OpenID Connect (OIDC)

Authrim provides full OpenID Connect Core 1.0 compliance, enabling secure authentication for your applications.

Overview

• Standard: OpenID Connect Core 1.0
• Conformance: OpenID Certification conformance test suite compatible
• Discovery: Full OIDC Discovery support

Supported Flows

Authorization Code Flow with PKCE (Recommended)

The most secure flow for all client types:

Client → Authorization Endpoint → User Login → Authorization Code
Client → Token Endpoint (+ PKCE) → Access Token + ID Token

Hybrid Flow

For applications that need both immediate identity verification and backend token exchange:

• code id_token
• code token
• code id_token token

Implicit Flow

For legacy applications only (not recommended for new implementations):

• id_token
• id_token token

Discovery Endpoint

Retrieve the OpenID Provider configuration:

GET /.well-known/openid-configuration

Response:

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "userinfo_endpoint": "https://auth.example.com/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "registration_endpoint": "https://auth.example.com/register",
  "introspection_endpoint": "https://auth.example.com/introspect",
  "revocation_endpoint": "https://auth.example.com/revoke",
  "pushed_authorization_request_endpoint": "https://auth.example.com/par",
  "device_authorization_endpoint": "https://auth.example.com/device_authorization",
  "scopes_supported": ["openid", "profile", "email", "address", "phone"],
  "response_types_supported": ["code", "id_token", "id_token token", "code id_token", "code token", "code id_token token", "none"],
  "response_modes_supported": ["query", "fragment", "form_post", "query.jwt", "fragment.jwt", "form_post.jwt", "jwt"],
  "grant_types_supported": ["authorization_code", "refresh_token", "implicit", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:device_code", "urn:openid:params:grant-type:ciba", "urn:ietf:params:oauth:grant-type:token-exchange", "client_credentials"],
  "subject_types_supported": ["public", "pairwise"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt", "none"],
  "code_challenge_methods_supported": ["S256"],
  "dpop_signing_alg_values_supported": ["ES256", "RS256", "PS256", "EdDSA"],
  "end_session_endpoint": "https://auth.example.com/logout"
}

Grant types and optional async endpoints are filtered by tenant profile and feature flags, so production metadata should be treated as the source of truth for each tenant.

JWKS Endpoint

Retrieve the JSON Web Key Set for ID token verification:

GET /.well-known/jwks.json

Response:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Authorization Flow

1. Authorization Request

GET /authorize
  ?response_type=code
  &client_id=my_client_id
  &redirect_uri=https://myapp.example.com/callback
  &scope=openid+profile+email
  &state=random_state_value
  &nonce=random_nonce_value
  &code_challenge=...
  &code_challenge_method=S256
Host: auth.example.com

Parameters:

Parameter	Required	Description
response_type	Yes	code for authorization code flow
client_id	Yes	Client identifier
redirect_uri	Yes	Registered redirect URI
scope	Yes	Must include openid
state	Recommended	CSRF protection
nonce	Required for OIDC	ID token binding
code_challenge	Recommended	PKCE code challenge
code_challenge_method	Recommended	Must be S256

2. User Authentication

User is redirected to the login page and authenticates.

3. Authorization Response

HTTP/1.1 302 Found
Location: https://myapp.example.com/callback
  ?code=authorization_code_value
  &state=random_state_value

4. Token Request

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=authorization_code
&code=authorization_code_value
&redirect_uri=https://myapp.example.com/callback
&code_verifier=pkce_code_verifier

5. Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9...",
  "scope": "openid profile email"
}

ID Token

The ID Token is a JSON Web Token (JWT) containing user identity claims:

{
  "iss": "https://auth.example.com",
  "sub": "user-id-123",
  "aud": "my_client_id",
  "exp": 1699880000,
  "iat": 1699876400,
  "nonce": "random_nonce_value",
  "auth_time": 1699876400,
  "acr": "urn:mace:incommon:iap:silver",
  "at_hash": "...",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true
}

Standard Claims

Claim	Description
iss	Issuer identifier
sub	Subject identifier (user ID)
aud	Audience (client ID)
exp	Expiration time
iat	Issued at time
nonce	Nonce from authorization request
auth_time	Time of authentication
acr	Authentication context class reference
amr	Authentication methods reference
at_hash	Access token hash
c_hash	Code hash (hybrid flow)

Profile Scope Claims

Claim	Description
name	Full name
given_name	First name
family_name	Last name
nickname	Nickname
preferred_username	Preferred username
picture	Profile picture URL
locale	Locale
zoneinfo	Time zone
updated_at	Last update time

Email Scope Claims

Claim	Description
email	Email address
email_verified	Email verification status

UserInfo Endpoint

Retrieve user profile information:

GET /userinfo HTTP/1.1
Authorization: Bearer <access_token>

Response:

{
  "sub": "user-id-123",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "john@example.com",
  "email_verified": true,
  "picture": "https://example.com/photo.jpg"
}

Client Registration

Dynamic Client Registration

POST /register HTTP/1.1
Content-Type: application/json

{
  "client_name": "My Application",
  "redirect_uris": ["https://myapp.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic"
}

Response:

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "client_id_issued_at": 1699876400,
  "client_secret_expires_at": 0,
  "redirect_uris": ["https://myapp.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Scopes

Scope	Description
openid	Required for OIDC, returns sub claim
profile	Returns profile claims (name, picture, etc.)
email	Returns email and email_verified claims
address	Returns address claim
phone	Returns phone_number and phone_number_verified

Refresh token availability is controlled by client metadata and tenant profile. Use the refresh_token grant advertised in discovery instead of assuming an offline_access scope.

Security Best Practices

1. Always use PKCE - Prevents authorization code interception
2. Use state parameter - Prevents CSRF attacks
3. Use nonce parameter - Prevents ID token replay
4. Validate ID tokens - Verify signature, issuer, audience, expiration
5. Use short-lived tokens - Minimize impact of token theft
6. Implement proper logout - Revoke tokens on logout

References

• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• OpenID Connect Dynamic Client Registration