NAME

Catalyst::Plugin::OIDC - Catalyst plugin for OIDC protocol integration

DESCRIPTION

This plugin makes it easy to integrate the OpenID Connect protocol into a Catalyst application.

METHODS

setup_finalize

Code executed once when the application is loaded.

Depending on the configuration, creates and keeps in memory one or more clients (OIDC::Client stateless objects) and automatically adds the callback routes to the application.

METHODS ADDED TO THE APPLICATION

oidc( $provider )

# with just one provider
my $oidc = $c->oidc;
# or
my $oidc = $c->oidc('my_provider');

# with several providers
my $oidc = $c->oidc('my_provider_1');

Creates and returns an instance of OIDC::Client::Plugin with the data from the current request and session.

If several providers are configured, the $provider parameter is mandatory.

This is the application's entry point to the library. Please see the OIDC::Client::Plugin documentation to find out what methods are available.

CONFIGURATION

Section to be added to your configuration file :

<oidc_client>
    <provider provider_name>
        id                    my-app-id
        secret                xxxxxxxxx
        well_known_url        https://yourprovider.com/oauth2/.well-known/openid-configuration
        signin_redirect_path  /oidc/login/callback
        scope                 openid profile email
        expiration_leeway     20
        <claim_mapping>
            login      sub
            lastname   lastName
            firstname  firstName
            email      email
            roles      roles
        </claim_mapping>
        <audience_alias other_app_name>
            audience    other-app-audience
        </audience_alias>
    </provider>
</oidc_client>

This is an example, see the detailed possibilities in OIDC::Client::Config.

SAMPLES

Here are some samples by category. Although you will have to adapt them to your needs, they should be a good starting point.

Setup

To setup the plugin when the application is launched :

my @plugin = (
  ...
  'OIDC',
);
__PACKAGE__->setup(@plugin);

Authentication

To authenticate the end-user :

if (my $identity = $c->oidc->get_stored_identity()) {
  $c->request->remote_user($identity->{subject});
}
elsif (uc($c->request->method) eq 'GET' && !$c->is_ajax_request()) {
  $c->oidc->redirect_to_authorize();
}
else {
  MyApp::Exception::Authentication->throw(
    error => "You have been logged out. Please try again after refreshing the page.",
  );
}

API call

To make an API call with propagation of the security context (token exchange) :

# Retrieving a web client (Mojo::UserAgent object)
my $ua = try {
  $c->oidc->build_api_useragent('other_app_name')
}
catch {
  $c->log->warn("Unable to exchange token : $_");
  MyApp::Exception::Authorization->throw(
    error => "Authorization problem. Please try again after refreshing the page.",
  );
};

# Usual call to the API
my $res = $ua->get($url)->result;

SECURITY RECOMMENDATION

It is highly recommended to configure the framework to store session data, including sensitive tokens such as access and refresh tokens, on the backend rather than in client-side cookies. Although cookies can be signed and encrypted, storing tokens in the client exposes them to potential security threats.

cpanm OIDC::Client

perl -MCPAN -e shell
install OIDC::Client