NAME

OIDC::Client::Plugin - Main module for the plugins

DESCRIPTION

Main module instanciated for the current request by an application plugin (for example: Mojolicious::Plugin::OIDC).

It contains all the methods available in the application.

METHODS

redirect_to_authorize( %args )

$c->oidc->redirect_to_authorize();

Redirect the browser to the authorize URL to initiate an authorization code flow. The state parameter contains a generated UUID but other data can be added.

The optional hash parameters are:

target_url

Specifies the URL to redirect to at the end of the authorization code flow. Default to the current URL (attribute current_url).

redirect_uri

Specifies the URL that the provider uses to redirect the user's browser back to the application after the user has been authenticated. Default to the URL built from the signin_redirect_path configuration entry.

extra_params

Hashref which can be used to send extra query parameters.

other_state_params

List (arrayref) of strings to add before the auto-generated UUID string to build the state parameter. All these strings are separated by a comma.

get_token( %args )

my $identity = $c->oidc->get_token();

Checks that the state parameter received from the provider is identical to the state parameter sent with the authorize URL.

From a code received from the provider, executes a request to get the token(s).

Checks the ID token if present and stores the token(s) in the session by default or stash depending on your configured store_mode (see OIDC::Client::Config).

Returns the stored OIDC::Client::Identity object.

The optional hash parameters are:

redirect_uri

Specifies the URL that the provider uses to redirect the user's browser back to the application after the user has been authenticated. Default to the URL built from the signin_redirect_path configuration entry.

refresh_token( $audience_alias )

my $stored_access_token = $c->oidc->refresh_token( $audience_alias );

Refreshes a token (usually because it has expired) for the default audience (token for the current application) or for the audience corresponding to a given alias (exchanged token for another application).

Stores and returns a new OIDC::Client::AccessToken object.

Throws an error if no access token or no refresh token has been stored for the audience.

The optional list parameters are:

audience_alias

Alias configured for the audience of the other application.

exchange_token( $audience_alias )

my $stored_exchanged_token = $c->oidc->exchange_token($audience_alias);

Exchange the access token received during the user's login, for an access token that is accepted by a different OIDC application and stores it.

Stores and returns an OIDC::Client::AccessToken object.

The list parameters are:

audience_alias

Alias configured for the audience of the other application.

verify_token()

my $access_token = $c->oidc->verify_token();

Verifies the JWT access token received in the Authorization header of the current request. Throws an exception if an error occurs. Otherwise, stores an OIDC::Client::AccessToken object and returns the claims.

To bypass the token verification in local environment, you can configure the mocked_access_token entry (hashref) to be used to create an OIDC::Client::AccessToken object that will be returned by this method.

get_token_from_authorization_header()

my $token = $c->oidc->get_token_from_authorization_header();

Returns the token received in the Authorization header of the current request, or returns undef if there is no token in this header.

get_userinfo()

my $userinfo = $c->oidc->get_userinfo();

Returns the user informations from the userinfo endpoint.

This method should only be invoked when an access token has been stored.

To mock the userinfo returned by this method in local environment, you can configure the mocked_userinfo entry (hashref).

build_user_from_userinfo( $user_class )

my $user = $c->oidc->build_user_from_userinfo();

Gets the user informations calling the provider (see "get_userinfo()") and returns a user object (OIDC::Client::User by default) from this user informations.

The claim_mapping configuration entry is used to map user information to user attributes.

The optional list parameters are:

user_class

Class to be used to instantiate the user object. Default to OIDC::Client::User.

build_user_from_claims( $claims, $user_class )

my $user = $c->oidc->build_user_from_claims($claims);

Returns a user object (OIDC::Client::User by default) based on provided claims.

The claim_mapping configuration entry is used to map claim keys to user attributes.

This method can be useful, for example, if the access token is a JWT token that has just been verified with the verify_token() method and already contains the relevant information without having to call the userinfo endpoint.

The list parameters are:

claims

Hashref of claims.

user_class

Optional class to be used to instantiate the user object. Default to OIDC::Client::User.

build_user_from_identity( $user_class )

my $user = $c->oidc->build_user_from_identity();

Returns a user object (OIDC::Client::User by default) from the claims of the stored identity.

The claim_mapping configuration entry is used to map identity claim keys to user attributes.

This method should only be invoked when an identity has been stored, i.e. when an authorisation flow has completed and an ID token has been returned by the provider.

The optional list parameters are:

user_class

Class to be used to instantiate the user object. Default to OIDC::Client::User.

build_api_useragent( $audience_alias )

my $ua = $c->oidc->build_api_useragent( $audience_alias );

Builds a web client (Mojo::UserAgent object) to perform requests on another application with security context propagation.

The appropriate access token will be added in the authorization header of each request.

The list parameters are:

audience_alias

Optional alias configured for the audience of the other application. If this parameter is missing, the default audience (current application) is used.

redirect_to_logout( %args )

$c->oidc->redirect_to_logout();

Redirect the browser to the logout URL.

The optional hash parameters are:

with_id_token

Specifies whether the stored id token should be sent to the provider.

target_url

Specifies the URL to redirect to after the browser is redirected to the logout callback URL.

post_logout_redirect_uri

Specifies the URL that the provider uses to redirect the user's browser back to the application after the logout has been performed. Default to the URL built from the logout_redirect_path configuration entry.

extra_params

Hashref which can be used to send extra query parameters.

other_state_params

List (arrayref) of strings to add before the auto-generated UUID string to build the state parameter. All these strings are separated by a comma.

get_valid_access_token( $audience_alias )

my $valid_access_token = $c->oidc->get_valid_access_token( $audience_alias );

When an audience alias is specified and no access token has been stored for the audience, returns the execution of the "exchange_token( $audience_alias )" method.

Retrieves the stored OIDC::Client::AccessToken object for the default audience (current application) or for the audience corresponding to the given alias.

If this token has not expired, returns it, otherwise returns the execution of the "refresh_token( $audience_alias )" method.

If the refresh failed and the audience alias is specified, finally returns the execution of the "exchange_token( $audience_alias )" method.

The optional list parameters are:

audience_alias

Alias configured for the audience of the other application.

In local environment, if the mocked_access_token entry (hashref) is configured, it is used to create an OIDC::Client::AccessToken object that will be returned by this method.

get_valid_identity()

my $identity = $c->oidc->get_valid_identity();

Executes the "get_stored_identity()" method to get the stored OIDC::Client::Identity object.

Returns undef if no identity has been stored or if the stored identity has expired including the configured leeway.

Otherwise, returns the stored OIDC::Client::Identity object.

get_stored_identity()

my $identity = $c->oidc->get_stored_identity();

Returns undef if no identity has been stored. Otherwise, returns the stored OIDC::Client::Identity object, even if the identity has expired.

By default, the expires_at attribute comes directly from the exp claim but if the identity_expires_in configuration entry is specified, it is added to the current time (when the ID token is retrieved) to force an expiration time.

To bypass the OIDC flow in local environment, you can configure the mocked_identity entry (hashref) to be used to create an OIDC::Client::Identity object that will be returned by this method.

get_stored_access_token( $audience_alias )

my $access_token = $c->oidc->get_stored_access_token();

Returns the stored OIDC::Client::AccessToken object for the specified audience alias, even if this token has expired.

The optional list parameters are:

audience_alias

Alias configured for the audience of the other application.

In local environment, if the mocked_access_token entry (hashref) is configured, it is used to create an OIDC::Client::AccessToken object that will be returned by this method.

store_access_token( $access_token, $audience_alias )

$c->oidc->store_access_token($access_token);

Stores an OIDC::Client::AccessToken object in the session or stash depending on your configured store_mode (see OIDC::Client::Config).

delete_stored_data()

$c->oidc->delete_stored_data();

Delete the tokens and other data stored in the session or stash depending on your configured store_mode (see OIDC::Client::Config).

Note that only the data from the current provider is deleted.

cpanm OIDC::Client

perl -MCPAN -e shell
install OIDC::Client