/ 
OIDC-Client-0.01
/ OIDC::Client::Plugin

NAME

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

DESCRIPTION

Main module instanciated for the current request by the application plugin (Mojolicious::Plugin::OIDC or Catalyst::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 to the state parameter.

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 if preferred.

Returns the stored identity object (see get_stored_identity method) for details of the returned 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 the new access token, replacing the old one.

Returns the stored access token object. See get_valid_access_token method for details of the returned object.

Returns undef if 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.

Returns the stored access token object (see get_valid_access_token method) for details of the returned object.

The list parameters are:

audience_alias

Alias configured for the audience of the other application.

verify_token()

my $claims = $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 the token and returns the claims.

To bypass the token verification in local environment, you can configure the mocked_claims entry (hashref) to 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.

has_scope( $expected_scope )

my $has_scope = $c->oidc->has_scope($expected_scope);

Returns whether a scope is present in the scopes of the stored access token.

This method should only be invoked after a call to the "verify_token( %args )" method.

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 optional list parameters are:

user_class

Class to be used to instantiate the user. 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 stored identity. 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. 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

Alias configured for the audience of the other application.

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.

state

String which can be send in the state parameter.

has_access_token_expired( $audience_alias )

my $has_expired = $c->oidc->has_access_token_expired( $audience_alias );

Returns whether the stored access token for a specified audience has expired.

The list parameters are:

audience_alias

Alias configured for the audience of the other application.

get_valid_access_token( $audience_alias )

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

Returns a valid (not expired) token object (hashref) for the default audience or for the audience corresponding to a given alias.

Returns undef if no access token has been stored for the audience.

The token can be retrieved from the store or after a refresh.

The optional list parameters are:

audience_alias

Alias configured for the audience of the other application.

Returns a hashref with the keys :

token

Access token (String)

expires_at

The expiration time of this access token (Integer timestamp)

refresh_token

Token to "refresh" the access token when it has expired (String)

token_type

Type of the token (String)

scopes

Token scopes (arrayref of strings). Present only after a call to the "verify_token( %args )" method.

In local environment, if the mocked_claims entry (hashref) is configured, mocked token and scopes are returned.

get_stored_identity()

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

Returns the stored identity, a hashref with at least these keys :

token

Id token (String)

subject

Subject identifier (String)

If a claim mapping is configured in the claim_mapping section, the claim names/values are present in the stored identity and therefore returned by this method.

To bypass the OIDC flow in local environment, you can configure the mocked_identity entry (hashref) to be returned by this method.