View Source oidcc (Oidcc v3.2.1)

OpenID Connect High Level Interface

Setup

  {ok, Pid} =
    oidcc_provider_configuration_worker:start_link(#{
      issuer => <<"https://accounts.google.com">>,
      name => {local, google_config_provider}
    }).

(or via a supervisor)

See oidcc_provider_configuration_worker for details

Global Configuration

  • max_clock_skew (default 0) - Maximum allowed clock skew for JWT exp / nbf validation, in seconds

Summary

Functions

Link to this function

client_credentials_token(ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec client_credentials_token(ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts) ->
                                  {ok, oidcc_token:t()} |
                                  {error, oidcc_client_context:error() | oidcc_token:error()}
                                  when
                                      ProviderConfigurationWorkerName :: gen_server:server_ref(),
                                      ClientId :: binary(),
                                      ClientSecret :: binary(),
                                      Opts ::
                                          oidcc_token:client_credentials_opts() |
                                          oidcc_client_context:opts().

Retrieve Client Credential Token

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

Examples

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

create_redirect_url(ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec create_redirect_url(ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts) ->
                             {ok, Uri} |
                             {error, oidcc_client_context:error() | oidcc_authorization:error()}
                             when
                                 ProviderConfigurationWorkerName :: gen_server:server_ref(),
                                 ClientId :: binary(),
                                 ClientSecret :: binary() | unauthenticated,
                                 Opts :: oidcc_authorization:opts() | oidcc_client_context:opts(),
                                 Uri :: uri_string:uri_string().

Create Auth Redirect URL

Examples

  {ok, RedirectUri} =
    oidcc:create_redirect_url(
      provider_name,
      <<"client_id">>,
      <<"client_secret">>
      #{redirect_uri: <<"https://my.server/return"}
    ),
 
  %% RedirectUri = https://my.provider/auth?scope=openid&response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Fmy.server%2Freturn
Link to this function

initiate_logout_url(Token, ProviderConfigurationWorkerName, ClientId, Opts)

View Source (since 3.0.0)
-spec initiate_logout_url(Token, ProviderConfigurationWorkerName, ClientId, Opts) ->
                             {ok, uri_string:uri_string()} |
                             {error, oidcc_client_context:error() | oidcc_logout:error()}
                             when
                                 Token :: IdToken | oidcc_token:t() | undefined,
                                 IdToken :: binary(),
                                 ProviderConfigurationWorkerName :: gen_server:server_ref(),
                                 ClientId :: binary(),
                                 Opts ::
                                     oidcc_logout:initiate_url_opts() |
                                     oidcc_client_context:unauthenticated_opts().

Create Initiate URI for Relaying Party initiated Logout

See https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout

Examples

  %% Get `Token` from `oidcc_token`
 
  {ok, RedirectUri} =
    oidcc:initiate_logout_url(
      Token,
      provider_name,
      <<"client_id">>,
      #{post_logout_redirect_uri: <<"https://my.server/return"}
  ),
 
  %% RedirectUri = https://my.provider/logout?id_token_hint=IDToken&client_id=ClientId&post_logout_redirect_uri=https%3A%2F%2Fmy.server%2Freturn
Link to this function

introspect_token(Token, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec introspect_token(Token, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts) ->
                          {ok, oidcc_token_introspection:t()} |
                          {error, oidcc_client_context:error() | oidcc_token_introspection:error()}
                          when
                              Token :: oidcc_token:t() | binary(),
                              ProviderConfigurationWorkerName :: gen_server:server_ref(),
                              ClientId :: binary(),
                              ClientSecret :: binary(),
                              Opts :: oidcc_token_introspection:opts() | oidcc_client_context:opts().

Introspect the given access token

Examples

  %% Get AccessToken
 
  {ok, #oidcc_token_introspection{active = True}} =
    oidcc:introspect_token(
      AccessToken,
      provider_name,
      <<"client_id">>,
      <<"client_secret">>,
      #{}
    ).
Link to this function

jwt_profile_token(Subject, ProviderConfigurationWorkerName, ClientId, ClientSecret, Jwk, Opts)

View Source (since 3.0.0)
-spec jwt_profile_token(Subject, ProviderConfigurationWorkerName, ClientId,
                        ClientSecret | unauthenticated,
                        Jwk, Opts) ->
                           {ok, oidcc_token:t()} |
                           {error, oidcc_client_context:error() | oidcc_token:error()}
                           when
                               Subject :: binary(),
                               ProviderConfigurationWorkerName :: gen_server:server_ref(),
                               ClientId :: binary(),
                               ClientSecret :: binary(),
                               Jwk :: jose_jwk:key(),
                               Opts :: oidcc_token:jwt_profile_opts() | oidcc_client_context:opts().

Retrieve JSON Web Token (JWT) Profile Token

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

Examples

  {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">>,
      provider_name,
      <<"client_id">>,
      <<"client_secret">>,
      Key,
      #{
       scope => [<<"scope">>],
       kid => maps:get(<<"keyId">>, KeyMap)
      }
    ).
Link to this function

refresh_token(RefreshToken, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec refresh_token(RefreshToken, ProviderConfigurationWorkerName, ClientId,
                    ClientSecret | unauthenticated,
                    Opts) ->
                       {ok, oidcc_token:t()} |
                       {error, oidcc_client_context:error() | oidcc_token:error()}
                       when
                           RefreshToken :: binary(),
                           ProviderConfigurationWorkerName :: gen_server:server_ref(),
                           ClientId :: binary(),
                           ClientSecret :: binary(),
                           Opts :: oidcc_token:refresh_opts() | oidcc_client_context:opts();
                   (Token, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts) ->
                       {ok, oidcc_token:t()} |
                       {error, oidcc_client_context:error() | oidcc_token:error()}
                       when
                           Token :: oidcc_token:t(),
                           ProviderConfigurationWorkerName :: gen_server:server_ref(),
                           ClientId :: binary(),
                           ClientSecret :: binary(),
                           Opts :: oidcc_token:refresh_opts_no_sub().

Refresh Token

Examples

  %% Get Token and wait for its expiry
 
  {ok, #oidcc_token{}} =
    oidcc:refresh_token(
      Token,
      provider_name,
      <<"client_id">>,
      <<"client_secret">>,
      #{expected_subject => <<"sub_from_initial_id_token>>}
    ).
Link to this function

retrieve_token(AuthCode, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec retrieve_token(AuthCode, ProviderConfigurationWorkerName, ClientId,
                     ClientSecret | unauthenticated,
                     Opts) ->
                        {ok, oidcc_token:t()} |
                        {error, oidcc_client_context:error() | oidcc_token:error()}
                        when
                            AuthCode :: binary(),
                            ProviderConfigurationWorkerName :: gen_server:server_ref(),
                            ClientId :: binary(),
                            ClientSecret :: binary(),
                            Opts :: oidcc_token:retrieve_opts() | oidcc_client_context: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

Examples

  %% Get AuthCode from Redirect
 
  {ok, #oidcc_token{}} =
    oidcc:retrieve_token(
      AuthCode,
      provider_name,
      <<"client_id">>,
      <<"client_secret">>,
      #{redirect_uri => <<"https://example.com/callback">>}
    ).
Link to this function

retrieve_userinfo(Token, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts)

View Source (since 3.0.0)
-spec retrieve_userinfo(Token, ProviderConfigurationWorkerName, ClientId,
                        ClientSecret | unauthenticated,
                        Opts) ->
                           {ok, map()} | {error, oidcc_client_context:error() | oidcc_userinfo:error()}
                           when
                               Token :: oidcc_token:t(),
                               ProviderConfigurationWorkerName :: gen_server:server_ref(),
                               ClientId :: binary(),
                               ClientSecret :: binary() | unauthenticated,
                               Opts ::
                                   oidcc_userinfo:retrieve_opts_no_sub() | oidcc_client_context:opts();
                       (Token, ProviderConfigurationWorkerName, ClientId, ClientSecret, Opts) ->
                           {ok, map()} | {error, any()}
                           when
                               Token :: binary(),
                               ProviderConfigurationWorkerName :: gen_server:server_ref(),
                               ClientId :: binary(),
                               ClientSecret :: binary(),
                               Opts :: oidcc_userinfo:retrieve_opts().

Load userinfo for the given token

Examples

  %% Get Token
 
  {ok, #{<<"sub">> => Sub}} =
    oidcc:retrieve_userinfo(
      Token,
      provider_name,
      <<"client_id">>,
      <<"client_secret">>,
      #{}
    ).