OIDC provider (Sign in with Ubikap)

Ubikap is an OpenID Connect provider. Your application redirects a Ubikap member to it, the member signs in, and your application receives tokens that identify the member and their office.

Discovery

Issuer	Discovery document
https://auth.external-integration.ubikap.dev	https://auth.external-integration.ubikap.dev/.well-known/openid-configuration

The same document is also served at /.well-known/oauth-authorization-server. Read every endpoint from it rather than hard-coding them.

Endpoints

Endpoint	Path
Authorization	/auth
Token	/token
UserInfo	/me
JWKS	/jwks
End session	/session/end
Introspection	/token/introspection
Revocation	/token/revocation

Dynamic client registration is not available.

Your client

Ubikap registers your client and sends you:

• the client_id, and the client_secret, which is shown only once;
• the redirect_uris you are allowed to use: HTTPS, without fragment (http://localhost is accepted outside production only);
• the scopes your client may request;
• the grant types: authorization_code, plus refresh_token if you need to act while the user is away.

Authenticate on the token, introspection and revocation endpoints with client_secret_basic (recommended) or client_secret_post.

Scopes and claims

Scope	Claims	Notes
openid	sub	Required.
office	office_key	Returned by /me only.
email	email
profile	given_name, family_name, name
offline_access	—	Issues a refresh token. Requires the refresh_token grant and prompt=consent.

Requesting a scope your client is not allowed returns invalid_scope.

Caution

The ID token contains only sub. Call /me with the access token to read office_key and the other claims.

Caution

An account that belongs to no office cannot be granted the office scope: the sign-in ends on the Ubikap error page. If the member later leaves their office, /me answers 401 invalid_token and a refresh answers 400 invalid_scope.

PKCE

PKCE is required for every client, confidential ones included, and only code_challenge_method=S256 is accepted. A request without code_challenge, or with plain, is rejected with invalid_request.

ID token signature

ID tokens are signed with ES512 (ECDSA on P-521, JWK kty: "EC"). Configure your client library to expect ES512: many default to RS256 and would reject the token.

• Select the verification key in /jwks by the token’s kid. The JWKS may publish keys for other algorithms: ignore them.
• Cache the JWKS, and fetch it again when you meet an unknown kid.
• After a key rotation, the retired key stays published for 24 hours, much longer than an ID token lives (1 hour).

Access tokens are opaque: do not try to decode them. Use /me, or /token/introspection, to learn about them.

Rate limits

Scope	Limit
Any endpoint	100 requests per minute per IP
/token, /token/introspection, /token/revocation	600 requests per minute per IP

Above the limit, the provider answers 429 with RateLimit and RateLimit-Policy headers. A user account is locked for 15 minutes after 10 failed passwords.

Errors

• Errors met in the browser (a sign-in left open for more than an hour, a rejected authorization request) end on the Ubikap SSO error page. Only your application can start a new authorization.
• When the member refuses the consent, your redirect_uri receives error=access_denied.
• The token endpoint answers standard OAuth 2.0 JSON errors: invalid_grant, invalid_scope, invalid_client, invalid_request.