OIDC-Client

 view release on metacpan or  search on metacpan

lib/OIDC/Client/Config.pod  view on Meta::CPAN

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
C<error_message> flash data.

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

=head2 provider."provider".store_mode

Defines where the tokens are stored for this provider.

Possible values (C<session> by default) :

=over

=item session

Stored data persists between requests until the session expires.

=item 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 C<Authorization> header for each request (Resource Server).

=item cache

The data is stored in a L<CHI|https://metacpan.org/pod/CHI> cache.
The cache keys correspond to the names of the audiences.

The L</"provider."provider".cache_config"> configuration entry is used
to instanciate the CHI object.

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

=back

=head2 provider."provider".proxy_detect

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

=head2 provider."provider".user_agent

Changes the user agent name.

=head2 provider."provider".id

OIDC client ID supplied by your provider. Mandatory

=head2 provider."provider".secret

OIDC client secret supplied by your provider.

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

=head2 provider."provider".private_jwk_file

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

=head2 provider."provider".private_jwk

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

=head2 provider."provider".private_key_file

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

=head2 provider."provider".private_key

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

=head2 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.

=head2 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 C<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');

=head2 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:

=over

=item issuer

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

=item jwks_url

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

=item authorize_url

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

=item token_url

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

=item introspection_url

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

lib/OIDC/Client/Config.pod  view on Meta::CPAN

=head2 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 C<exp> claim,
which is used by default.

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

=head2 provider."provider".expiration_leeway

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

=head2 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.

=head2 provider."provider".jwt_decoding_options

Options to be transferred to the
L<Crypt::JWT::decode_jwt()|https://metacpan.org/pod/Crypt::JWT#decode_jwt>
function used to validate and decode a JWT token.

By default, the transmitted options are :

=over

=item verify_exp: 1

Expiration Time 'exp' claim must be present and valid

=item verify_iat: 1

Issued At 'iat' claim must be present and valid

=item leeway: 60

Clock skew of 1 minute

=back

=head2 provider."provider".client_secret_jwt_encoding_options

Options to be transferred to the
L<Crypt::JWT::encode_jwt()|https://metacpan.org/pod/Crypt::JWT#encode_jwt>
function called to encode a JWT token when using the C<client_secret_jwt>
authentication method.

By default, the transmitted options are :

=over

=item alg: 'HS256'

Encoding algorithm used

=back

=head2 provider."provider".private_key_jwt_encoding_options

Options to be transferred to the
L<Crypt::JWT::encode_jwt()|https://metacpan.org/pod/Crypt::JWT#encode_jwt>
function called to encode a JWT token when using the C<private_key_jwt>
authentication method.

By default, the transmitted options are :

=over

=item alg: 'RS256'

Encoding algorithm used

=back

=head2 provider."provider".claim_mapping

Used to map token claims or user information to an L<OIDC::Client::User> object
when calling the L<OIDC::Client::Plugin/"build_user_from_userinfo( $user_class )">,
L<OIDC::Client::Plugin/"build_user_from_claims( $claims, $user_class )"> or
L<OIDC::Client::Plugin/"build_user_from_identity( $user_class )"> methods.

The keys are the user attributes and the values are the keys of the claims.
If needed, to walk down the data tree of a claim, use the dot character.

For example, with this configured claim mapping :

    <claim_mapping>
        login      sub
        lastname   family_name
        firstname  given_name
        email      contact.email
        roles      roles
    </claim_mapping>

And the JSON claims :

    {
        "sub": "4d586782",
        "family_name": "Doe",
        "given_name": "John",
        "contact": {
            "email": "doej@example.com",
            "country": "France"
        },
        "roles": [
            "role1",
            "role2"
        ]
    }

The resulted Perl object is :

    bless {
        login     => '4d586782',
        lastname  => 'Doe',
        firstname => 'John',
        email     => 'doej@example.com',
        roles     => ['role1', 'role2']
    }, 'OIDC::Client::User'

By default, no mapping is used.

lib/OIDC/Client/Config.pod  view on Meta::CPAN

is called.

=head2 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 (C<jwt> by default) :

=over

=item jwt

The L<OIDC::Client::verify_jwt_token()|https://metacpan.org/pod/OIDC::Client#verify_jwt_token(-%25args-)>
method is used to validate an access token.

=item introspection

The L<OIDC::Client::introspect_token()|https://metacpan.org/pod/OIDC::Client#introspect_token(-%25args-)>
method is used to validate an access token.

=back

=head2 provider."provider".token_endpoint_grant_type

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

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

=over

=item authorization_code

=item client_credentials

=item password

=back

=head2 provider."provider".client_auth_method

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

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

=over

=item client_secret_basic

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

=item client_secret_post

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

=item client_secret_jwt

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

=item 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 C<private_key> attribute of the L<OIDC::Client>
object instance or with one of the following configuration entries :

=item none

The Client does not authenticate itself.

=over

=item private_jwk_file

=item private_jwk

=item private_key_file

=item private_key

=back

=back

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

=head2 provider."provider".token_endpoint_auth_method

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

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

=head2 provider."provider".introspection_endpoint_auth_method

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

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

=head2 provider."provider".client_assertion_lifetime

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

120 seconds by default.

=head2 provider."provider".client_assertion_audience

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

Default: the URL of the endpoint being called.

=head2 provider."provider".username

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

=head2 provider."provider".password

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

=head2 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.

=head2 provider."provider".post_logout_redirect_uri

Alternative to C<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.

=head2 provider."provider".logout_with_id_token

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

True by default

=head2 provider."provider".logout_extra_params

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

=head2 provider."provider".cache_config

Options to be transferred to the L<CHI|https://metacpan.org/pod/CHI#CONSTRUCTOR>
constructor when using C<cache> store mode.

By default, the transmitted options are :

=over

=item 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.

=item global: 0