You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by rn...@apache.org on 2026/07/17 12:23:21 UTC
(couchdb) 01/01: couch replication auth plugin for IBM IAM with refresh
This is an automated email from the ASF dual-hosted git repository.
rnewson pushed a commit to branch ibm-iam-auth
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 24cbbb43a744ef4ae26ef470b4482c55a15a59c9
Author: Robert Newson <rn...@apache.org>
AuthorDate: Mon Jun 29 13:27:32 2026 +0100
couch replication auth plugin for IBM IAM with refresh
---
rel/overlay/etc/default.ini | 5 +-
.../src/couch_replicator_auth_ibm_iam.erl | 178 +++++++++++++++++++++
src/docs/src/config/replicator.rst | 5 +-
src/docs/src/replication/replicator.rst | 22 +++
4 files changed, 206 insertions(+), 4 deletions(-)
diff --git a/rel/overlay/etc/default.ini b/rel/overlay/etc/default.ini
index aac8ff584..4a298fe28 100644
--- a/rel/overlay/etc/default.ini
+++ b/rel/overlay/etc/default.ini
@@ -803,12 +803,13 @@ 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_iam - 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:
-;auth_plugins = couch_replicator_auth_session,couch_replicator_auth_noop
+auth_plugins = couch_replicator_auth_session,couch_replicator_auth_noop
; To restore the old behaviour, use the following value:
;auth_plugins = couch_replicator_auth_noop
diff --git a/src/couch_replicator/src/couch_replicator_auth_ibm_iam.erl b/src/couch_replicator/src/couch_replicator_auth_ibm_iam.erl
new file mode 100644
index 000000000..d291205c1
--- /dev/null
+++ b/src/couch_replicator/src/couch_replicator_auth_ibm_iam.erl
@@ -0,0 +1,178 @@
+% 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.
+
+-module(couch_replicator_auth_ibm_iam).
+
+-behaviour(couch_replicator_auth).
+
+-export([
+ initialize/1,
+ update_headers/2,
+ handle_response/3,
+ cleanup/1
+]).
+
+-export([token_acquirer/1]).
+
+-define(EARLY_REFRESH_MS, 5 * 60 * 1000).
+
+-include_lib("couch_replicator/include/couch_replicator_api_wrap.hrl").
+-include_lib("ibrowse/include/ibrowse.hrl").
+
+-record(state, {
+ acquirer,
+ apikey :: binary(),
+ refresh_at_ms,
+ token :: list()
+}).
+
+%% callbacks
+
+initialize(#httpdb{} = HttpDb) ->
+ case extract_apikey(HttpDb) of
+ ignore ->
+ ignore;
+ {ok, APIKey} ->
+ Acquirer = spawn_link(?MODULE, token_acquirer, [APIKey]),
+ {ok, HttpDb, #state{apikey = APIKey, acquirer = Acquirer}}
+ end.
+
+update_headers(#state{} = State0, Headers) when is_list(Headers) ->
+ State1 = get_current_token(State0),
+ {[{"Authorization", "Bearer " ++ State1#state.token} | Headers], State1}.
+
+get_current_token(#state{} = State) ->
+ NowMs = now_ms(),
+ if
+ State#state.token == undefined ->
+ State#state.acquirer ! {get_token, self()};
+ NowMs >= State#state.refresh_at_ms ->
+ State#state.acquirer ! {get_token, self()}
+ end,
+ receive
+ {token, _RefreshAtMs, Token} when Token == undefined ->
+ timer:sleep(1000),
+ get_current_token(State);
+ {token, RefreshAtMs, Token} ->
+ State#state{refresh_at_ms = RefreshAtMs, token = Token}
+ end.
+
+handle_response(#state{} = State, StatusCode, Headers) when
+ is_integer(StatusCode), is_list(Headers)
+->
+ {continue, State}.
+
+cleanup(#state{} = State) ->
+ unlink(State#state.acquirer),
+ exit(State#state.acquirer, kill),
+ ok.
+
+%% private functions
+
+-record(acquirer, {
+ apikey,
+ ibrowse_req_id,
+ refresh_at_ms,
+ token
+}).
+
+token_acquirer(APIKey) when is_binary(APIKey) ->
+ case send_req(APIKey) of
+ {error, Reason} ->
+ exit(Reason);
+ {ibrowse_req_id, NewReqId} ->
+ token_acquirer_loop(#acquirer{apikey = APIKey, ibrowse_req_id = NewReqId})
+ end.
+
+token_acquirer_loop(#acquirer{ibrowse_req_id = ReqId} = Acquirer) ->
+ receive
+ refresh ->
+ case send_req(Acquirer#acquirer.apikey) of
+ {error, Reason} ->
+ exit(Reason);
+ {ibrowse_req_id, NewReqId} ->
+ token_acquirer_loop(Acquirer#acquirer{ibrowse_req_id = NewReqId})
+ end;
+ {get_token, From} ->
+ From ! {token, Acquirer#acquirer.refresh_at_ms, Acquirer#acquirer.token},
+ token_acquirer_loop(Acquirer);
+ {ibrowse_async_headers, ReqId, "200", _ResponseHeaders} ->
+ token_acquirer_loop(Acquirer);
+ {ibrowse_async_headers, ReqId, "401", _ResponseHeaders} ->
+ exit(unauthorized);
+ {ibrowse_async_headers, ReqId, "403", _ResponseHeaders} ->
+ exit(forbidden);
+ {ibrowse_async_headers, ReqId, "500", _ResponseHeaders} ->
+ erlang:send_after(10000, self(), refresh),
+ token_acquirer_loop(Acquirer#acquirer{ibrowse_req_id = undefined});
+ {ibrowse_async_headers, ReqId, StatusCode, _ResponseHeaders} ->
+ exit(StatusCode);
+ {ibrowse_async_response, ReqId, ResponseBody} ->
+ {ok, Token, ExpiresInSecs} = decode_iam_response(ResponseBody),
+ RefreshAtMs = now_ms() + sec_to_ms(ExpiresInSecs) - ?EARLY_REFRESH_MS,
+ RefreshInMs = sec_to_ms(ExpiresInSecs) - ?EARLY_REFRESH_MS,
+ erlang:send_after(RefreshInMs, self(), refresh),
+ token_acquirer_loop(Acquirer#acquirer{
+ ibrowse_req_id = undefined, refresh_at_ms = RefreshAtMs, token = Token
+ });
+ {ibrowse_async_response_end, ReqId} ->
+ token_acquirer_loop(Acquirer#acquirer{ibrowse_req_id = undefined});
+ {ibrowse_async_response_timeout, ReqId} ->
+ erlang:send_after(10000, self(), refresh),
+ token_acquirer_loop(Acquirer#acquirer{ibrowse_req_id = undefined});
+ %% consume ibrowse responses for stale requests
+ {ibrowse_async_headers, _OtherReqId, _StatusCode, _ResponseHeaders} ->
+ token_acquirer_loop(Acquirer);
+ {ibrowse_async_response, _OtherReqId} ->
+ token_acquirer_loop(Acquirer);
+ {ibrowse_async_response_end, _OtherReqId} ->
+ token_acquirer_loop(Acquirer);
+ {ibrowse_async_response_timeout, _OtherReqId} ->
+ token_acquirer_loop(Acquirer)
+ end.
+
+now_ms() ->
+ os:system_time(millisecond).
+
+sec_to_ms(Secs) ->
+ erlang:convert_time_unit(Secs, second, millisecond).
+
+extract_apikey(#httpdb{auth_props = AuthProps}) ->
+ case proplists:get_value(<<"ibm">>, AuthProps) of
+ undefined ->
+ ignore;
+ {IBMProps} ->
+ case proplists:get_value(<<"apikey">>, IBMProps) of
+ undefined ->
+ {error, missing_apikey};
+ ApiKey ->
+ {ok, ApiKey}
+ end
+ end.
+
+send_req(APIKey) ->
+ Body =
+ <<"grant_type=urn:ibm:params:oauth:grant-type:apikey&response_type=cloud_iam&apikey=",
+ APIKey/binary>>,
+ Options = [{stream_to, self()}, {ssl_options, [{cacerts, public_key:cacerts_get()}]}],
+ ibrowse:send_req(token_url(), [], post, Body, Options).
+
+decode_iam_response(ResponseBody) ->
+ #{
+ <<"token_type">> := <<"Bearer">>,
+ <<"access_token">> := Token,
+ <<"expires_in">> := ExpiresInSecs
+ } = jiffy:decode(ResponseBody, [return_maps]),
+ {ok, binary_to_list(Token), ExpiresInSecs}.
+
+token_url() ->
+ config:get("ibm_iam", "token_url", "https://iam.cloud.ibm.com/identity/token").
diff --git a/src/docs/src/config/replicator.rst b/src/docs/src/config/replicator.rst
index ceb3eebba..fd6b5d9a4 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_iam` 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..a3c0c8835 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_auth`
+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
================================