-spec authorization_headers(AccessTokenRecord, Method, Endpoint, ClientContext) -> HeaderMap
                               when
                                   AccessTokenRecord :: access(),
                                   Method :: post | get,
                                   Endpoint :: uri_string:uri_string(),
                                   ClientContext :: oidcc_client_context:t(),
                                   HeaderMap :: #{binary() => binary()}.

Authorization headers

Generate a map of authorization headers to use when using the given access token to access an API endpoint.

Examples

{ok, ClientContext} =
    oidcc_client_context:from_configuration_worker(provider_name,
                                                    <<"client_id">>,
                                                    <<"client_secret">>),
%% Get Access Token record from somewhere
Headers =
    oidcc:authorization_headers(AccessTokenRecord, :get, Url, ClientContext).

-spec jwt_profile(Subject, ClientContext, Jwk, Opts) -> {ok, t()} | {error, error()}
                     when
                         Subject :: binary(),
                         ClientContext :: oidcc_client_context:t(),
                         Jwk :: jose_jwk:key(),
                         Opts :: jwt_profile_opts().

Retrieve JSON Web Token (JWT) Profile Token

See [https://datatracker.ietf.org/doc/html/rfc7523#section-4]

For a high level interface using {@link oidcc_provider_configuration_worker} see {@link oidcc:jwt_profile_token/6}.

Examples

{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

{ok, KeyJson} = file:read_file("jwt-profile.json"),
KeyMap = jose:decode(KeyJson),
Key = jose_jwk:from_pem(maps:get(<<"key">>, KeyMap)),

{ok, #oidcc_token{}} =
  oidcc_token:jwt_profile(<<"subject">>,
                          ClientContext,
                          Key,
                          #{scope => [<<"scope">>],
                            kid => maps:get(<<"keyId">>, KeyMap)}).

-spec refresh(RefreshToken, ClientContext, Opts) -> {ok, t()} | {error, error()}
                 when
                     RefreshToken :: binary(),
                     ClientContext :: oidcc_client_context:t(),
                     Opts :: refresh_opts();
             (Token, ClientContext, Opts) -> {ok, t()} | {error, error()}
                 when
                     Token :: oidcc_token:t(),
                     ClientContext :: oidcc_client_context:t(),
                     Opts :: refresh_opts_no_sub().

Refresh Token

For a high level interface using oidcc_provider_configuration_worker see oidcc:refresh_token/5.

Examples

{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

%% Get AuthCode from Redirect

{ok, Token} =
  oidcc_token:retrieve(AuthCode, ClientContext, #{
    redirect_uri => <<"https://example.com/callback">>}).

%% Later

{ok, #oidcc_token{}} =
  oidcc_token:refresh(Token,
                      ClientContext,
                      #{expected_subject => <<"sub_from_initial_id_token">>}).

-spec retrieve(AuthCode, ClientContext, Opts) -> {ok, t()} | {error, error()}
                  when
                      AuthCode :: binary(),
                      ClientContext :: oidcc_client_context:t(),
                      Opts :: retrieve_opts().

Retrieve the token using the authcode received before and directly validate the result.

The authcode was sent to the local endpoint by the OpenId Connect provider, using redirects.

For a high level interface using oidcc_provider_configuration_worker see oidcc:retrieve_token/5.

Examples

{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

%% Get AuthCode from Redirect

{ok, #oidcc_token{}} =
  oidcc:retrieve(AuthCode, ClientContext, #{
    redirect_uri => <<"https://example.com/callback">>}).

-spec validate_jarm(Response, ClientContext, Opts) -> {ok, oidcc_jwt_util:claims()} | {error, error()}
                       when
                           Response :: binary(),
                           ClientContext :: oidcc_client_context:t(),
                           Opts :: validate_jarm_opts().

Validate the JARM response, returning the valid claims as a map.

The response was sent to the local endpoint by the OpenId Connect provider, using redirects.

Examples

{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

%% Get Response from Redirect

{ok, #{<<"code">> := AuthCode}} =
  oidcc:validate_jarm(Response, ClientContext, #{}),

{ok, #oidcc_token{}} = oidcc:retrieve(AuthCode, ClientContext,
  #{redirect_uri => <<"https://redirect.example/">>}).

-spec validate_jwt(Jwt, ClientContext, Opts) -> {ok, Claims} | {error, error()}
                      when
                          Jwt :: binary(),
                          ClientContext :: oidcc_client_context:t(),
                          Opts :: validate_jwt_opts(),
                          Claims :: oidcc_jwt_util:claims().

Validate JWT

Validates a generic JWT (such as an access token) from the given provider. Useful if the issuer is shared between multiple applications, and the access token generated for a user at one client is used to validate their access at another client.

Examples

{ok, ClientContext} =
    oidcc_client_context:from_configuration_worker(provider_name,
                                                <<"client_id">>,
                                                <<"client_secret">>),
%% Get Jwt from Authorization header
{ok, Claims} =
    oidcc:validate_jwt(Jwt, ClientContext, Opts).