view release on metacpan or  search on metacpan

DEPLOYMENT.md  view on Meta::CPAN

# Deployment Guide

Production deployment considerations for Catalyst::Plugin::OpenIDConnect.

## Prerequisites

- Perl 5.20 or higher
- Catalyst 5.90100 or higher
- OpenSSL for key generation
- HTTP/HTTPS web server
- Database (optional, for persistent storage)

## Installation

### 1. Install Dependencies

Using cpanm:

```bash
cpanm Catalyst::Plugin::OpenIDConnect
```

Or using cpanfile:

```bash
cpanm --installdeps .
```

### 2. Generate RSA Keys

```bash
# Generate 2048-bit RSA key pair
openssl genrsa -out /secure/path/private.pem 2048

# Extract public key
openssl rsa -in /secure/path/private.pem -pubout -out /secure/path/public.pem

# Set restrictive permissions
chmod 600 /secure/path/private.pem
chmod 644 /secure/path/public.pem
```

Note: For production, consider using 4096-bit keys or storing keys in a HSM (Hardware Security Module).

### 3. Configure Your Application

Create/update `catalyst.conf`:

```
<Plugin::OpenIDConnect>
    <issuer>
        url = https://auth.example.com
        private_key_file = /secure/path/private.pem
        public_key_file = /secure/path/public.pem
        key_id = prod-key-2024-01
    </issuer>
    
    <clients>
        <my-app>
            client_secret = <randomly-generated-secret>
            redirect_uris = https://app.example.com/callback https://app.example.com/oauth/callback
            post_logout_redirect_uris = https://app.example.com/logged-out
            response_types = code
            grant_types = authorization_code refresh_token
            scope = openid profile email
        </my-app>
    </clients>
    
    <user_claims>
        sub = id
        name = full_name
        email = email
        picture = avatar_url
    </user_claims>
</Plugin::OpenIDConnect>

<Plugin::Session>
    expires = 2592000
    cookie_secure = 1
    cookie_httponly = 1
    cookie_samesite = Lax
</Plugin::Session>
```

### 4. Create the OpenIDConnect Controller

Create `lib/MyApp/Controller/OpenIDConnect.pm` in your application:

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

use Moose;
use namespace::autoclean;

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

__PACKAGE__->meta->make_immutable;

1;
```