/ 
Catalyst-Plugin-OIDC-0.01
/ Catalyst::Plugin::OIDC

NAME

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

DESCRIPTION

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

It essentially uses the OIDC-Client distribution.

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.

AUTHOR

Sébastien Mourlhou

COPYRIGHT AND LICENSE

Copyright (C) Sébastien Mourlhou

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.