/ 
Catalyst-Plugin-OpenIDConnect-0.09
/ Catalyst::Plugin::OpenIDConnect

NAME

Catalyst::Plugin::OpenIDConnect - OpenID Connect provider plugin for Catalyst

DESCRIPTION

A Catalyst plugin implementing the OpenID Connect specification, providing OAuth 2.0 authentication and authorization. Note that this plugin does not implement the OIDC Client role; it is intended for applications acting as OIDC providers (authorization servers).

This plugin provides the core OpenIDConnect functionality (JWT handling, state management, and a reusable controller). To use it in your application, you must create a controller in your app's namespace that extends the plugin's controller (see below). This allows you to keep full control over your routing while cooperating with ACL and other route-processing plugins.

CONFIGURATION

package MyApp;
use Catalyst qw/
    OpenIDConnect
    Session
    Session::Store::File
    Session::State::Cookie
/;

MyApp->config(
    'Plugin::OpenIDConnect' => {
        issuer => {
            url => 'http://localhost:5000',
            private_key_file => '/path/to/private.pem',
            public_key_file => '/path/to/public.pem',
            key_id => 'key-123',
        },
        clients => {
            'my-client' => {
                client_secret => 'secret123',
                redirect_uris => ['http://localhost:3000/callback'],
                response_types => ['code'],
                grant_types => ['authorization_code'],
                scope => 'openid profile email',
            },
        },
    },
);

CREATING THE OPENIDCONNECT CONTROLLER

To enable the OpenIDConnect endpoints, create a controller in your app that extends the plugin's controller. Create the file lib/MyApp/Controller/OpenIDConnect.pm (where MyApp is your app's namespace) with the following content:

package MyApp::Controller::OpenIDConnect;

use Moose;
use namespace::autoclean;

BEGIN { extends 'Catalyst::Plugin::OpenIDConnect::Controller::Root' }

__PACKAGE__->meta->make_immutable;
1;

Then, in your main app module, explicitly load this controller before setup:

package MyApp;
use Catalyst qw/
    OpenIDConnect
    Session
    Session::Store::File
    Session::State::Cookie
/;

# Load the controller before setup so Catalyst discovers it
use MyApp::Controller::OpenIDConnect;

MyApp->config(...);
MyApp->setup(...);

Setting up the controller in this way allows you to keep full control over your routing, and avoid namespace conflicts with ACL and other route-processing plugins. The plugin's controller will automatically mount the standard OpenID Connect endpoints (e.g. /authorize, /token, /userinfo) under the /openidconnect path, so you can access them at /openidconnect/authorize, etc.

ROUTES ADDED TO THE APPLICATION

The plugin's controller adds the following routes to the application:

GET  /.well-known/openid-configuration
GET  /openidconnect/authorize
POST /openidconnect/token
GET  /openidconnect/userinfo
GET  /openidconnect/jwks
POST /openidconnect/logout

ATTRIBUTES

_oidc_jwt

JWT handler instance.

_oidc_store

State and code storage.

METHODS

setup

Catalyst setup hook - initialize the plugin. Note that this hook can effectively be blocked in the consuming app by a similar setup method checking for configuration and deleting $config->{issuer} if not properly configured. This allows the consuming app to control whether the plugin initializes or not, which is useful for example in FastCGI deployments where multiple apps share the same codebase but only some are OIDC providers.

openidconnect()

Returns the OIDC context/handler object for use in controllers.

_oidc_build_jwt_handler($config)

Builds and configures the JWT handler from config.

AUTHOR

Tim F. Rayner

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0.