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",
  "scopes_supported": ["openid", "profile", "email", "address", "phone", "offline_access"],
  "response_types_supported": ["code", "id_token", "id_token token", "code id_token", "code token", "code id_token token"],
  "response_modes_supported": ["query", "fragment", "form_post"],
  "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
  "subject_types_supported": ["public", "pairwise"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "private_key_jwt"],
  "code_challenge_methods_supported": ["S256"]
}

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": "[email protected]",
  "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": "[email protected]",
  "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
offline_access	Returns refresh token

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