# OIDC-Client

This distribution makes it easy to integrate the OpenID Connect protocol into different types of Perl applications.

You can use the [OIDC::Client](https://metacpan.org/pod/OIDC::Client) module directly in any batch or script. If you plan to use it from a web application, you should instead choose the plugin that is compatible with your framework (all these plugins essentially use this distribution) :

- [Mojolicious::Plugin::OIDC](https://metacpan.org/pod/Mojolicious::Plugin::OIDC)
- [Catalyst::Plugin::OIDC](https://metacpan.org/pod/Catalyst::Plugin::OIDC)
- [Dancer2::Plugin::OIDC](https://metacpan.org/pod/Dancer2::Plugin::OIDC)

## Features

- builds the authorization URL
- retrieves the provider metadata and JWK keys when the application is launched
- gets the token(s) from the provider
- includes a class for session management (token storage)
- refreshes the token(s)
- verifies a JWT token with support for automatic JWK key rotation
- introspects a token
- gets the user information from the *userinfo* endpoint
- exchanges the access token

## Security Features

### PKCE (Proof Key for Code Exchange)

PKCE is **enabled by default** for all authorization code flows. This mitigates authorization code interception attacks.

PKCE is considered a best practice for all OAuth 2.0 clients, including confidential clients, and is mandatory in OAuth 2.1.

### Cryptographically Secure Random Values

All security-sensitive random values generated by this module — `state`, `nonce`, `jti`, and PKCE `code_verifier` — are generated using a cryptographically secure pseudo-random number generator (CSPRNG). The generated values provide at least 128 bits of entropy, while PKCE `code_verifier` values provide 256 bits of entropy, as recommended by RFC 7636.

### Client Authentication

The following OAuth 2.0 client authentication methods are supported:

- `client_secret_basic`
- `client_secret_post`
- `client_secret_jwt`
- `private_key_jwt`
- `tls_client_auth`
- `none`

### Token Validation

ID Tokens and Access Tokens can be validated according to the OpenID Connect and OAuth 2.0 specifications, including support for JWT signature verification and token introspection.

## Documentation Index

- [Client module documentation](https://metacpan.org/pod/OIDC::Client)
- [Configuration](https://metacpan.org/pod/OIDC::Client::Config)

## Security Recommendation

When using OIDC-Client with an application, 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.

## Limitations

- no support for Implicit or Hybrid flows (applicable to front-end applications only and deprecated)