OIDC-Client

 view release on metacpan or  search on metacpan

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

=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".use_pkce

Boolean indicating whether to use PKCE (Proof Key for Code Exchange, RFC 7636)
for the authorization code flow.

Default: 1 (enabled)

=head2 provider."provider".pkce_code_challenge_method

The method used to derive the PKCE code challenge from the code verifier,
as defined in RFC 7636.

Accepted values:

=over

=item S256

SHA-256 hash of the code verifier (recommended, default)

=item plain

The code verifier is used as-is (not recommended)

=back

Only relevant when C<use_pkce> is enabled.

Default: S256

=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 tls_client_cert_file

Path to the PEM-encoded client certificate to use for mutual TLS (mTLS) client authentication.

This option is used only when C<client_auth_method> is set to C<tls_client_auth>.

The certificate must correspond to the private key configured with C<tls_client_key_file>.

=head2 tls_client_key_file

Path to the PEM-encoded private key associated with the client certificate specified
by C<tls_client_cert_file>.

This option is used only when C<client_auth_method> is set to C<tls_client_auth>.

If the private key is encrypted, specify its passphrase using C<tls_client_key_passphrase>.

=head2 tls_client_key_passphrase

Passphrase used to decrypt the private key specified by C<tls_client_key_file>.

This option is only required when the private key is encrypted.

=head2 tls_ca_file

Path to a PEM-encoded CA certificate bundle used to verify the TLS certificate
presented by the OpenID Provider during mutual TLS authentication.

=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

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 :

=over

=item private_jwk_file

=item private_jwk

=item private_key_file

=item private_key

=back

=item tls_client_auth

Mutual TLS (mTLS) client authentication using an X.509 certificate during
the TLS handshake itself.

=item none

The Client does not authenticate itself.

=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