/ 
OIDC-Client-1.05
River stage one • 2 direct dependents • 2 total dependents
⭐ Starred 0 GitHub stars
/ OIDC::Client::Config

NAME

OIDC::Client::Config - Configuration Documentation

DESCRIPTION

These configuration entries apply to all framework plugins using the OIDC-Client distribution.

For direct use with the OIDC::Client module, all entries beginning with provider."provider". apply, but this prefix must be removed from the configuration entry names.

ENTRIES

default_provider

Defines the provider name to use by the framework plugin when no one has been specified in the call to the oidc($provider) method.

authentication_error_path

Relative path of the endpoint to which the browser is redirected if an error is returned by the provider during the callback to the application after an authentication attempt, if an error occurs when the token is retrieved in exchange for the code or if an error occurs when verifying the token.

From the redirection endpoint, the error message is present in error_message flash data.

If this path is not configured, an OIDC::Client::Error::Authentication error is thrown.

provider."provider".store_mode

Defines where the tokens are stored for this provider.

Possible values (session by default) :

session

Stored data persists between requests until the session expires.

stash

Stored data can only be accessed in the current request. This may be useful for an API which must validate the token in the Authorization header for each request (Resource Server).

cache

The data is stored in a CHI cache. The cache keys correspond to the names of the audiences.

The "provider."provider".cache_config" configuration entry is used to instanciate the CHI object.

You can only use the cache store mode with the client_credentials or password grant types.

provider."provider".proxy_detect

If true, detects the proxy server based on environment variables.

provider."provider".user_agent

Changes the user agent name.

provider."provider".id

OIDC client ID supplied by your provider. Mandatory

provider."provider".secret

OIDC client secret supplied by your provider.

If not present, the secret must be defined in the OIDC_${provider}_SECRET environment variable unless the authentication method is none or private_key_jwt.

provider."provider".private_jwk_file

Path to the private JWK file, used when using the private_key_jwt client authentication method.

provider."provider".private_jwk

Perl HASH ref with JWK key structure, used when using the private_key_jwt client authentication method.

provider."provider".private_key_file

Path to the private RSA key file when using the private_key_jwt client authentication method.

provider."provider".private_key

String of the private RSA key file when using the private_key_jwt client authentication method.

provider."provider".audience

Specifies the provider for whom the access token is intended.

If this parameter is omitted, the access token returned by the provider is intended for your OIDC client (useful for making token exchanges).

For an application, it's better to leave this parameter out and make token exchanges if you need to make API calls to other applications, but it can be useful for a batch if you know that the API calls will be made to a single application.

provider."provider".role_prefix

Defines a prefix common to the roles that will be ignored during a comparison test between a role to be verified and the list of user roles.

For example, with MYAPP. prefix, you cand do :

my $can_access_app = $auth_user->has_role('USER');

instead of :

my $can_access_app = $auth_user->has_role('MYAPP.USER');

provider."provider".well_known_url

Endpoint which allows the library to retrieve the provider's metadata at the time of instantiation of the OIDC client only.

If it's not defined, the following parameters must be manually specified when required:

issuer

Provider identifier which must correspond exactly to the iss claim of the tokens received.

jwks_url

Endpoint for publishing the keys to be used to verify the signature of a JWT token.

authorize_url

Endpoint from which an interaction takes place between the provider and the browser in order to authenticate the user.

token_url

Endpoint on which the backend exchanges an authorization code with a token or refreshes a token.

introspection_url

Endpoint on which the resource server can query an authorization server to determine the active state of a token.

userinfo_url

Endpoint used to retrieve user information.

end_session_url

Endpoint used to clean up the user session on the provider side.

You can also configure the well know URL and _overload_ one or more metadata with these same configuration entries.

provider."provider".signin_redirect_path

Relative path of the endpoint used by the provider to redirect the user's browser to the application once authentication has been completed.

provider."provider".signin_redirect_uri

Alternative to signin_redirect_path

Absolute path to the endpoint used by the provider to redirect the user's browser to the application once authentication has been completed.

provider."provider".scope

String with space separators defining the desired scope of rights of the requested token.

provider."provider".refresh_scope

String with space separators, used only for the refresh_token grant-type, defining the desired scope of rights of the requested renewed token.

May be useful, depending on your needs, to restrict scopes relative to the initial request. For example, removing the openid scope means that no new ID token will be received, only a new access token with its new refresh token.

provider."provider".identity_expires_in

Number of seconds to add to the current time (when the ID token is retrieved) to force an expiration time. This overrides the expiration time specified in the exp claim, which is used by default.

The value 0 means that there is no expiration time for the stored identity (lifetime of the current session).

provider."provider".expiration_leeway

Number of seconds of leeway for a token to be considered expired before it actually is.

provider."provider".max_id_token_age

Maximum number of seconds for an ID token to be considered too old during validation by the current client application, after the user has been authenticated with the provider.

provider."provider".jwt_decoding_options

Options to be transferred to the Crypt::JWT::decode_jwt() function used to validate and decode a JWT token.

By default, the transmitted options are :

verify_exp: 1

Expiration Time 'exp' claim must be present and valid

verify_iat: 1

Issued At 'iat' claim must be present and valid

leeway: 60

Clock skew of 1 minute

provider."provider".client_secret_jwt_encoding_options

Options to be transferred to the Crypt::JWT::encode_jwt() function called to encode a JWT token when using the client_secret_jwt authentication method.

By default, the transmitted options are :

alg: 'HS256'

Encoding algorithm used

provider."provider".private_key_jwt_encoding_options

Options to be transferred to the Crypt::JWT::encode_jwt() function called to encode a JWT token when using the private_key_jwt authentication method.

By default, the transmitted options are :

alg: 'RS256'

Encoding algorithm used

provider."provider".claim_mapping

Used to map token claims or user information to an OIDC::Client::User object.

By default, no mapping is used.

provider."provider".audience_alias

Audience configuration for token exchanges.

Gives an alias to an audience rather than using the technical identifier.

For example :

<audience_alias other_app_name>
    audience    other-app-audience
</audience_alias>

provider."provider".audience_alias.audience

Audience to be used for this audience alias.

provider."provider".audience_alias.scope

String with space separators defining the desired scope of rights of the requested exchanged token.

provider."provider".authorize_endpoint_response_mode

Defines how tokens are sent by the provider.

Can take one of these values:

query

Tokens are sent in query parameters.

form_post

Tokens are sent in a POST form.

provider."provider".authorize_endpoint_extra_params

Defines additional parameters to be sent to the provider when the authorize endpoint is called.

provider."provider".token_validation_method

Defines which method to use for a resource server to validate an access token.

Can take one of these values (jwt by default) :

jwt

The OIDC::Client::verify_jwt_token() method is used to validate an access token.

introspection

The OIDC::Client::introspect_token() method is used to validate an access token.

provider."provider".token_endpoint_grant_type

Defines the grant_type parameter to be sent to the provider when the token endpoint is called.

Can take one of these values (authorization_code by default) :

authorization_code
client_credentials
password

provider."provider".client_auth_method

Defines the authentication method to be used for all the provider endpoints.

Can take one of these values (client_secret_basic by default) :

client_secret_basic

The client id and the secret are sent in an Authorization header.

client_secret_post

The client id and secret are sent in the POST body.

client_secret_jwt

A JWT assertion, signed with the client secret using an HMAC SHA algorithm, is generated and sent in the POST body.

private_key_jwt

A JWT assertion, signed using a private key in asymmetric cryptography, is generated and sent in the POST body.

The private key can be defined with the private_key attribute of the OIDC::Client object instance or with one of the following configuration entries :

none

The Client does not authenticate itself.

private_jwk_file
private_jwk
private_key_file
private_key

You can also redefines the authentication method to be used for each endpoint with the token_endpoint_auth_method and introspection_endpoint_auth_method configuration entries.

provider."provider".token_endpoint_auth_method

Defines the authentication method to be used when calling the token endpoint.

Same list of possible values as for the client_auth_method configuration entry.

provider."provider".introspection_endpoint_auth_method

Defines the authentication method to be used when calling the token endpoint.

Same list of possible values as for the client_auth_method configuration entry.

provider."provider".client_assertion_lifetime

Specifies the lifetime, in seconds, of the client assertion JWT generated for client authentication methods such as client_secret_jwt and private_key_jwt.

120 seconds by default.

provider."provider".client_assertion_audience

Defines the audience (aud) claim to include in the client assertion JWT used for authentication.

Default: the URL of the endpoint being called.

provider."provider".username

For a grant_type password, specifies the technical account to be used.

provider."provider".password

For a grant_type password, specifies the technical account password to be used.

provider."provider".logout_redirect_path

Relative path of the endpoint used by the provider to redirect the user's browser to the application once the session has been cleaned up on the provider side.

provider."provider".post_logout_redirect_uri

Alternative to logout_redirect_path

Absolute path to the endpoint used by the provider to redirect the user's browser to the application once the session has been cleaned up on the provider side.

provider."provider".logout_with_id_token

Specifies whether the token id should be sent to the provider when the end_session endpoint is called.

True by default

provider."provider".logout_extra_params

Defines additional parameters to be sent to the provider when the end_session endpoint is called.

provider."provider".cache_config

Options to be transferred to the CHI constructor when using cache store mode.

By default, the transmitted options are :

driver: Memory

In-process memory based cache

This is the least intrusive driver, but you should probably use the one that best suits your needs.

global: 0

No global datastore in memory.

provider."provider".mocked_identity

For local use only, bypasses the authentication flow by directly defining a mocked object representing an OIDC::Client::Identity object.

Example:

<mocked_identity>
    subject     DOEJ
    token       abcd1234
    <claims>
        sub         DOEJ
        lastName    Doe
        firstName   John
        email       john.doe@gmail.com
        roles       MYAPP.ROLE1
        roles       MYAPP.ROLE2
    </claims>
</mocked_identity>

provider."provider".mocked_access_token

For local use only, allows the verification of a token to be bypassed by directly defining a mocked object representing an OIDC::Client::AccessToken object. Also used when retrieving an OIDC::Client::AccessToken object from the store.

Example:

<mocked_access_token>
    token       abcd1234
    scopes      scope1
    scopes      scope2
</mocked_access_token>

provider."provider".mocked_userinfo

For local use only, allows you to directly define a mocked object representing userinfo.

Example:

<mocked_userinfo>
    sub         DOEJ
    lastName    Doe
    firstName   John
    email       john.doe@gmail.com
    roles       MYAPP.ROLE1
    roles       MYAPP.ROLE2
</mocked_userinfo>