view release on metacpan or  search on metacpan

QUICKSTART.md  view on Meta::CPAN

# Quick Start Guide

Get started with Catalyst::Plugin::OpenIDConnect in 5 minutes.

## 1. Install

```bash
cd /path/to/catalyst-plugin-openidconnect
cpanm --installdeps .
```

## 2. Generate Keys

```bash
# Generate RSA key pair (2048-bit, suitable for development)
openssl genrsa -out /path/to/private.pem 2048
openssl rsa -in /path/to/private.pem -pubout -out /path/to/public.pem

# Or use the example script
bash example/generate_keys.sh
```

## 3. Configure Your App

Add to your Catalyst application:

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

__PACKAGE__->config(
    'Plugin::OpenIDConnect' => {
        issuer => {
            url                => 'http://localhost:5000',
            private_key_file   => '/path/to/private.pem',
            public_key_file    => '/path/to/public.pem',
            key_id             => 'my-key-1',
        },
        clients => {
            'my-client' => {
                client_secret             => 'my-secret',
                redirect_uris             => ['http://localhost:3000/callback'],
                post_logout_redirect_uris => ['http://localhost:3000/logged-out'],
            },
        },
    },
);

# Load the OpenIDConnect controller before setup
use MyApp::Controller::OpenIDConnect;

__PACKAGE__->setup;
```

## 3a. Create the OpenIDConnect Controller

The plugin requires you to create a controller that extends the plugin's controller.
Create `lib/MyApp/Controller/OpenIDConnect.pm`:

```perl
package MyApp::Controller::OpenIDConnect;

use Moose;
use namespace::autoclean;

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

__PACKAGE__->meta->make_immutable;

1;
```

This allows Catalyst to properly discover and register all OpenIDConnect routes.

## 3b. Create a Login Action

Your app must have a login action that handles the `back` parameter. The plugin redirects unauthenticated users to your login page, which should redirect back to complete the authentication flow:

```perl
package MyApp::Controller::Auth;

use Moose;
use namespace::autoclean;

BEGIN { extends 'Catalyst::Controller'; }

sub login : Local {
    my ( $self, $c ) = @_;

    if ( $c->request->method eq 'POST' ) {
        my $username = $c->request->params->{username};

        # In development, accept any username
        if ($username) {
            $c->session->{user} = { username => $username, id => $username };