This is an automated email from the ASF dual-hosted git repository.

nickva pushed a commit to branch 3.5.x
in repository https://gitbox.apache.org/repos/asf/couchdb.git

commit e565b5383325f05154b006b0e16db2ffa06e8a17
Author: Robert Newson <[email protected]>
AuthorDate: Mon Jun 29 13:27:32 2026 +0100

    couch replication auth plugin for IBM IAM with refresh
    
    (cherry picked from commit cedae8ade2b635d092437d3eaaf2cff777e2df07)
---
 rel/overlay/etc/default.ini                        |  24 +-
 .../src/couch_replicator_auth_ibm.erl              | 718 +++++++++++++++++++++
 src/docs/src/config/replicator.rst                 |   5 +-
 src/docs/src/replication/replicator.rst            |  22 +
 4 files changed, 766 insertions(+), 3 deletions(-)

diff --git a/rel/overlay/etc/default.ini b/rel/overlay/etc/default.ini
index 11dab43c0..8de418095 100644
--- a/rel/overlay/etc/default.ini
+++ b/rel/overlay/etc/default.ini
@@ -758,8 +758,9 @@ partitioned||* = true
 ; particular endpoint (source or target). Normally couch_replicator_auth_noop
 ; would be used at the end of the list as a "catch-all". It doesn't do anything
 ; and effectively implements the previous behavior of using basic auth.
-; There are currently two plugins available:
+; There are currently three plugins available:
 ;   couch_replicator_auth_session - use _session cookie authentication
+;   couch_replicator_auth_ibm - use IBM's IAM service for authentication
 ;   couch_replicator_auth_noop - use basic authentication (previous default)
 ; Currently, the new _session cookie authentication is tried first, before
 ; falling back to the old basic authentication default:
@@ -801,6 +802,27 @@ partitioned||* = true
 ; if the database does not exist.
 ;_replicator = 100
 
+[replicator_auth_ibm]
+; How often to check the cached tokens for refresh or expiration.
+;check_interval_secs = 60
+
+; the number of seconds before expiration that a token refresh
+; should be attempted
+;early_refresh_secs = 300
+
+; A random number of seconds added to a refresh attempt
+;jitter_secs = 60
+
+; The number of seconds to wait before retrying a token acquistion
+; after an error
+;retry_secs = 10
+
+; request timeout for acquiring tokens
+;request_timeout_secs = 30
+
+; The URL to fetch tokens from
+;token_url = https://iam.cloud.ibm.com/identity/token
+
 [log]
 ; Possible log levels:
 ;  debug
diff --git a/src/couch_replicator/src/couch_replicator_auth_ibm.erl 
b/src/couch_replicator/src/couch_replicator_auth_ibm.erl
new file mode 100644
index 000000000..ed17080a0
--- /dev/null
+++ b/src/couch_replicator/src/couch_replicator_auth_ibm.erl
@@ -0,0 +1,718 @@
+% Licensed under the Apache License, Version 2.0 (the "License"); you may not
+% use this file except in compliance with the License. You may obtain a copy of
+% the License at
+%
+%   http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+% License for the specific language governing permissions and limitations under
+% the License.
+
+% This module allows a replication source or target to use an IAM api key for 
authentication.
+%
+% Features;
+%
+% Automatic refreshing of time-limited token before expiration
+% Deduplication - only one token will be acquired for each distinct IAM api key
+%
+% Implementation details
+%
+% As api keys are sensitive, the only copy of api keys is held in a private 
ETS table
+% owned by this module's gen_server. An opaque reference is returned to 
clients (this is
+% a message authentication code where the key is a non-persisted value 
generated by the
+% gen_server)
+
+-module(couch_replicator_auth_ibm).
+
+-behaviour(couch_replicator_auth).
+-behaviour(gen_server).
+-behaviour(config_listener).
+
+-export([
+    sup_initialize/0,
+    sup_cleanup/1,
+    initialize/1,
+    update_headers/2,
+    handle_response/3,
+    cleanup/1
+]).
+
+%% gen_server callbacks
+-export([
+    init/1,
+    handle_call/3,
+    handle_cast/2,
+    handle_info/2,
+    terminate/2
+]).
+
+% config_listener callbacks
+-export([
+    handle_config_change/5,
+    handle_config_terminate/3
+]).
+
+-include_lib("couch_replicator/include/couch_replicator_api_wrap.hrl").
+
+-define(MINUTE, 60).
+-define(PUBLIC, couch_replicator_auth_ibm_public).
+-define(PRIVATE, couch_replicator_auth_ibm_private).
+
+-record(worker_state, {
+    api_key_mac,
+    last_used
+}).
+
+-record(state, {
+    mac_key,
+    token_url
+}).
+
+-record(public_entry, {
+    api_key_mac,
+    token
+}).
+
+-record(private_entry, {
+    api_key_mac,
+    api_key_uuid,
+    api_key,
+    % Number of seconds (counted since January 1st, 1970) until the IAM access 
token will expire.
+    expires_at_secs,
+    acquire_mref,
+    last_used,
+    last_updated,
+    waiters = []
+}).
+
+%% callbacks
+
+sup_initialize() ->
+    {ok, _} = gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).
+
+sup_cleanup(_) ->
+    ok = gen_server:stop(?MODULE).
+
+initialize(#httpdb{} = HttpDb) ->
+    case extract_api_key(HttpDb) of
+        {ok, APIKey} ->
+            case gen_server:call(?MODULE, {register, APIKey}) of
+                {ok, APIKeyMAC} ->
+                    WorkerState = #worker_state{api_key_mac = APIKeyMAC, 
last_used = now_secs()},
+                    {ok, HttpDb, WorkerState};
+                {error, Reason} ->
+                    {error, Reason}
+            end;
+        {error, _} ->
+            ignore
+    end.
+
+update_headers(WorkerState, Headers) when is_list(Headers) ->
+    case get_token(WorkerState) of
+        {ok, Token} ->
+            {
+                [{~"Authorization", <<"Bearer ", Token/binary>>} | Headers],
+                update_last_used(WorkerState)
+            };
+        {error, Reason} ->
+            couch_log:warning("Error when retrieving token: ~p", [Reason]),
+            {Headers, WorkerState}
+    end.
+
+handle_response(WorkerState, _StatusCode, _Headers) ->
+    {continue, WorkerState}.
+
+cleanup(_WorkerState) ->
+    ok.
+
+get_token(#worker_state{} = WorkerState) ->
+    #worker_state{api_key_mac = APIKeyMAC} = WorkerState,
+    case ets:lookup(?PUBLIC, APIKeyMAC) of
+        [#public_entry{token = Token}] when is_binary(Token) ->
+            {ok, Token};
+        [#public_entry{}] ->
+            gen_server:call(?MODULE, {get_token, APIKeyMAC}, 
request_timeout_ms());
+        [] ->
+            {error, no_token}
+    end.
+
+update_last_used(#worker_state{} = WorkerState) ->
+    #worker_state{api_key_mac = APIKeyMAC, last_used = LastUsed} = WorkerState,
+    Now = now_secs(),
+    %% only send a message once per minute at most.
+    case Now - LastUsed > ?MINUTE of
+        true ->
+            gen_server:cast(?MODULE, {update_last_used, APIKeyMAC}),
+            WorkerState#worker_state{last_used = Now};
+        false ->
+            WorkerState
+    end.
+
+%% gen_server callbacks.
+
+init(_) ->
+    case token_url() of
+        {ok, TokenUrl} ->
+            ?PUBLIC = ets:new(?PUBLIC, [protected, {keypos, 
#public_entry.api_key_mac}, named_table]),
+            ?PRIVATE = ets:new(?PRIVATE, [
+                private, {keypos, #private_entry.api_key_mac}, named_table
+            ]),
+            ok = config:listen_for_changes(?MODULE, nil),
+            erlang:send_after(check_interval_ms(), self(), 
refresh_expire_check),
+            {ok, #state{
+                mac_key = crypto:strong_rand_bytes(32),
+                token_url = TokenUrl
+            }};
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+handle_call({register, APIKey}, _From, State) ->
+    case ets:match_object(?PRIVATE, #private_entry{api_key = APIKey, _ = '_'}) 
of
+        [#private_entry{} = Entry] ->
+            {reply, {ok, Entry#private_entry.api_key_mac}, State};
+        [] ->
+            AcquireMRef = acquire_token(APIKey, State),
+            APIKeyMAC = mac(State#state.mac_key, APIKey),
+            true = ets:insert_new(?PUBLIC, #public_entry{
+                api_key_mac = APIKeyMAC
+            }),
+            true = ets:insert_new(?PRIVATE, #private_entry{
+                api_key = APIKey,
+                api_key_mac = APIKeyMAC,
+                acquire_mref = AcquireMRef,
+                last_used = now_secs(),
+                last_updated = 0
+            }),
+            {reply, {ok, APIKeyMAC}, State}
+    end;
+handle_call({get_token, APIKeyMAC}, From, State) ->
+    case ets:lookup(?PUBLIC, APIKeyMAC) of
+        [] ->
+            {reply, {error, no_such_api_key}, State};
+        [#public_entry{token = Token}] when Token /= undefined ->
+            {reply, {ok, Token}, State};
+        [#public_entry{}] ->
+            [#private_entry{} = Entry] = ets:lookup(?PRIVATE, APIKeyMAC),
+            ets:insert(?PRIVATE, Entry#private_entry{waiters = [From | 
Entry#private_entry.waiters]}),
+            if
+                Entry#private_entry.acquire_mref /= undefined ->
+                    ok;
+                true ->
+                    self() ! {refresh_token, APIKeyMAC}
+            end,
+            {noreply, State}
+    end;
+handle_call(_Msg, _From, State) ->
+    {reply, {error, unexpected_msg}, State}.
+
+handle_cast({update_last_used, APIKeyMAC}, State) ->
+    ets:update_element(?PRIVATE, APIKeyMAC, {#private_entry.last_used, 
now_secs()}),
+    {noreply, State};
+handle_cast(_Msg, State) ->
+    {noreply, State}.
+
+handle_info({refresh_token, APIKeyMAC}, State) ->
+    case ets:lookup(?PRIVATE, APIKeyMAC) of
+        [] ->
+            ok;
+        [#private_entry{acquire_mref = undefined} = Entry] ->
+            case Entry#private_entry.last_used > 
Entry#private_entry.last_updated of
+                true ->
+                    couch_log:notice("~p: refreshing api key ~s", [
+                        ?MODULE, Entry#private_entry.api_key_uuid
+                    ]),
+                    AcquireMRef = acquire_token(Entry#private_entry.api_key, 
State),
+                    ets:insert(?PRIVATE, Entry#private_entry{acquire_mref = 
AcquireMRef});
+                false ->
+                    %% let it expire and free any waiters
+                    reply_and_reset(Entry, {error, token_expiring})
+            end;
+        [#private_entry{}] ->
+            ok
+    end,
+    {noreply, State};
+handle_info({expire_api_key_entry, APIKeyMAC}, State) ->
+    NowSecs = now_secs(),
+    case ets:lookup(?PRIVATE, APIKeyMAC) of
+        [] ->
+            ok;
+        [#private_entry{expires_at_secs = ExpiresAtSecs} = Entry] when 
ExpiresAtSecs =< NowSecs ->
+            couch_log:warning("~p: api key entry ~s passed expiration time", [
+                ?MODULE, Entry#private_entry.api_key_uuid
+            ]),
+            ets:delete(?PUBLIC, APIKeyMAC),
+            ets:delete(?PRIVATE, APIKeyMAC),
+            if
+                Entry#private_entry.acquire_mref /= undefined ->
+                    demonitor(Entry#private_entry.acquire_mref, [flush]);
+                true ->
+                    ok
+            end,
+            reply_all(Entry#private_entry.waiters, {error, 
expired_api_key_entry});
+        % was refreshed
+        [#private_entry{}] ->
+            ok
+    end,
+    {noreply, State};
+handle_info(refresh_expire_check, #state{} = State) ->
+    NowSecs = now_secs(),
+    EarlyRefreshSecs = early_refresh_secs(),
+    Matches = ets:select(?PRIVATE, [
+        {
+            #private_entry{api_key_mac = '$1', expires_at_secs = '$2', _ = 
'_'},
+            [{is_integer, '$2'}, {'=<', '$2', NowSecs + EarlyRefreshSecs}],
+            [['$1', '$2']]
+        }
+    ]),
+    lists:foreach(
+        fun([APIKeyMAC, ExpiresAtSecs]) ->
+            if
+                NowSecs >= ExpiresAtSecs ->
+                    self() ! {expire_api_key_entry, APIKeyMAC};
+                true ->
+                    erlang:send_after(jitter_ms(), self(), {refresh_token, 
APIKeyMAC})
+            end
+        end,
+        Matches
+    ),
+    erlang:send_after(check_interval_ms(), self(), refresh_expire_check),
+    {noreply, State};
+handle_info(
+    {'DOWN', AcquireMRef, process, _AcquirePid, {ok, StatusCode, 
_ResponseHeaders, ResponseBody}},
+    #state{} = State
+) ->
+    case match_on_acquire_mref(AcquireMRef) of
+        [#private_entry{} = Entry] ->
+            case StatusCode of
+                200 ->
+                    case decode_iam_response(ResponseBody) of
+                        {ok, Token, ExpiresAtSecs} ->
+                            UUID = api_key_uuid(Token),
+                            couch_log:notice("~p: refreshed api key ~s", [
+                                ?MODULE, UUID
+                            ]),
+                            true = ets:update_element(?PUBLIC, 
Entry#private_entry.api_key_mac, {
+                                #public_entry.token, Token
+                            }),
+                            reply_and_reset(
+                                Entry#private_entry{
+                                    api_key_uuid = UUID,
+                                    expires_at_secs = ExpiresAtSecs,
+                                    last_updated = now_secs()
+                                },
+                                {ok, Token}
+                            );
+                        {error, Reason} ->
+                            couch_log:notice("~p: failed to refresh api key 
~s: ~p", [
+                                ?MODULE, Entry#private_entry.api_key_uuid, 
Reason
+                            ]),
+                            reply_and_reset(Entry, {error, Reason})
+                    end;
+                StatusCode ->
+                    ErrorMessage = extract_error_message(ResponseBody),
+                    couch_log:notice("~p: failed to refresh api key ~s: ~p", [
+                        ?MODULE, Entry#private_entry.api_key_uuid, ErrorMessage
+                    ]),
+                    case StatusCode of
+                        500 ->
+                            erlang:send_after(
+                                retry_ms(),
+                                self(),
+                                {refresh_token, 
Entry#private_entry.api_key_mac}
+                            );
+                        _ ->
+                            ok
+                    end,
+                    reply_and_reset(Entry, {error, ErrorMessage})
+            end;
+        [] ->
+            ok
+    end,
+    {noreply, State};
+handle_info({'DOWN', AcquireMRef, process, _AcquirePid, Reason}, #state{} = 
State) ->
+    %% acquire process exited with {error, Reason} or died some other way
+    %% we don't care how, we always clean up after it
+    case match_on_acquire_mref(AcquireMRef) of
+        [#private_entry{} = Entry] ->
+            reply_and_reset(Entry, acquire_error(Reason));
+        [] ->
+            ok
+    end,
+    {noreply, State};
+handle_info(restart_config_listener, State) ->
+    ok = config:listen_for_changes(?MODULE, nil),
+    {noreply, State};
+handle_info(token_url_change, State) ->
+    case token_url() of
+        {ok, TokenUrl} ->
+            %% picked up by the next request, nothing to reconnect
+            {noreply, State#state{token_url = TokenUrl}};
+        {error, Reason} ->
+            {stop, Reason, State}
+    end;
+handle_info(Msg, State) ->
+    couch_log:warning("~p: unexpected info ~p", [?MODULE, Msg]),
+    {noreply, State}.
+
+terminate(_Reason, _State) ->
+    ets:foldl(
+        fun(#private_entry{} = Entry, Acc) ->
+            lists:foreach(
+                fun(W) -> gen_server:reply(W, {error, terminated}) end,
+                Entry#private_entry.waiters
+            ),
+            Acc
+        end,
+        ok,
+        ?PRIVATE
+    ).
+
+%% config_listener functions.
+
+handle_config_change("replicator_auth_ibm", "token_url", _, _, State) ->
+    ?MODULE ! token_url_change,
+    {ok, State};
+handle_config_change(_, _, _, _, State) ->
+    {ok, State}.
+
+handle_config_terminate(_, stop, _) ->
+    ok;
+handle_config_terminate(_Server, _Reason, _State) ->
+    erlang:send_after(5000, ?MODULE, restart_config_listener).
+
+%% private functions.
+
+now_secs() ->
+    erlang:system_time(second).
+
+extract_api_key(#httpdb{auth_props = AuthProps}) ->
+    case proplists:get_value(~"ibm", AuthProps) of
+        {IBMProps} when is_list(IBMProps) ->
+            case proplists:get_value(~"apikey", IBMProps) of
+                APIKey when is_binary(APIKey), byte_size(APIKey) > 0 ->
+                    {ok, APIKey};
+                _ ->
+                    {error, missing_api_key}
+            end;
+        _ ->
+            {error, missing_api_key}
+    end.
+
+acquire_token(APIKey, #state{token_url = Url}) ->
+    Headers = [
+        {~"content-type", ~"application/x-www-form-urlencoded"}
+    ],
+    Body = mochiweb_util:urlencode([
+        {~"grant_type", ~"urn:ibm:params:oauth:grant-type:apikey"},
+        {~"response_type", ~"cloud_iam"},
+        {~"apikey", APIKey}
+    ]),
+    {_Pid, Ref} = spawn_monitor(fun() ->
+        exit(
+            try
+                post(Url, Headers, Body, request_timeout_ms())
+            catch
+                Tag:Err -> {error, {Tag, Err}}
+            end
+        )
+    end),
+    Ref.
+
+post(Url, ReqHeaders, ReqBody, Timeout) ->
+    Opts = #{
+        timeout => Timeout,
+        tls_opts => [{cacerts, couch_replicator_utils:cacert_get()}]
+    },
+    couch_gun:req(post, Url, ReqHeaders, ReqBody, Opts).
+
+decode_iam_response(ResponseBody) ->
+    try jiffy:decode(ResponseBody, [return_maps]) of
+        Decoded when is_map(Decoded) ->
+            Token = maps:get(~"access_token", Decoded, undefined),
+            ExpiresAtSecs = maps:get(~"expiration", Decoded, undefined),
+            if
+                is_binary(Token) andalso is_integer(ExpiresAtSecs) ->
+                    {ok, Token, ExpiresAtSecs};
+                true ->
+                    {error, malformed_iam_response}
+            end;
+        _ ->
+            {error, malformed_iam_response}
+    catch
+        _:_ ->
+            {error, malformed_iam_response}
+    end.
+
+extract_error_message(ResponseBody) ->
+    try jiffy:decode(ResponseBody, [return_maps]) of
+        #{~"errorCode" := ErrorCode, ~"errorMessage" := ErrorMessage} ->
+            {ErrorCode, ErrorMessage};
+        _ ->
+            malformed_iam_response
+    catch
+        _:_ ->
+            malformed_iam_response
+    end.
+
+api_key_uuid(EncodedToken) when is_binary(EncodedToken) ->
+    case binary:split(EncodedToken, ~".", [global]) of
+        [_Header, Payload, _Signature] ->
+            case b64url:decode(Payload) of
+                {error, _Reason} ->
+                    ~"";
+                Decoded when is_binary(Decoded) ->
+                    try jiffy:decode(Decoded, [return_maps]) of
+                        #{~"apikey_uuid" := UUID} ->
+                            UUID;
+                        _ ->
+                            ~""
+                    catch
+                        _:_ ->
+                            ~""
+                    end
+            end;
+        _ ->
+            ~""
+    end.
+
+-spec token_url() -> {ok, string()} | {error, term()}.
+token_url() ->
+    Url = config:get(
+        "replicator_auth_ibm", "token_url", 
"https://iam.cloud.ibm.com/identity/token";
+    ),
+    case couch_gun:parse_url(Url) of
+        {ok, #{}} ->
+            {ok, Url};
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+match_on_acquire_mref(AcquireMRef) ->
+    ets:match_object(?PRIVATE, #private_entry{acquire_mref = AcquireMRef, _ = 
'_'}).
+
+acquire_error({error, _} = Error) ->
+    Error;
+acquire_error(Reason) ->
+    {error, Reason}.
+
+-spec reply_and_reset(Entry :: #private_entry{}, Reply :: term()) -> ok.
+reply_and_reset(#private_entry{} = Entry, Reply) ->
+    ets:insert(?PRIVATE, Entry#private_entry{
+        acquire_mref = undefined,
+        waiters = []
+    }),
+    reply_all(Entry#private_entry.waiters, Reply).
+
+-spec reply_all(Waiters :: [gen_server:from()], Reply :: term()) -> ok.
+reply_all(Waiters, Reply) ->
+    lists:foreach(
+        fun(W) -> gen_server:reply(W, Reply) end,
+        Waiters
+    ).
+
+mac(Key, Data) when is_binary(Key), is_binary(Data) ->
+    crypto:mac(hmac, sha256, Key, Data).
+
+request_timeout_ms() ->
+    max(0, 1000 * config:get_integer("replicator_auth_ibm", 
"request_timeout_secs", 30)).
+
+check_interval_ms() ->
+    max(0, 1000 * config:get_integer("replicator_auth_ibm", 
"check_interval_secs", 60)).
+
+early_refresh_secs() ->
+    max(0, config:get_integer("replicator_auth_ibm", "early_refresh_secs", 
300)).
+
+jitter_ms() ->
+    JitterMS = max(0, 1000 * config:get_integer("replicator_auth_ibm", 
"jitter_secs", 60)),
+    case JitterMS of
+        0 -> 0;
+        _ -> rand:uniform(JitterMS)
+    end.
+
+retry_ms() ->
+    max(0, 1000 * config:get_integer("replicator_auth_ibm", "retry_secs", 10)).
+
+-ifdef(TEST).
+-include_lib("eunit/include/eunit.hrl").
+
+extract_api_key_test() ->
+    ?assertEqual(
+        {ok, ~"fake_api_key"},
+        extract_api_key(#httpdb{auth_props = [{~"ibm", {[{~"apikey", 
~"fake_api_key"}]}}]})
+    ),
+    ?assertEqual({error, missing_api_key}, extract_api_key(#httpdb{auth_props 
= []})).
+
+server_test_() ->
+    {
+        "IAM replicator auth server tests",
+        {setup, fun start_gun/0,
+            {
+                foreach,
+                fun start/0,
+                fun stop/1,
+                [
+                    fun test_get_token/1,
+                    fun test_initialize/1,
+                    fun test_update_headers/1,
+                    fun test_refresh_token/1,
+                    fun test_token_expiration/1
+                ]
+            }}
+    }.
+
+start_gun() ->
+    application:ensure_all_started(gun).
+
+start() ->
+    {IAMPid, Port} = fake_iam_server_start(),
+    mock_config(Port),
+    {ok, _} = sup_initialize(),
+    IAMPid.
+
+stop(IAMPid) ->
+    sup_cleanup(undefined),
+    fake_iam_server_stop(IAMPid),
+    meck:unload().
+
+test_get_token(_) ->
+    ?_test(
+        begin
+            ?assertMatch({error, no_token}, 
get_token(#worker_state{api_key_mac = ~"foo"})),
+            Reply1 = gen_server:call(?MODULE, {register, ~"fake_api_key"}),
+            ?assertMatch({ok, Bin} when is_binary(Bin), Reply1),
+            {ok, APIKeyMAC} = Reply1,
+            ?assertMatch(
+                {ok, Bin} when is_binary(Bin),
+                get_token(#worker_state{api_key_mac = APIKeyMAC, last_used = 
now_secs()})
+            )
+        end
+    ).
+
+test_initialize(_) ->
+    ?_test(
+        begin
+            HttpDb = #httpdb{auth_props = [{~"ibm", {[{~"apikey", 
~"fake_api_key"}]}}]},
+            Result2 = initialize(HttpDb),
+            ?assertMatch(
+                {ok, HttpDb, #worker_state{api_key_mac = MAC}} when 
is_binary(MAC), Result2
+            )
+        end
+    ).
+
+test_update_headers(_) ->
+    ?_test(
+        begin
+            ?assertMatch(
+                {[dummy], _},
+                update_headers(
+                    #worker_state{api_key_mac = ~"fake_api_key_mac", last_used 
= now_secs()}, [
+                        dummy
+                    ]
+                )
+            ),
+            {ok, APIKeyMAC} = gen_server:call(?MODULE, {register, 
~"fake_api_key"}),
+            ?assertMatch(
+                {[{~"Authorization", <<"Bearer ", _/binary>>}, dummy], _},
+                update_headers(#worker_state{api_key_mac = APIKeyMAC, 
last_used = now_secs()}, [
+                    dummy
+                ])
+            )
+        end
+    ).
+
+test_refresh_token(_) ->
+    ?_test(
+        begin
+            {ok, APIKeyMAC} = gen_server:call(?MODULE, {register, 
~"fake_api_key"}),
+            {ok, Token1} = gen_server:call(?MODULE, {get_token, APIKeyMAC}),
+            timer:sleep(1000),
+            gen_server:cast(?MODULE, {update_last_used, APIKeyMAC}),
+            ?MODULE ! {refresh_token, APIKeyMAC},
+            wait_for_refresh(APIKeyMAC, Token1, 20),
+            {ok, Token2} = gen_server:call(?MODULE, {get_token, APIKeyMAC}),
+            ?assertNotEqual(Token1, Token2)
+        end
+    ).
+
+wait_for_refresh(_APIKeyMAC, OriginalToken, 0) ->
+    OriginalToken;
+wait_for_refresh(APIKeyMAC, OriginalToken, RetriesLeft) ->
+    {ok, NewToken} = gen_server:call(?MODULE, {get_token, APIKeyMAC}),
+    if
+        OriginalToken == NewToken ->
+            timer:sleep(100),
+            wait_for_refresh(APIKeyMAC, OriginalToken, RetriesLeft - 1);
+        true ->
+            NewToken
+    end.
+
+test_token_expiration(_) ->
+    ?_test(
+        begin
+            {ok, APIKeyMAC} = gen_server:call(?MODULE, {register, 
~"fake_api_key"}),
+            ?assertMatch(
+                {ok, _}, get_token(#worker_state{api_key_mac = APIKeyMAC, 
last_used = now_secs()})
+            ),
+            timer:sleep(4000),
+            ?assertMatch(
+                {error, no_token},
+                get_token(#worker_state{api_key_mac = APIKeyMAC, last_used = 
now_secs()})
+            )
+        end
+    ).
+
+handle_response_test() ->
+    WorkerState = #worker_state{},
+    ?assertEqual({continue, WorkerState}, handle_response(WorkerState, 200, 
[])).
+
+cleanup_test() ->
+    ?assertEqual(ok, cleanup(#worker_state{})).
+
+token_url_test() ->
+    try
+        meck:expect(config, get, fun("replicator_auth_ibm", "token_url", _) ->
+            "https://nohost.invalid";
+        end),
+        ?assertEqual({ok, "https://nohost.invalid"}, token_url()),
+        meck:expect(config, get, fun("replicator_auth_ibm", "token_url", _) -> 
"https://"; end),
+        ?assertEqual({error, invalid_uri}, token_url())
+    after
+        meck:unload()
+    end.
+
+mock_config(Port) ->
+    meck:expect(config, listen_for_changes, fun(_, _) -> ok end),
+    meck:expect(config, get, fun("replicator_auth_ibm", "token_url", _) ->
+        "http://localhost:"; ++ integer_to_list(Port) ++ "/identity/token"
+    end),
+    meck:expect(config, get_integer, fun
+        ("replicator_auth_ibm", "check_interval_secs", _) -> 1;
+        ("replicator_auth_ibm", "early_refresh_secs", _) -> 1;
+        ("replicator_auth_ibm", "jitter_secs", _) -> 0;
+        ("replicator_auth_ibm", "retry_secs", _) -> 1;
+        (_Section, _Key, Default) -> Default
+    end).
+
+fake_iam_server_start() ->
+    {ok, Pid} = mochiweb_http:start([{port, 0}, {loop, fun 
fake_iam_server_loop/1}]),
+    {Pid, mochiweb_socket_server:get(Pid, port)}.
+
+fake_iam_server_stop(Pid) ->
+    mochiweb_http:stop(Pid).
+
+fake_iam_server_loop(Req) ->
+    case {mochiweb_request:get(method, Req), mochiweb_request:get(path, Req)} 
of
+        {'POST', "/identity/token"} ->
+            RespBody = #{
+                ~"access_token" => 
binary:encode_hex(crypto:strong_rand_bytes(16)),
+                ~"expiration" => 2 + now_secs()
+            },
+            mochiweb_request:ok({"application/json", [], 
jiffy:encode(RespBody)}, Req);
+        _ ->
+            mochiweb_request:not_found(Req)
+    end.
+
+-endif.
diff --git a/src/docs/src/config/replicator.rst 
b/src/docs/src/config/replicator.rst
index ceb3eebba..b86d018d6 100644
--- a/src/docs/src/config/replicator.rst
+++ b/src/docs/src/config/replicator.rst
@@ -370,9 +370,10 @@ Replicator Database Configuration
 
         List of replicator client authentication plugins. Plugins will
         be tried in order and the first to initialize successfully will
-        be used. By default there are two plugins available:
+        be used. By default there are three plugins available:
         `couch_replicator_auth_session` implementing session (cookie)
-        authentication, and `couch_replicator_auth_noop` implementing basic
+        authentication, `couch_replicator_auth_ibm` integrating
+        with IBM's IAM service and `couch_replicator_auth_noop` implementing 
basic
         authentication. For backwards compatibility, the no-op plugin should 
be used at
         the end of the plugin list::
 
diff --git a/src/docs/src/replication/replicator.rst 
b/src/docs/src/replication/replicator.rst
index 3d8b6bf7b..92a74f612 100644
--- a/src/docs/src/replication/replicator.rst
+++ b/src/docs/src/replication/replicator.rst
@@ -809,6 +809,28 @@ they are used. If they are not, then URL userinfo is 
checked. If credentials
 are found there, then those credentials are used, otherwise basic auth header
 is used.
 
+Using an IBM IAM apikey
+=======================
+
+If you've enabled the optional `couch_replicator_auth_ibm`
+replicator authentication plugin you can specify an IBM IAM apikey in
+your source or target as follows;
+
+    .. code-block:: javascript
+
+        {
+            "target": {
+                "url": "http://someurl.com/mydb";,
+                "auth": {
+                    "ibm": {
+                        "apikey": "$apikey"
+                     }
+                }
+            },
+            ...
+        }
+
+
 Replicate Winning Revisions Only
 ================================
 

Reply via email to