phpBB OIDC Provider

This phpBB 3.3 extension lets a forum act as an OpenID Connect Provider.

It is feature-complete for the current supported flows, but it has not had broad third-party deployment coverage yet. Review configuration carefully before using it outside a controlled environment.

Features

• Authorization Code flow with S256 PKCE
• Refresh tokens, including offline_access
• ID tokens signed with RS256
• UserInfo endpoint with scope-gated profile and email claims
• Discovery and JWKS endpoints
• ACP-managed OIDC modes, identity, scopes, clients, and client secrets
• Consent handling and first-party authorization policy controls
• Back-channel logout on phpBB logout and user bans
• Expired token cleanup through phpBB cron

Requirements

• phpBB >=3.3.0
• PHP >=8.2
• Composer dependencies from composer.json
• PHP cURL extension for back-channel logout delivery
• OAUTH_ENC_KEY, configured as described below
• An unencrypted RSA private key readable at /run/secrets/oauth_private_key

Cryptographic configuration

OAUTH_ENC_KEY

OAUTH_ENC_KEY encrypts authorization-code and refresh-token payloads. It must be a base64-encoded or base64url-encoded 32-byte random key.

Generate one with:

php -r "echo base64_encode(random_bytes(32));"

The extension trims surrounding environment whitespace, accepts standard base64 or base64url encoding, rejects missing or malformed input, and verifies that the decoded key is exactly 32 bytes.

Signing key

Access tokens, ID tokens, logout tokens, and JWKS all use the RSA signing key at /run/secrets/oauth_private_key. The extension derives the public key and key ID from that private key.

Example local key generation:

openssl genrsa -out oauth_private_key 2048
chmod 600 oauth_private_key

Make that key available to phpBB at /run/secrets/oauth_private_key.

Runtime configuration

Runtime OIDC configuration is database-backed and managed in the phpBB ACP under OIDC Provider.

The ACP exposes:

• Modes: separate named OIDC configurations, with one active mode
• Identity: issuer plus ID group prefix and endpoint overrides
• Scopes: supported OAuth/OIDC scope names
• Clients: redirect URIs, grant support, permitted scopes, secret generation/rotation, back-channel logout URL, active state, authorization policy JSON
• Import: legacy YAML import into the database

The active mode is stored in phpBB config as oidcprovider_active_mode. Runtime tokens and authorization state are mode-scoped.

YAML files now serve the legacy or bootstrap import path. They are read when database config is empty, or when an admin imports them through the ACP. If you keep YAML import files locally, treat them as runtime secrets and do not commit real client secrets.

vendor/bin/phing build excludes config/clients.yml and config/config-sets/**/clients.yml from packaged builds.

First-party authorization policy

Trusted first-party clients can use authorization policy JSON in the ACP client form:

{
  "skip_consent": true,
  "allow_offline_access_without_prompt_consent": true,
  "pre_authorized_scopes": ["openid", "email", "profile", "offline_access"]
}

prompt=login and max_age still force reauthentication when a client asks for fresh authentication.

Endpoints

• Discovery: /.well-known/openid-configuration
• Legacy discovery alias: /oauth2/v1/discovery
• Authorization: /oauth2/v1/authorize
• Token: /oauth2/v1/token
• UserInfo: /oauth2/v1/userinfo
• JWKS: /oauth2/v1/jwks
• Legacy JWKS alias: /.well-known/jwks.json

When the configured issuer has a path component, discovery is also available at /{issuer_path}/.well-known/openid-configuration.

Development

composer install
vendor/bin/phing build
vendor/bin/psalm
php tests/security_regression.php

End-to-end tests live in playwright-tests/:

cd playwright-tests
npm install
npx playwright test

Create playwright-tests/.env from .env.example and configure a local phpBB user plus a matching OIDC test client in the ACP.