View Source oidcc_token (Oidcc v3.0.0-alpha.1)

Facilitate OpenID Code/Token Exchanges

Link to this section Summary

Types

Access Token Wrapper

Refresh Token Wrapper

Options for refreshing a token

Options for retrieving a token

t/0

Token Response Wrapper

Functions

Retrieve Client Credential Token

Retrieve JSON Web Token (JWT) Profile Token

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

Link to this section Types

-type access() :: #oidcc_token_access{token :: binary(), expires :: pos_integer() | undefined}.

Access Token Wrapper

fields

Fields

  • token - The retrieved token
  • expires - Timestamp when token will expire
Link to this type

client_credentials_opts/0

View Source
-type client_credentials_opts() ::
    #{scope => oidcc_scope:scopes(),
      refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
      request_opts => oidcc_http_util:request_opts()}.
-type error() ::
    {missing_claim, MissingClaim :: binary(), Claims :: oidcc_jwt_util:claims()} |
    bad_access_token_hash | sub_invalid |
    {none_alg_used, NoneClaims :: oidcc_jwt_util:claims()} |
    {grant_type_not_supported,
     authorization_code | refresh_token | jwt_bearer | client_credentials} |
    oidcc_jwt_util:error() |
    oidcc_http_util:error().
-type id() :: #oidcc_token_id{token :: binary(), claims :: oidcc_jwt_util:claims()}.
-type jwt_profile_opts() ::
    #{scope => oidcc_scope:scopes(),
      refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
      request_opts => oidcc_http_util:request_opts(),
      kid => binary()}.
-type pkce() :: #{verifier := binary()}.
-type refresh() :: #oidcc_token_refresh{token :: binary()}.

Refresh Token Wrapper

fields

Fields

  • token - The retrieved token
-type refresh_opts() ::
    #{scope => oidcc_scope:scopes(),
      refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
      expected_subject := binary(),
      request_opts => oidcc_http_util:request_opts()}.

Options for refreshing a token

See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3

fields

Fields

-type refresh_opts_no_sub() ::
    #{scope => oidcc_scope:scopes(),
      refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
      expected_subject := binary()}.
See refresh_opts_no_sub()
-type retrieve_opts() ::
    #{pkce => pkce(),
      nonce => binary() | any,
      scope => oidcc_scope:scopes(),
      refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
      redirect_uri := uri_string:uri_string(),
      request_opts => oidcc_http_util:request_opts()}.

Options for retrieving a token

See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3

fields

Fields

-type t() ::
    #oidcc_token{id :: oidcc_token:id() | none,
                 access :: oidcc_token:access() | none,
                 refresh :: oidcc_token:refresh() | none,
                 scope :: oidcc_scope:scopes()}.

Token Response Wrapper

fields

Fields

Link to this section Functions

Link to this function

client_credentials(ClientContext, Opts)

View Source
-spec client_credentials(ClientContext, Opts) -> {ok, t()} | {error, error()}
                      when
                          ClientContext :: oidcc_client_context:t(),
                          Opts :: client_credentials_opts().

Retrieve Client Credential Token

See https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4

For a high level interface using oidcc_provider_configuration_worker see oidcc:client_credentials_token/4.

examples

Examples

  {ok, ClientContext} =
    oidcc_client_context:from_configuration_worker(provider_name,
                                                   <<"client_id">>,
                                                   <<"client_secret">>),
 
  {ok, #oidcc_token{}} =
    oidcc_token:client_credentials(ClientContext,
                                   #{scope => [<<"scope">>]}).
Link to this function

jwt_profile(Subject, ClientContext, Jwk, Opts)

View Source
-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 oidcc_provider_configuration_worker see oidcc:jwt_profile_token/6.

examples

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)}).
Link to this function

refresh(RefreshToken, ClientContext, Opts)

View Source
-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

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>>}).
Link to this function

retrieve(AuthCode, ClientContext, Opts)

View Source
-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

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">>}).
Link to this function

validate_id_token(IdToken, ClientContext, Nonce)

View Source
-spec validate_id_token(IdToken, ClientContext, Nonce) -> {ok, Claims} | {error, error()}
                     when
                         IdToken :: binary(),
                         ClientContext :: oidcc_client_context:t(),
                         Nonce :: binary() | any,
                         Claims :: oidcc_jwt_util:claims().

Validate ID Token

Usually the id token is validated using retrieve/3. If you gget the token passed from somewhere else, this function can validate it.

examples

Examples

  {ok, ClientContext} =
    oidcc_client_context:from_configuration_worker(provider_name,
                                                   <<"client_id">>,
                                                   <<"client_secret">>),
 
  %% Get IdToken from somewhere
 
  {ok, Claims} =
    oidcc:validate_id_token(IdToken, ClientContext, ExpectedNonce).