view release on metacpan or  search on metacpan

API_REFERENCE.md  view on Meta::CPAN

# OpenID Connect API Reference

Complete API documentation for the Catalyst::Plugin::OpenIDConnect endpoints.

## Base URL

```
http://localhost:5000
```

Replace with your actual issuer URL.

## Authentication Methods

- **Client Authentication**: Use `client_id` and `client_secret` in request body for token endpoint
- **Bearer Token**: Use `Authorization: Bearer <access_token>` header for protected resources

## Discovery Endpoint

### GET /.well-known/openid-configuration

Returns the OpenID Provider Configuration.

**Response:**

```json
{
  "issuer": "http://localhost:5000",
  "authorization_endpoint": "http://localhost:5000/openidconnect/authorize",
  "token_endpoint": "http://localhost:5000/openidconnect/token",
  "userinfo_endpoint": "http://localhost:5000/openidconnect/userinfo",
  "jwks_uri": "http://localhost:5000/openidconnect/jwks",
  "scopes_supported": ["openid", "profile", "email", "phone", "address"],
  "response_types_supported": ["code", "id_token token"],
  "response_modes_supported": ["query", "fragment", "form_post"],
  "grant_types_supported": ["authorization_code", "refresh_token", "implicit"],
  "subject_types_supported": ["public", "pairwise"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "userinfo_signing_alg_values_supported": ["RS256"],
  "claims_supported": [
    "sub", "name", "given_name", "family_name", "email", "email_verified", 
    "picture", "phone_number", "updated_at"
  ],
  "claim_types_supported": ["normal", "aggregated", "distributed"],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true
}
```

---

## Authorization Endpoint

### GET /openidconnect/authorize

Initiates an OpenID Connect authorization request.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_type | string | Yes | Must be "code" |
| client_id | string | Yes | The client identifier |
| redirect_uri | string | Yes | Where to redirect after authorization |
| scope | string | No | Space-separated scopes (default: "openid") |
| state | string | Recommended | CSRF protection state value |
| nonce | string | No | Session binding nonce (client validates it matches auth request) |
| code_challenge | string | Conditional | PKCE challenge value (RFC 7636). **Required for public clients** (those without a `client_secret`). Strongly recommended for all clients. Value is `BASE64URL(SHA256(ASCII(code_verifier)))`. |
| code_challenge_method | string | Conditional | Must be `S256` when `code_challenge` is provided. `plain` is not supported. |
| prompt | string | No | "login" to force re-authentication |
| max_age | integer | No | Maximum age of authentication (seconds) |
| ui_locales | string | No | Preferred UI locales |
| id_token_hint | string | No | Preferred user identity |
| login_hint | string | No | Hint for login (e.g., email) |
| acr_values | string | No | Authentication context class references |

**Example Request:**

```
GET /openidconnect/authorize?
    response_type=code&
    client_id=my-app&
    redirect_uri=https://app.example.com/callback&
    scope=openid%20profile%20email&
    state=xyz789&
    nonce=n-0S6_WzA2Mj
```

**Successful Response (Redirect):**

```
HTTP/1.1 302 Found
Location: https://app.example.com/callback?
    code=SplxlOBeZQQYbIHSmLqwuQ&
    state=xyz789