Features

What Beffroi OP includes: OpenID Connect and SAML 2.0 on the same users and sessions, passkeys and multi-factor authentication, FAPI 2.0, key management, encryption at rest and logout, with a diagram for each.

OpenID Connect · SAML 2.0 · Passkeys · FAPI 2.0 · Key management

Architecture

One Symfony application serves the pages, the endpoints, the console and the background jobs. The protocol rules live in pure PHP packages with no dependency on HTTP.

Architecture of Beffroi OPUsers, client applications and SAML partners talk to one Symfony application. The application serves the pages, the endpoints, the console and the background work, and delegates every rule to three pure PHP packages: the identity core, OAuth 2.0 and OpenID Connect, and SAML 2.0 with XML security.PHP packagesThe applicationUsers, clients and partnersUsersin a browser, atthe sign-in pagesClient applicationsOpenID Connect,OAuth 2.0SAML partnersservice providers,identity providersThe pagessign-in and account:what a browser seesThe endpointswhat clients andpartners callConsole and workeroperator commands,what runs laterIdentity coreusers, credentials,sessions, keysOpenID Connectand OAuth 2.0:grants and tokensSAML 2.0both roles, XMLsignatures, bindings
Architecture of Beffroi OPUsers, client applications and SAML partners talk to one Symfony application. The application serves the pages, the endpoints, the console and the background work, and delegates every rule to three pure PHP packages: the identity core, OAuth 2.0 and OpenID Connect, and SAML 2.0 with XML security.PHP packagesPHP packagesThe applicationThe applicationUsers, clientsand SAML partnersPages and endpointsConsole and workerIdentity coreOpenID Connectand OAuth 2.0SAML 2.0
Fig. 01 Users, client applications and SAML partners talk to one application, beffroi/op, one image on FrankenPHP. The identity core holds the users, their credentials, their sessions, their groups and the keys; the two protocols are packages of their own beside it. For what runs next to the application, PostgreSQL and the key management service, see Fig. 02.

Deployment

Beffroi OP ships as a Docker image and a compose file that run the server, its worker and PostgreSQL next to the key management service you configure. Without one, the sodium backend seals the keys with a key generated once into a file. The same application runs from its source, on your own PHP 8.4 runtime and web server.

DeploymentBrowsers and applications reach the server. The server and its worker run from the same image and share PostgreSQL. Both ask the key management service to open the keys they use.One imageBrowsersThe serverFrankenPHP, worker modeYour applicationsThe workercallbacks, the journal,the timed stepsPostgreSQLthe model, and thequeues of the workerKey management serviceyours, or a sodiumkey in a file
DeploymentBrowsers and applications reach the server. The server and its worker run from the same image and share PostgreSQL. Both ask the key management service to open the keys they use.One imageBrowsers andyour applicationsThe serverFrankenPHP, workermodeThe workercallbacks, thejournal,the timed stepsPostgreSQLKey managementservice
Fig. 02 The server answers browsers and applications. The worker calls clients back, writes the audit log and runs the scheduled jobs. Both run from the same image, ghcr.io/beffroi-auth/op, share PostgreSQL, and ask the key management service to open the keys they use.

The image is built for amd64 and arm64, runs its two processes as an unprivileged user, terminates TLS itself or hands it to the proxy in front of it, and reads its whole configuration from the environment.

Single sign-on with OpenID Connect

Browsers sign in with the authorization code flow and PKCE. The implicit and password grants are not served.

Single sign-on with OpenID ConnectThe application sends the browser to Beffroi with a PKCE challenge. The user authenticates, Beffroi sends the browser back with a code, and the application exchanges that code for tokens with its verifier.Opens a page that needs a sign-inTo Beffroi, with a PKCE challengeAuthorization requestThe sign-in page: a passkey, a password, a one-time codeThe proofBack to the application, with a codeThe codeToken request, with the PKCE verifierID token, access token, refresh tokenBrowserYour applicationBeffroiBrowserYour applicationBeffroi
Single sign-on with OpenID ConnectThe application sends the browser to Beffroi with a PKCE challenge. The user authenticates, Beffroi sends the browser back with a code, and the application exchanges that code for tokens with its verifier.Opens apage thatneeds asign-inTo Beffroi,with a PKCEchallengeAuthorization requestThe sign-in page: apasskey, a password, aone-time codeThe proofBack to the application,with a codeThe codeTokenrequest,with thePKCEverifierID token,accesstoken,refreshtokenBrowserYourapplicationBeffroiBrowserYourapplicationBeffroi
Fig. 03 The application sends the browser to Beffroi with a PKCE challenge. The user authenticates, Beffroi sends the browser back with a code, and the application exchanges that code for tokens with its verifier.

The sign-in and consent pages carry the name, the logo and the two colours of the tenant, in English and in French, in light and in dark mode.

SAML 2.0

Beffroi acts as a SAML identity provider and as a SAML service provider. Both roles share the users and sessions of OpenID Connect: a browser signed in through one protocol is signed in for the other, and logout applies to both.

Identity provider for your applications

An application that speaks SAML authenticates its users with Beffroi: a SimpleSAMLphp or Shibboleth service provider, a product that requires a SAML identity provider, Microsoft Entra ID federating its guests.

SAML 2.0 identity provider for an applicationThe application sends the browser to Beffroi with an authentication request. Beffroi authenticates the user, or reuses the session already open, and posts a signed assertion back to the application, which verifies it against the metadata of Beffroi.Opens the applicationAuthnRequestover HTTP-Redirect or HTTP-POSTAuthnRequestThe sign-in page, or the session already openThe proofResponse with a signed assertionover HTTP-POSTResponseVerified against the metadata of BeffroiBrowserService provideryour applicationBeffroiidentity providerBrowserService provideryour applicationBeffroiidentity provider
SAML 2.0 identity provider for an applicationThe application sends the browser to Beffroi with an authentication request. Beffroi authenticates the user, or reuses the session already open, and posts a signed assertion back to the application, which verifies it against the metadata of Beffroi.Opens theapplicationAuthnRequestoverHTTP-RedirectorHTTP-POSTAuthnRequestThe sign-in page, or thesession already openThe proofResponse with a signedassertionover HTTP-POSTResponseVerifiedagainstthemetadataofBeffroiBrowserServiceprovideryourapplicationBeffroiidentityproviderBrowserServiceprovideryourapplicationBeffroiidentityprovider
Fig. 04 The application sends the browser to Beffroi with an authentication request. Beffroi authenticates the user, or reuses the session already open, and posts a signed assertion back, which the application verifies against the metadata of Beffroi.

Service provider for an organisation

The users of an organisation sign in through the organisation's own identity provider, discovered from their email domain. The account is created at first sign-in with its groups mapped, and never holds a local password.

SAML 2.0 service provider for the identity provider of an organisationThe user types their email address. Its domain names the identity provider of their organisation, where they sign in. The assertion comes back to Beffroi, which creates the user at their first sign-in, maps their groups, and sends the browser back to the application that was waiting.The sign-in page: the email addressAuthnRequest, signedAuthnRequestThe organisation's own sign-inThe proofResponse with a signed assertionResponseSigned in, back to the applicationThe domain of theaddress names theidentity providerThe user is created at their first sign-in,their groups mappedBrowserBeffroiservice providerIdentity providerof theorganisationBrowserBeffroiservice providerIdentity providerof theorganisation
SAML 2.0 service provider for the identity provider of an organisationThe user types their email address. Its domain names the identity provider of their organisation, where they sign in. The assertion comes back to Beffroi, which creates the user at their first sign-in, maps their groups, and sends the browser back to the application that was waiting.Thesign-inpage: theemailaddressAuthnRequest,signedAuthnRequestThe organisation's ownsign-inThe proofResponse with a signedassertionResponseSignedin, backto theapplicationThe domain ofthe addressnames theidentityproviderThe user iscreated attheir firstsign-in,their groupsmappedBrowserBeffroiserviceproviderIdentityproviderof theorganisationBrowserBeffroiserviceproviderIdentityproviderof theorganisation
Fig. 05 The domain of the address selects the identity provider. The user signs in there, the assertion comes back to Beffroi, and the browser returns to the application that was waiting.

Passkeys and multi-factor authentication

A user can hold a password, several passkeys and a one-time code generator with its backup codes, each revocable on its own.

  • Passkeys, usable as the only credential, with no password.
  • One-time codes from an authenticator application, with backup codes shown once.
  • Passwords with a minimum length, and refused when a list of compromised values you configure contains them.
  • Minimum authentication level per tenant: one factor, two factors, phishing-resistant, or phishing-resistant on hardware.
  • Enrolment tickets: a first passkey registered from a link the operator provides, so that a tenant can run without passwords.

FAPI 2.0

For clients that require the financial-grade profile: authorization requests pushed or signed, responses signed, and tokens bound to the client's key or certificate, on the same endpoints as every other client.

FAPI 2.0The request is pushed to the provider first or signed by the client, the answer is signed, and the token is bound to a key or a certificate of the client, so that a stolen token opens nothing.The requestpushed to the providerfirst, or signed by theclientThe answersigned, and encrypted onrequestThe tokenbound to a key or acertificate of the client:stolen, it opens nothing
FAPI 2.0The request is pushed to the provider first or signed by the client, the answer is signed, and the token is bound to a key or a certificate of the client, so that a stolen token opens nothing.The requestpushed to theprovider first, orsigned by the clientThe answersigned, and encryptedon requestThe tokenbound to a key or acertificate of theclient:stolen, it opensnothing
Fig. 06 Pushed authorization requests and signed request objects on the way in, signed responses on the way out, and tokens bound with DPoP or mutual TLS.

Grants for services and devices

Client credentials for services, device authorization for devices without a keyboard, CIBA for approval on another device, and token exchange for gateways acting on behalf of a caller.

Grants for services and devicesA service with no user uses client credentials. A device with no keyboard uses the device authorization grant. A user who approves on their own device uses CIBA. A gateway acting for a caller uses token exchange. Each one ends with an access token.A serviceno user behind itClient credentialsA device, no keyboarda command line,a televisionDevice authorizationA userwho approveson their own deviceCIBAby poll or by pingA gatewayacting for its callerToken exchangeAn access tokena JWT, or anopaque reference
Grants for services and devicesA service with no user uses client credentials. A device with no keyboard uses the device authorization grant. A user who approves on their own device uses CIBA. A gateway acting for a caller uses token exchange. Each one ends with an access token.GrantsClient credentialsa service withno user behind itDevice authorizationa device withno keyboardCIBA, by poll or pinga user who approveson their own deviceToken exchangea gateway actingfor its callerAn access tokena JWT, or anopaque reference
Fig. 07 A service with no user behind it, a device with no keyboard, a user who approves on their own device, a gateway acting for its caller: each one has its grant, and each one ends with an access token.

Key management

The master key stays in your key management service. Signing keys are generated in the process, sealed, and only then written to disk: a copy of the database and of the files is unreadable without the service.

Key managementThe key management service holds the master key and seals each signing key in a file of its own. The provider opens a key once per process, publishes its public part in the JWK Set and signs with its private part.sealsopened once per processpublishes the public partsigns with the private partKey management serviceholds the master key,never signsEach signing keyin a file of its ownThe providerThe JWK SetTokens and assertions
Key managementThe key management service holds the master key and seals each signing key in a file of its own. The provider opens a key once per process, publishes its public part in the JWK Set and signs with its private part.sealsopened once per processthe public partthe private partKey managementserviceholds the master key,never signsEach signing keyin a file of its ownThe providerThe JWK SetTokens andassertions
Fig. 08 The key management service seals each signing key. The provider opens it once per process, publishes its public part in the JWK Set and signs with its private part.

Key rotation

The next key is published before it signs, and the previous one stays published until the last token it signed has expired, so that clients never receive a token they cannot verify. A compromised key is removed immediately.

Supported KMS AWS KMS · HashiCorp Vault · OpenBao · Sodium key file

Encryption of personal data

Names, addresses and session origins are encrypted in their column under a data key of the tenant. A test scans a dump of the database byte by byte and fails if it finds a value in clear.

Encryption of personal dataThe key management service wraps a data key per tenant and per family of columns. That key seals each personal column. A lookup that must still work goes through a blind index, a keyed tag of the value.wrapssealsis looked up throughKey management serviceA data keyper tenant and family ofcolumnsEach personal columnnames, addresses, where asession came fromA blind indexa keyed tag, never thevalue
Encryption of personal dataThe key management service wraps a data key per tenant and per family of columns. That key seals each personal column. A lookup that must still work goes through a blind index, a keyed tag of the value.wrapssealsis looked up throughKey managementserviceA data keyper tenant and familyof columnsEach personal columnnames, addresses,where a session camefromA blind indexa keyed tag, neverthe value
Fig. 09 A data key per tenant and per family of columns, wrapped by the key management service, seals each personal column. A lookup that must still work, such as a sign-in by username, matches a blind index.

Logout

When a session ends, its tokens are revoked and every application signed in under it is notified, whichever protocol it uses.

LogoutHowever a session ends, its refresh tokens are revoked and its opaque access tokens removed, the other clients are told through the browser or server to server, and each SAML service provider of the session is logged out.A session endsat the end sessionendpoint, from the accountpage, by the console or bya SAML logoutRefresh tokens revokedopaque access tokensremovedFront-channel logoutthe other clients, toldthrough the browserBack-channel logouttold server to server,with a signed logout tokenSAML Single Logouteach service provider ofthe session
LogoutHowever a session ends, its refresh tokens are revoked and its opaque access tokens removed, the other clients are told through the browser or server to server, and each SAML service provider of the session is logged out.A session endsRefresh tokensrevoked,opaque access tokensremovedFront-channel logout,through the browserBack-channel logout,server to serverSAML Single Logout,each service provider
Fig. 10 The end of a session revokes its refresh tokens and removes its opaque access tokens, notifies the other clients through the browser or server to server, and logs out each SAML service provider of the session.

Account management and audit log

Users manage their own account: profile, passkeys and codes, sessions, consents, and an export of everything the provider holds about them. The audit log records who did what, when and from where, with a retention period set by the deployment.

Get started with Beffroi OP.

Security Specifications