—
—
—
—

              
package Catalyst::Plugin::OIDC;
use utf8;
use Moose;
use namespace::autoclean;
with 'Catalyst::ClassData';
use feature 'signatures';
no warnings 'experimental::signatures';
use Catalyst::Action;
use Carp qw(croak);
use Clone qw(clone);
use List::Util qw(first);
use Scalar::Util qw(blessed);
use Try::Tiny;
use OIDC::Client;
use OIDC::Client::Plugin;
use OIDC::Client::Error::Authentication;
our $VERSION = '0.01';
HideShow 16 lines of Pod
=encoding utf8
=head1 NAME
Catalyst::Plugin::OIDC - OIDC protocol integration for Catalyst
=head1 DESCRIPTION
This plugin makes it easy to integrate the OpenID Connect protocol
into a Catalyst application.
It essentially uses the L<OIDC-Client|https://metacpan.org/dist/OIDC-Client>
distribution.
=cut
__PACKAGE__->mk_classdata('_oidc_config');
__PACKAGE__->mk_classdata('_oidc_client_by_provider');
HideShow 12 lines of Pod
=head1 METHODS
=head2 setup_finalize
Code executed once when the application is loaded.
Depending on the configuration, creates and keeps in memory one or more clients
(L<OIDC::Client> stateless objects) and automatically adds the callback routes
to the application.
=cut
sub setup_finalize ($app) {
  my $config = $app->config->{'oidc_client'}
    or croak('no oidc_client config');
  $app->_oidc_config($config);
  my %client_by_provider;
  my %seen_path;
  my $dispatch_path = first { $_->isa('Catalyst::DispatchType::Path') } @{$app->dispatcher->dispatch_types};
  foreach my $provider (keys %{ $config->{provider} || {} }) {
    my $config_provider = clone($config->{provider}{$provider});
    $config_provider->{provider} = $provider;
    $client_by_provider{$provider} = OIDC::Client->new(
      config => $config_provider,
      log    => $app->log,
    );
    # didn't find a better way to dynamically add the callback routes to the application
    my @new_actions;
    foreach my $action_type (qw/ login logout /) {
      my $path = $action_type eq 'login' ? $config_provider->{signin_redirect_path}
                                         : $config_provider->{logout_redirect_path};
      next if !$path || $seen_path{$path}++;
      push @new_actions, Catalyst::Action->new(
        class      => __PACKAGE__,
        namespace  => '',
        code       => $action_type eq 'login' ? \&_oidc_login_callback : \&_oidc_logout_callback,
        name       => "oidc_${action_type}_callback",
        reverse    => "oidc/${action_type}_callback",
        attributes => { Path => [ $path ] },
      );
    }
    $dispatch_path->register($app, $_) for @new_actions;
  }
  $app->_oidc_client_by_provider(\%client_by_provider);
}
HideShow 22 lines of Pod
=head1 METHODS ADDED TO THE APPLICATION
=head2 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 L<OIDC::Client::Plugin> with the data
from the current request and session.
If several providers are configured, the I<$provider> parameter is mandatory.
This is the application's entry point to the library. Please see the
L<OIDC::Client::Plugin> documentation to find out what methods are available.
=cut
sub oidc ($c, $provider = undef) {
  my $client = $c->_oidc_get_client_for_provider($provider);
  my $plugin = $c->stash->{oidc}{plugin};
  return $plugin
    if $plugin && $plugin->client->provider eq $client->provider;
  $plugin = $c->stash->{oidc}{plugin} = OIDC::Client::Plugin->new(
    log             => $c->log,
    store_mode      => $c->_oidc_config->{store_mode} || 'session',
    request_params  => $c->req->params,
    request_headers => { $c->req->headers->flatten },
    session         => $c->session,
    stash           => $c->stash,
    get_flash       => sub { return $c->flash->{$_[0]}; },
    set_flash       => sub { $c->flash->{$_[0]} = $_[1]; return; },
    redirect        => sub { $c->response->redirect($_[0]); return; },
    client          => $client,
    base_url        => $c->req->base->as_string,
    current_url     => $c->req->uri->as_string,
  );
  return $plugin;
}
# code executed on callback after authentication attempt
sub _oidc_login_callback ($self, $c) {
  my @providers = keys %{ $c->_oidc_client_by_provider };
  my $provider = @providers == 1 ? $providers[0]
                                 : $c->flash->{oidc_provider};
  try {
    $c->oidc($provider)->get_token();
    $c->response->redirect($c->flash->{oidc_target_url} || $c->uri_for('/'));
  }
  catch {
    my $e = $_;
    die $e unless blessed($e) && $e->isa('OIDC::Client::Error');
    if (my $error_path = $c->_oidc_config->{authentication_error_path}) {
      $c->flash->{error_message} = $e->message;
      $c->response->redirect($c->uri_for($error_path));
    }
    else {
      OIDC::Client::Error::Authentication->throw($e->message);
    }
  };
}
# code executed on callback after user logout
sub _oidc_logout_callback ($self, $c) {
  $c->log->debug('Logging out');
  $c->delete_session;
  $c->response->redirect($c->flash->{oidc_target_url} || $c->uri_for('/'));
}
sub _oidc_get_client_for_provider ($c, $provider) {
  unless ($provider) {
    my @providers = keys %{ $c->_oidc_client_by_provider };
    if (@providers == 1) {
      $provider = $providers[0];
    }
    elsif (@providers > 1) {
      croak(q{OIDC: more than one provider are configured, the provider is mandatory : $c->oidc('my_provider')});
    }
    else {
      croak("OIDC: no provider is configured");
    }
  }
  my $client = $c->_oidc_client_by_provider->{$provider}
    or croak("OIDC: no client for provider $provider");
  return $client;
}
HideShow 95 lines of Pod
=head1 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 L<OIDC::Client::Config>.
=head1 SAMPLES
Here are some samples by category. Although you will have to adapt them to your needs,
they should be a good starting point.
=head2 Setup
To setup the plugin when the application is launched :
  my @plugin = (
    ...
    'OIDC',
  );
  __PACKAGE__->setup(@plugin);
=head2 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.",
    );
  }
=head2 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;
=head1 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.
=head1 AUTHOR
Sébastien Mourlhou
=head1 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.
=cut
__PACKAGE__->meta->make_immutable;
1;