Table of Contents

OpenID Connect Integration Overview

Introduction to PhenixID Authentication Services (PAS) OpenID Connect

PhenixID Authentication Services (PAS) provides a highly secure and flexible solution for implementing OpenID Connect (OIDC) and OAuth 2.0 flows, offering tailored authentication and authorization capabilities that support a wide variety of applications, from single-page applications (SPAs) to server-side systems and complex hybrid environments. By integrating OIDC and OAuth 2.0 protocols, PAS allows organizations to provide seamless, secure Single Sign-On (SSO) experiences while offering robust token management, consent options, and session control. With features like PKCE for added protection on public clients, customizable claims, and multiple token formats, PAS ensures that organizations can achieve fine-grained access control while safeguarding user data privacy.

This document provides a detailed overview of the PAS-supported OIDC flows, configuration options for claims, introspection and revocation endpoints, and available security enhancements, including PKCE, various client authentication methods, and consent management.

Supported OIDC Flows

PhenixID Authentication Services (PAS) supports the three main OpenID Connect (OIDC) flows—Authorization Code, Implicit, and Hybrid—each catering to different application requirements and security levels.

All flows are enabled by default when you setup the OIDC open provider in pas.

Authorization Code flow

Authorization Code Flow is best suited for server-side applications that can securely store a client secret. In this flow, the Relying Party (client) first receives an authorization code from PAS, which it then exchanges for an ID token and access token through a secure backend call to the token endpoint. This two-step process is highly secure, as sensitive tokens are only obtained server-side and not exposed to the user’s browser.

Authorization Code Flow Sequence

sequenceDiagram
    participant UserAgent
    participant RP as Relying Party (Client)
    participant OP as OpenID Provider (PAS)

    UserAgent ->>+ RP: 1. User initiates login
    RP ->>+ OP: 2. Redirect to Authorization Endpoint
    OP ->>+ UserAgent: 3. Prompt user for authentication
    UserAgent ->>+ OP: 4. User authenticates
    OP -->> UserAgent: 5. Redirect with Authorization Code
    UserAgent ->>+ RP: 6. Authorization Code sent to RP
    RP ->>+ OP: 7. Request tokens at Token Endpoint
    OP -->> RP: 8. Respond with ID Token and Access Token
    RP -->> UserAgent: 9. User gains access to RP

Authorization Endpoint and Token Exchange Process

To begin authentication, redirect the client to the authorization endpoint. Construct the authorization URL with the following structure and parameters:

<authorization_endpoint_url>?response_type=code
&client_id=<client_id_assigned_by_op_admin>
&scope=openid
&redirect_uri=<url_encoded_redirect_uri>
&nonce=<unique_nonce_generated_by_you>
&state=<optional_state_value_for_response_tracking>

Parameter Explanation:

  • response_type: Use code to initiate the Authorization Code Flow.
  • client_id: The identifier assigned to your client by the OpenID Provider administrator.
  • scope: Specifies the permissions requested; at minimum, use openid.
  • redirect_uri: The callback URI where the OpenID Provider will redirect after authentication.
  • nonce: A random, unique string to prevent replay attacks.
  • state (optional): A unique identifier that you can use to track and validate the response.

Upon successful authentication, the OpenID Provider will redirect to your specified redirect_uri, appending an authorization code in the code query parameter:

<redirect_uri>?code=<authorization_code>

To exchange this authorization code for tokens, send an HTTP POST request to the token endpoint with the following parameters. Note: This exchange must occur on a secure backend server, not directly on the client.

POST <token_endpoint_url>
code=<authorization_code_from_previous_step>
&client_id=<client_id_assigned_by_pas_admin>
&scope=openid
&redirect_uri=<url_encoded_redirect_uri>
&client_secret=<client_secret_assigned_by_pas_admin>
&grant_type=authorization_code

Details of Token Request Parameters:

  • code: The authorization code received from the OpenID Provider.
  • client_id: The client ID assigned by the OpenID Provider administrator.
  • scope: Should include openid.
  • redirect_uri: The same redirect_uri used in the initial request.
  • client_secret: The client secret assigned by the OpenID Provider, required to authenticate the request.
  • grant_type: Set this to authorization_code to specify the authorization grant type.

A successful response will return an HTTP 200 status with a JSON payload, containing the tokens (such as ID and access tokens) needed for accessing protected resources on behalf of the user.

Example response:

{
  "id_token": "base64_encoded_token_data",
  "access_token": "base64_encoded_token_data",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "970cbfa0-9bc5-4666-b8dd-28b60874b417"
}

Implicit flow

Implicit Flow is intended for single-page or client-side applications where keeping a client secret secure is not feasible. Here, the client requests an ID token (and optionally an access token) directly from the authorization endpoint. Tokens are delivered immediately through a redirect back to the client, without needing an authorization code or backend exchange. However, since tokens are visible in the browser, this flow offers less security than the authorization code flow and is typically used for applications with more limited access needs.

Implicit Flow Sequence

sequenceDiagram
    participant UserAgent
    participant RP as Relying Party (Client)
    participant OP as OpenID Provider (PAS)

    UserAgent ->>+ RP: 1. User initiates login
    RP ->>+ OP: 2. Redirect to Authorization Endpoint (Request ID Token)
    OP ->>+ UserAgent: 3. Prompt user for authentication
    UserAgent ->>+ OP: 4. User authenticates
    OP -->> UserAgent: 5. Redirect with ID Token (and optionally Access Token)
    UserAgent ->>+ RP: 6. ID Token (and Access Token) sent to RP
    RP -->> UserAgent: 7. User gains access to RP

Authorization Endpoint and Token Delivery in Implicit Flow

In the Implicit Flow, redirect the client to the authorization endpoint with the required parameters embedded in the URL:

<authorization_endpoint_url>?response_type=id_token%20token
&client_id=<client_id_assigned_by_op_admin>
&scope=openid
&redirect_uri=<url_encoded_redirect_uri>
&nonce=<unique_nonce_generated_by_you>
&state=<optional_state_value_for_response_tracking>

Key parameters include:

  • response_type: Use id_token token to request an ID token and, optionally, an access token.
  • redirect_uri: The URI to which the OpenID Provider will redirect the client after authentication.
  • nonce: A unique string to prevent replay attacks.
  • state (optional): Used to track the response.

Upon successful authentication, the OpenID Provider will redirect to your redirect_uri, including the ID token (and optionally the access token) in the URL fragment:

<redirect_uri>#id_token=<id_token>&access_token=<access_token>&state=<state_value>

Unlike the Authorization Code Flow, no backend exchange is needed, as tokens are delivered directly to the client. The application can then use these tokens to access protected resources.

Hybrid flow

Hybrid Flow provides flexibility for applications requiring both immediate access and secure backend processing. In this flow, the client receives an ID token along with an authorization code. This setup allows the application to verify the user’s identity with the ID token right away, while still using the authorization code to request additional tokens through the backend, combining aspects of both the authorization code and implicit flows for added security. The Hybrid Flow in OpenID Connect is seldom used because it is a complex and specialized flow that is typically only necessary for specific use cases where both immediate access to user information and backend security are required.

Hybrid Flow Sequence

sequenceDiagram
    participant UserAgent
    participant RP as Relying Party (Client)
    participant OP as OpenID Provider (PAS)

    UserAgent ->>+ RP: 1. User initiates login
    RP ->>+ OP: 2. Redirect to Authorization Endpoint (Request ID Token and Code)
    OP ->>+ UserAgent: 3. Prompt user for authentication
    UserAgent ->>+ OP: 4. User authenticates
    OP -->> UserAgent: 5. Redirect with ID Token and Authorization Code
    UserAgent ->>+ RP: 6. ID Token and Code sent to RP
    RP ->>+ OP: 7. Request Access Token at Token Endpoint using Code
    OP -->> RP: 8. Respond with Access Token
    RP -->> UserAgent: 9. User gains access to RP

Authorization Endpoint and Token Delivery in Hybrid Flow

In the Hybrid Flow, redirect the client to the authorization endpoint with the following parameters:

<authorization_endpoint_url>?response_type=code%20id_token
&client_id=<client_id_assigned_by_op_admin>
&scope=openid
&redirect_uri=<url_encoded_redirect_uri>
&nonce=<unique_nonce_generated_by_you>
&state=<optional_state_value_for_response_tracking>

Key parameters include:

  • response_type: Use code id_token to request an authorization code, ID token, and access token.
  • redirect_uri: The URI where the OpenID Provider will redirect the client after authentication.
  • nonce: A unique string to prevent replay attacks.
  • state (optional): Used to track the response.

Upon successful authentication, the OpenID Provider will redirect to the specified redirect_uri, including the ID token, access token, and authorization code in the URL fragment:

<redirect_uri>#id_token=<id_token>&code=<authorization_code>&state=<state_value>

The client application can immediately use the ID token for client-side access to resources. To securely obtain additional tokens, the client’s backend server can exchange the authorization code for further tokens, typically a access token, through a backend call to the token endpoint.

To complete the Hybrid Flow, the backend must securely exchange the authorization code for tokens by calling the token endpoint with the following parameters:

POST <token_endpoint_url>
code=<authorization_code_from_redirect>
&client_id=<client_id_assigned_by_op_admin>
&redirect_uri=<url_encoded_redirect_uri>
&client_secret=<client_secret_assigned_by_op_admin>
&grant_type=authorization_code
  • code: The authorization code received from the OpenID Provider.
  • client_secret: The secret provided by the OpenID Provider to authenticate the backend request.
  • grant_type: Set to authorization_code to specify the authorization grant type.

Upon a successful exchange, the OpenID Provider will respond with a JSON payload, typically including tokens such as an access token, and refresh token, enabling long-lived, backend-controlled access for the client.

The Hybrid Flow thus combines immediate client access with secure backend token management, providing flexibility for applications that require both quick access to user data and enhanced security for long-term sessions.

Supported Response Modes

PhenixID Authentication Services (PAS) offers multiple response modes within its OpenID Connect (OIDC) flows, each providing a different method for returning tokens and authorization codes to client applications. The supported response modes—query, fragment, and form_post—allow PAS to adapt to different security requirements and client application types.

Query Mode (response_mode=query)

In query mode, PAS returns response parameters in the URL's query string. This mode is straightforward and convenient for server-side applications that can securely handle these query parameters on the backend. For example, when using the Authorization Code Flow, the authorization code can be delivered in the query string to a secure redirect_uri, where the backend exchanges it for tokens. This mode is generally best for scenarios where the URL does not risk exposure to unauthorized parties (e.g., server logs or browser history).

Fragment Mode (response_mode=fragment)

The fragment mode returns response parameters in the URL fragment (the part following #), which is not typically sent to servers during requests. This mode is often used for client-side applications, like Single Page Applications (SPAs), where response parameters (such as ID tokens or access tokens) are processed directly by the client. By using the URL fragment, sensitive data is less likely to be exposed in server logs or other places where query parameters may be visible.

Form Post Mode (response_mode=form_post)

The form_post response mode allows PAS to return response parameters, such as authorization codes or tokens, securely in the body of an HTTP POST request. Rather than appending sensitive data in the URL, PAS submits the response to the redirect_uri as form-encoded data within an HTML form. This mode provides enhanced security by avoiding exposure of tokens in the URL, making it particularly suitable for applications with stringent security requirements.

Benefits of form_post in PAS

Using form_post is beneficial for:

  • Server-Side Applications: Server-side applications handling sensitive data benefit from receiving response parameters in the POST body, as they can handle these securely without exposing them in the browser’s URL.
  • Single Page Applications (SPAs) with PKCE: SPAs using the Authorization Code Flow with Proof Key for Code Exchange (PKCE) can leverage form_post to secure the delivery of authorization codes.
  • Compliance with Security Policies: Many security policies mandate that sensitive data should not appear in URLs. Using form_post helps organizations meet these requirements while preserving a secure, user-friendly experience.
Example form_post Request

To implement form_post in an OIDC flow, include response_mode=form_post in the authorization request parameters:

https://pas.example.com/authentication/oidc/t1/authorize
?response_type=code
&client_id=your_client_id
&redirect_uri=https://clientapp.com/callback
&scope=openid profile
&response_mode=form_post
&nonce=unique_nonce_value
&state=optional_state_value

Upon successful authentication, PAS will redirect to the specified redirect_uri and deliver the response parameters in the body of a POST request.

Example Response:

<form method="post" action="https://clientapp.com/callback">
    <input type="hidden" name="code" value="authorization_code_value">
    <input type="hidden" name="state" value="optional_state_value">
    <input type="hidden" name="session_state" value="unique_session_state_value">
    <input type="submit" value="Submit">
</form>

Using form_post in PAS provides an additional layer of security by ensuring that sensitive information is not exposed in the URL, allowing for secure OIDC interactions across client types and flow configurations.

By including this section in "Supported OIDC Flows", readers get a comprehensive overview of response modes available in PAS and the flexibility to choose the most secure and appropriate mode for their application requirements.

Types of Tokens Issued by PAS

ID Token

  • The ID token is always issued as a JSON Web Token (JWT) and includes verified information about the authenticated user, such as their unique identifier (sub), name, email, and other profile claims. Its primary purpose is to allow the client application to confirm the user’s identity immediately after authentication.
  • ID tokens are typically short-lived and cannot be refreshed directly, as they capture the user’s identity at the time of login.

Example ID token:

{
    "header": {
        "alg": "RS256",
        "typ": "JWT",
        "kid": "0d8cdiAk5cr78BD3KrVc9uExkLw"
    },
   "payload": {
        "iat": 1730991552,
        "nbf": 1730991552,
        "exp": 1730991642,
        "jti": "3aa71f2c-4867-4967-8440-55346ac728e6",
        "sub": "12312314412",
        "aud": "test",
        "azp": "test",
        "iss": "https://phenixid.se/t1",
        "nonce": "",
        "at_hash": "TnvhegvD2Umb_oQ0DAV51A",
        "sid": "x9VItB3ni8MXyqg5s7RjVfcXZye8PmkaLRGp5T5d5t3Rn3N268dxqRwID6sG31SSZKWeUw=="
    },
    "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Access Token

  • Access tokens enable client applications to access protected resources on behalf of the user. PAS can issue access tokens in either an opaque format or as JWTs, depending on application needs:
  • Opaque Access Tokens: These are non-readable random strings with no embedded information. To validate an opaque token, the resource server must contact PAS’s introspection endpoint.

Example opaque access token:

{
    "access_token": "Y2hlY2t0aGlzb3V0d29ya2luZw"
}
  • JWT Access Tokens: These tokens are self-contained and include claims, scopes, and expiration details directly in the token. Resource servers can validate JWT access tokens locally by checking the token’s signature, eliminating the need for introspection calls to the OP.

Example JWT access token:

{
    "header": {
        "alg": "RS256",
        "typ": "at+jwt",
        "kid": "0d8cdiAk5cr78BD3KrVc9uExkLw"
    },
    "payload": {
        "iat": 1730991552,
        "nbf": 1730991552,
        "exp": 1730993352,
        "jti": "a3b8f48a-e4a8-40a0-b0c1-be9de79d38b5",
        "sub": "12312314412",
        "aud": "test",
        "client_id": "test",
        "iss": "https://phenixid.se/t1",
        "scope": "openid profile"
    },
    "signature": "d2h6x0RLSME7KTJQ84fLM9JGyzP7RQp6MJN_ddEqn5b"
}

Refresh Token

  • Refresh tokens allow clients to request new access tokens without re-authenticating the user, supporting long-lived sessions. Refresh tokens are opaque and are meant to be stored and handled securely on the backend.
  • These tokens are usually long-lived but can be configured to expire or be revoked for additional security control.

Example refresh token:

{
    "refresh_token": "dGhpcy1pcy1hLXNhbXBsZS1yZWZyZXNoLXRva2Vu"
}

Configuring Token Lifetimes and Refresh Options in PAS

PAS allows administrators to customize the lifetime of each token type to balance security and convenience:

  • ID Token Lifetime: Is set to 90 seconds, ensuring that the user’s identity is verified only for the duration of a session.
  • Access Token Lifetime: Often configured to last 30–60 minutes, allowing for periodic refreshes to limit exposure if a token is compromised.
  • Refresh Token Lifetime: Generally set to days or weeks, allowing Relaying Parties to request new access tokens over extended sessions without requiring the user to log in again.

With PAS’s robust token management, administrators can optimize authentication and authorization by choosing between opaque and JWT access tokens, setting appropriate token lifetimes, and configuring refresh options. This flexibility ensures that PAS can support secure, scalable, and user-friendly authentication flows for a wide range of applications.

OpenID Connect Discovery in PhenixID Authentication Services

OpenID Connect (OIDC) Discovery provides a standardized way for client applications to dynamically obtain configuration details about an OpenID Provider (OP). Through a well-known URL, the OP exposes metadata such as endpoints, supported features, and available authentication methods, allowing clients to set up interactions with the OP without manual configuration.

In PhenixID Authentication Services (PAS), this discovery document is available at:

https://phenixid.se/t1/.well-known/openid-configuration

Here, "t1" is an example tenant name that represents a specific instance or customer configuration within PAS.

This endpoint returns the following JSON metadata, which includes essential URLs and supported options for OIDC and OAuth 2.0 interactions:

{
  "issuer": "https://phenixid.se/t1",
  "authorization_endpoint": "https://phenixid.se/authentication/oidc/t1/login",
  "token_endpoint": "https://phenixid.se/authentication/oidc/t1/token",
  "jwks_uri": "https://phenixid.se/t1/.well-known/openid-configuration/jwks",
  "userinfo_endpoint": "https://phenixid.se/authentication/oidc/t1/userinfo",
  "end_session_endpoint": "https://phenixid.se/authentication/oidc/t1/logout",
  "introspection_endpoint": "https://phenixid.se/authentication/oidc/t1/introspection",
  "revocation_endpoint": "https://phenixid.se/authentication/oidc/t1/revocation",
  "check_session_iframe": "https://phenixid.se/authentication/oidc/t1/check_session",
  "scopes_supported": ["openid"],
  "response_types_supported": ["code", "id_token", "id_token token", "code token", "code id_token", "code id_token token"],
  "response_modes_supported": ["query", "fragment", "form_post"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "client_secret_jwt", "private_key_jwt"],
  "token_endpoint_auth_signing_alg_values_supported": ["RS256", "HS256"],
  "claims_supported": ["sub", "name", "given_name", "mobile"],
  "request_parameter_supported": true
}

Field Explanations:

  • issuer: The base URL identifying the OP as the token issuer.
  • authorization_endpoint: URL where users authenticate and authorize the client.
  • token_endpoint: URL for exchanging authorization codes for tokens.
  • jwks_uri: URL for public keys used to validate token signatures.
  • userinfo_endpoint: URL for obtaining user profile data.
  • end_session_endpoint: URL to end the user session and log out.
  • introspection_endpoint: URL for validating token status and details.
  • revocation_endpoint: URL for invalidating tokens.
  • check_session_iframe: URL for session management between the client and OP.

Supported Options

  • scopes_supported: Available scopes, specifying the data clients can request.
  • response_types_supported: Types of responses supported, like code, id_token.
  • response_modes_supported: Methods for returning responses (e.g., query, fragment).
  • grant_types_supported: OAuth grant types available (e.g., authorization_code, refresh_token).
  • subject_types_supported: Types of user identifiers supported (public).
  • id_token_signing_alg_values_supported: Algorithms for signing ID tokens (RS256).
  • token_endpoint_auth_methods_supported: Client authentication methods for the token endpoint.
  • token_endpoint_auth_signing_alg_values_supported: Supported algorithms for client authentication.
  • claims_supported: Claims that can be included in tokens, like sub.
  • request_parameter_supported: Indicates if request parameters can be included in authorization requests.

This discovery document allows clients to configure themselves for secure and compatible OIDC and OAuth interactions with PAS.

Claims and Scopes Customization

In PhenixID Authentication Services (PAS), mapping claims to scopes enables administrators to control the specific user information (claims) that client applications can access, based on the requested scopes. This mapping process helps manage privacy and security by ensuring that only authorized information is exposed according to what the client requests and the scopes that have been granted.

How Mapping Claims to Scopes Works in PAS

Defining Scopes and Claims:

  • In PAS, scopes are categories of access that represent groups of user claims. For example, the profile scope may include claims like name, given_name, and family_name, while the email scope may include claims like email and email_verified.
  • Claims are individual pieces of information about the user, such as sub (user identifier), email, name, or address.

Mapping Claims to Scopes:

  • PAS allows administrators to configure which claims are associated with each scope. For example, the administrator can decide that only certain claims (e.g., name and email) are part of the profile scope, while more sensitive claims (e.g., address) may be included only in a dedicated address scope.
  • This mapping is done in the PAS configuration, where each scope can be assigned specific claims based on the organization's needs and data privacy requirements.

Authorization Based on Requested Scopes:

  • When a client application requests specific scopes during authentication (e.g., openid profile email), PAS checks which claims are mapped to these scopes.
  • Only the claims associated with the requested and granted scopes are included in the ID token or made available via the userinfo endpoint. For example, if the client requests the email scope, the claims email and email_verified might be included in the response.

Customizing Claims in Tokens and userinfo Endpoint:

  • PAS allows administrators to control which claims appear in the ID token and which are available via the userinfo endpoint. For example, some basic claims, like sub, might be included in the ID token by default, while more detailed claims (e.g., address) might only be accessible through the userinfo endpoint if the corresponding scope is requested and granted.
  • This distinction enables a clear separation between essential identity claims in the ID token and additional, potentially sensitive information retrieved via the userinfo endpoint.

Example: Mapping Claims to Scopes in PAS

Consider the following configuration example:

  • profile scope: Includes name, given_name, family_name.
  • email scope: Includes email, email_verified.
  • address scope: Includes address (structured address information).

If a client requests the profile and email scopes, the response might include claims for name, given_name, family_name, email, and email_verified, but not address, as that is tied to the address scope.

By mapping claims to scopes in this way, PAS allows fine-grained control over user data, ensuring that client applications only access the necessary information as authorized, protecting user privacy while maintaining flexibility in data sharing.

Here’s the example mapping for profile, email, and address scope:

"scope_claims" : [ 
  {
    "name" : "openid",
    "claims" : [ 
      {
        "name" : "sub",
        "include_in_id_token" : "true",
        "type" : "string"
      }
    ]
  },
  {
    "name" : "profile",
    "claims" : [ 
      {
        "name" : "name",
        "include_in_id_token" : "true",
        "type" : "string"
      },
      {
        "name" : "given_name",
        "include_in_id_token" : "true",
        "type" : "string"
      },
      {
        "name" : "family_name",
        "include_in_id_token" : "true",
        "type" : "string"
      }
    ]
  },
  {
    "name" : "email",
    "claims" : [ 
      {
        "name" : "email",
        "include_in_id_token" : "true",
        "type" : "string"
      },
      {
        "name" : "email_verified",
        "include_in_id_token" : "true",
        "type" : "boolean"
      }
    ]
  },
  {
    "name" : "address",
    "claims" : [ 
      {
        "name" : "address",
        "include_in_id_token" : "false",
        "type" : "object",
        "item_property_name": "street_address",
      }
    ]
  }
]

Read more about scope mapping here.

Retrieving User Information from the userinfo Endpoint in OpenID Connect

The userinfo endpoint in PhenixID Authentication Services (PAS) allows Relaying Parties to request additional user information not included in the ID token. Using an access token, clients can retrieve specific user claims (such as name, email, or profile details) based on the authorized scopes. This setup keeps the ID token focused on core identity information, while the userinfo endpoint provides access to further user data as needed, supporting privacy and up-to-date information retrieval.

sequenceDiagram
    participant UserAgent as User Agent
    participant Client as Client (RP)
    participant OP as OpenID Provider (PAS)

    Note over UserAgent, OP: **Authorization Code Flow**
    UserAgent ->>+ Client: User initiates login
    Client ->>+ OP: Authorization request and user authentication
    OP -->> Client: ID Token and Access Token returned

    Note over Client, OP: **`userinfo` Endpoint Request**
    Client ->>+ OP: Request user information from `userinfo` endpoint
    Note over Client, OP: Authorization: Bearer <Access Token>
    OP -->> Client: Respond with user claims in JSON (e.g., name, email)

Example Request to userinfo Endpoint

After obtaining an access token, the client can make a request to the userinfo endpoint to retrieve additional user claims.

HTTP Request

GET /authentication/oidc/t1/userinfo HTTP/1.1
Host: pas.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  • Method: GET
  • Endpoint: /authentication/oidc/t1/userinfo
  • Authorization Header: Contains the access token prefixed with Bearer.

Example Response from userinfo Endpoint

The OpenID Provider (PAS) responds with user claims in a JSON format. The response will include claims based on the scopes requested (e.g., profile, email).

{
    "sub": "1234567890",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "email": "john.doe@example.com",
    "email_verified": true,
    "preferred_username": "johndoe",
}

This response format allows client applications to retrieve rich user information in a single call, based on the scopes and claims configured in PAS.

Consent management in PhenixID Authentication Services (PAS) allows organizations to ensure that users are aware of, and agree to, the specific information (claims) that applications access. By configuring consent display options, PAS can present a customized consent screen to users, outlining which data will be shared and allowing them to make an informed decision.

To require user consent for an OpenID Connect (OIDC) flow, administrators can configure PAS to display a consent screen before issuing tokens. This is particularly important for applications requesting sensitive user information. By enabling consent at the OpenID Provider (OP) or Relying Party (RP) level, PAS will prompt users to review and approve the requested scopes (and their associated claims) before authentication completes.

PAS provides a variety of configuration options to customize the consent display, allowing administrators to control how claims are presented on the consent screen. These options are configured per claim and include:

  1. Consent Masking: Mask parts of sensitive data in the consent display to protect user privacy. For example:

    • "consent_mask": "mail" masks part of an email address (e.g., j**d@example.com).
    • "consent_mask": "last4" or "consent_mask": "first4" mask the first or lats 4 characters of certain data fields.

  2. Consent Labels: Define user-friendly labels for each claim to make them easily understandable. For instance, rather than showing "email_verified", the consent display could use the label "Email Verification Status". Set using:

"consentLabel": "Email Verification Status"
  1. Localization Keys: Use localization keys for claims to support multi-language environments. For example:
"consentLocalizationKey": "givenName"

This allows PAS to automatically select the appropriate language label for each claim based on user preferences or system settings.

Here’s an example of how these options might look in PAS configuration:

"scope_claims": [
  {
    "name": "profile",
    "claims": [
      {
        "name": "given_name",
        "include_in_id_token": "true",
        "type": "string",
        "consentLocalizationKey": "firstName",
        "consentLabel": "First Name"
      },
      {
        "name": "family_name",
        "include_in_id_token": "true",
        "type": "string",
        "consentLocalizationKey": "lastName",
        "consentLabel": "Last Name"
      }
    ]
  },
  {
    "name": "email",
    "claims": [
      {
        "name": "email",
        "include_in_id_token": "true",
        "type": "string",
        "consent_mask": "mail",
        "consentLabel": "Email Address"
      }
    ]
  }
]

In this example:

  • The profile scope includes given_name and family_name, each with localization keys and friendly labels for multi-language support.
  • The email scope includes email with masking applied, showing only part of the email in the consent display for added privacy.

To fully enable and configure consent in PhenixID Authentication Services (PAS), administrators can set consent requirements at both the Relying Party (RP) level and the OpenID Provider (OP) level. This setup ensures that the consent prompt aligns with the organization’s privacy and data-sharing policies.

Configuring consent at the RP level allows specific applications to require user consent before accessing user data. This setup is useful when different applications have varying data access requirements, and only certain applications need explicit user consent.

  1. Access the Relying Party Configuration: In the PAS configuration interface, navigate to the settings for the specific RP.
  2. Enable Consent Prompt: Enable the requireConsent setting in the RP configuration to ensure that a consent screen is displayed to users each time they authenticate with this application.

    • Example configuration:

      "requireConsent": true

This configuration ensures that users are presented with a consent screen before sharing any personal information with the specified RP, allowing them to review and approve the requested scopes.

When consent is enabled at the OP level, it applies globally across all RPs using this OP. This configuration is suitable when user consent is required universally, regardless of the specific application.

  1. Access the OP Configuration: In PAS, locate the OpenID Provider configuration settings.
  2. Set Global Consent Requirement: Enable the requireConsent parameter for the OP. This setting enforces the consent prompt for all RPs using this OP.

    • Example configuration:

      "requireConsent": true

Using the prompt=consent Parameter in Authentication Requests

To explicitly trigger a consent prompt from the client side, the prompt=consent parameter can be included in the authentication request to PAS. This ensures that the user will always see the consent screen, even if they have previously approved the scopes for this RP.

  • Example Authentication Request with Consent Prompt:

    <authorization_endpoint_url>?
response_type=code
&client_id=your_client_id
&scope=openid profile email
&redirect_uri=https://clientapp.com/callback
&prompt=consent

Using prompt=consent is helpful in cases where the application wants to reaffirm the user's approval, such as when requesting additional scopes or after a policy change. When this parameter is included, PAS will always display the consent screen, regardless of previous approvals.

Session and Logout Management in PhenixID Authentication Services (PAS)

PhenixID Authentication Services (PAS) offers robust session and logout management features that support Single Sign-On (SSO), RP-initiated logout, and backchannel logout. These options provide flexibility for organizations to manage user sessions and ensure seamless logout experiences across applications.

Single Sign-On (SSO) Support

SSO in PAS allows users to authenticate once and access multiple applications without re-authenticating. PAS uses a centralized session to track the user's authenticated state, meaning that once a user logs into one application, they gain access to other applications within the same SSO domain without additional logins. This enhances user convenience and ensures consistent access across various services.

RP-Initiated Logout

Relying Party (RP)-initiated logout enables a client application to log a user out of the entire SSO session. This action is initiated by the client, meaning that when a user logs out of one application, it prompts PAS to end the user’s session across all connected applications.

  1. Logout Process: The RP sends a logout request to the end_session_endpoint, informing PAS to terminate the session.
  2. Redirection: After the logout is processed, PAS can redirect the user to a specified post-logout URL or a default logout page.

Example RP-Initiated Logout Request:

<end_session_endpoint_url>?
id_token_hint=<id_token>
&post_logout_redirect_uri=https://clientapp.com/logout-callback

This process ensures that once the user logs out from one application, they are effectively logged out from all applications that were part of the SSO session, improving security by preventing unauthorized access.

Backchannel Logout

Backchannel logout in PAS provides a secure way to notify RPs that a user session should be terminated without requiring user interaction. Unlike front-channel logout, which may rely on browser redirects, backchannel logout sends a direct, server-to-server request to each RP that has an active session with the user.

  1. Logout Notification: When the user logs out or a session ends, PAS sends a logout request to each registered RP’s backchannel logout endpoint.
  2. Session Termination: Each RP processes the request and ends the user’s session on their server, ensuring consistent logout across applications.

Backchannel logout is particularly useful in environments where reliable logout is needed, even if the user’s browser is closed or network issues prevent a front-channel logout request from reaching each RP.

To configure backchannel logout for a Relying Party (RP) in PhenixID Authentication Services (PAS), you need to specify a backchannel_logout_uri in PAS’s settings. This setup ensures that PAS can notify the RP to terminate the user’s session whenever a logout event occurs.

Configuring Backchannel Logout on the RP

  • Register the backchannel_logout_uri in PAS:

    • In PAS’s configuration for the RP, specify the backchannel_logout_uri as the URL that PAS will call when a user logs out.
    • This configuration is done in the Relying Party settings within PAS’s configuration manager, allowing you to define the specific backchannel logout URL for each RP.

    Example Configuration in PAS:

    {
   "client_id": "your_client_id",
   "backchannel_logout_uri": "https://clientapp.com/backchannel-logout",
   "other_rp_settings": "..."
}

When backchannel logout is configured in this way, PAS will send a logout request to the specified backchannel_logout_uri whenever the user logs out. This approach provides a secure, server-to-server logout mechanism, ensuring the user is logged out from all RPs involved in the session, maintaining session consistency across applications.

Session Management with check_session_iframe

PhenixID Authentication Services (PAS) supports OpenID Connect (OIDC) check_session_iframe as part of its session management capabilities. This feature is particularly useful for Single Sign-On (SSO) and Single Logout (SLO) scenarios, enabling applications to maintain session synchronization with the authorization server.

The check_session_iframe is an endpoint provided by PAS for client applications to monitor the active session's status. Through this iframe-based mechanism, applications embedded in a browser can detect if a user’s session is still active with PAS or if it has expired, facilitating consistent user experiences across multiple applications in an SSO environment.

How check_session_iframe Works in PAS

  1. Embedding the Iframe: The client (Relying Party, RP) integrates an iframe pointing to the PAS check_session_iframe URL. This iframe allows the client to track session status through secure communication between the client application and PAS.

  2. Session Polling and Status Verification:

    • The client application periodically polls the iframe using JavaScript's postMessage API, sending a request to verify the session state.
    • PAS responds to these requests with the current session status, allowing the client to detect any changes.

  3. Session Expiration Handling:

    • If the PAS session has expired (for example, if the user logged out from another application), the iframe will indicate this to the client.
    • The client can then respond by ending the local session, logging the user out, or prompting them to re-authenticate.

Use Cases for check_session_iframe in PAS

  • Single Sign-On (SSO) and Single Logout (SLO): PAS leverages check_session_iframe to provide a seamless and consistent logout experience across applications. When a user logs out from one application, all applications relying on the same PAS session can detect this change and respond accordingly.

  • Automatic Session Synchronization: check_session_iframe enables client applications to automatically detect session inactivity or expiration, providing a more secure and responsive user experience.

Example Implementation

To implement check_session_iframe with PAS:

  1. Retrieve the session_state parameter in the initial authentication response, which PAS provides to uniquely identify the session. This corresponts to the sid delivered in the id token.
  2. Embed an iframe in your application that points to the PAS check_session_iframe URL (provided in the PAS OIDC discovery document).
  3. Use postMessage to send the session state to the iframe and listen for a response, handling session expiration as appropriate.

Example Polling Mechanism

Below is a simple illustration of how an application might poll the session state:

// Set up iframe for check_session_iframe
const checkSessionIframe = document.createElement('iframe');
checkSessionIframe.src = "https://phenixid.se/authentication/oidc/t1/check_session";
checkSessionIframe.style.display = "none";
document.body.appendChild(checkSessionIframe);

// Periodically check session state
setInterval(() => {
    checkSessionIframe.contentWindow.postMessage(session_state, "https://phenixid.se");
}, 60000);

// Listen for PAS response to determine session status
window.addEventListener("message", (event) => {
    if (event.origin === "https://phenixid.se") {
        if (event.data === "changed") {
            // Session has expired or changed
            alert("Your session has expired. Please log in again.");
            window.location.href = "/login";
        }
    }
});

Security and Privacy Considerations

  • Session State Security: Ensure that the session_state is transmitted securely, as it is sensitive information.
  • Polling Frequency: Adjust polling intervals based on security requirements and user experience; frequent polling increases responsiveness but may impact application performance.

By integrating check_session_iframe, PhenixID Authentication Services (PAS) ensures that applications can maintain session synchronization with PAS, providing secure, reliable session management and enhancing the user experience in multi-application environments.

OAuth 2.0 Enhancements

To enhance secure token management and authorization control in PhenixID Authentication Services (PAS), OAuth 2.0 features such as JWT access tokens, token introspection, and token revocation have been integrated, along with flexible claim configuration options.

Configuring Claims in Access Tokens

PhenixID PAS allows administrators to customize which claims are embedded within access tokens, ensuring that tokens contain only the information necessary for resource access control while protecting user privacy by limiting data exposure.

  • Adding Claims to Access Tokens: Claims represent user information (e.g., email, roles) and are structured based on requested scopes. PAS allows administrators to assign specific claims to each scope, such as profile, openid, or email, tailoring token contents to application needs.

Example Configuration: In the PAS configuration, specify claims within scopes to define which claims should be included in access tokens:

{
  "scope_claims": [
    {
      "name": "openid",
      "claims": [
        {
          "name": "email",
          "include_in_id_token": "true",
          "include_in_access_token": "true",
          "type": "string"
        }
      ]
    },
    {
      "name": "profile",
      "claims": [
        {
          "name": "name",
          "include_in_id_token": "true",
          "include_in_access_token": "true",
          "type": "string"
        }
      ]
    },
    {
      "name": "roles",
      "claims": [
        {
          "name": "roles",
          "include_in_access_token": "true",
          "type": "array"
        }
      ]
    }
  ]
}

In this example:

  • Claims like email are included under the openid scope, supporting the essential OpenID Connect identity needs.
  • The name claim is configured under the profile scope to include basic profile information.
  • The roles claim is added only to the access token, supporting applications that need role-based access control.

Using Token Introspection

Token introspection enables PAS to verify token validity in real time, providing information about the token’s active state, expiration, and associated claims. This capability is essential for applications using opaque tokens, as these tokens contain no embedded information.

  • Introspection Endpoint: PAS offers a standard OAuth 2.0 Token Introspection endpoint that resource servers can call to validate tokens dynamically. The endpoint URL is typically structured as follows:

    POST https://<pas_instance>/authentication/oidc/<tenant>/introspection

  • Example Request:

    POST https://pas.example.com/authentication/oidc/t1/introspection
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

token=<access_token_to_inspect>

    Request Parameters:

    • token: The access or refresh token to validate.

  • Example Response: If the token is active, PAS returns also returns scope.

    {
  "active": true,
  "scope": "openid profile roles",
}

    If the token is inactive (e.g., expired or revoked), the response will indicate "active": false.

Using Token Revocation

Token revocation allows PAS to invalidate access and refresh tokens on demand, which is essential for managing secure session terminations, especially in cases of compromised tokens or explicit user logout requests.

  • Revocation Endpoint: PAS provides a token revocation endpoint for deactivating tokens immediately.

    POST https://<pas_instance>/authentication/oidc/<tenant>/revocation

  • Example Revocation Request:

    POST https://pas.example.com/authentication/oidc/t1/revocation
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

token=<access_token_to_revoke>

    Request Parameters:

    • token: The access token or refresh token to revoke.

    After revocation, the token will no longer be valid for accessing resources, and PAS introspection responses for the revoked token will return "active": false.

These OAuth 2.0 enhancements in PAS offer robust mechanisms for real-time access control and secure token lifecycle management. By configuring claims and using introspection and revocation endpoints effectively, administrators can ensure secure and dynamic access management across applications and services.

Here’s the full, combined text on Security Features in PhenixID Authentication Services (PAS), including PKCE, client authentication methods, configuration steps, and examples:

Security Features

PhenixID Authentication Services (PAS) incorporates robust security features to ensure safe and controlled access to resources within OpenID Connect (OIDC) and OAuth 2.0 frameworks. Key security mechanisms include PKCE (Proof Key for Code Exchange) and various client authentication methods, each designed to enhance the integrity and resilience of token-based authentication flows.

PKCE (Proof Key for Code Exchange)

PKCE, originally designed for securing OAuth 2.0 flows on public clients such as single-page applications (SPAs) and mobile apps, adds an extra layer of protection against interception attacks. In PAS, PKCE is supported in the Authorization Code Flow, helping to protect authorization codes from interception or reuse by requiring a dynamically generated code challenge and code verifier.

  • How PKCE Works:

    • During the authorization request, the client generates a code_verifier (a random string) and derives a code_challenge (a hashed version of the verifier).
    • The code_challenge is sent to PAS’s authorization endpoint, while the code_verifier remains with the client.
    • When the client exchanges the authorization code for tokens, it includes the code_verifier. PAS checks that the code_challenge from the initial request matches the verifier provided, ensuring that only the original client can complete the exchange.

  • Configuration in PAS: PKCE can be configured with three enforcement options, allowing administrators to specify when PKCE should be required:

    • Always: PKCE is mandatory for all Authorization Code Flow requests. This setting is recommended for applications with higher security requirements, ensuring all authorization code requests use PKCE to protect against code interception attacks.
    • Optional: PKCE is used if provided by the client but is not required. This setting provides flexibility, allowing PKCE for clients that support it, while still allowing clients without PKCE capabilities to authenticate.
    • Never: PKCE is disabled for Authorization Code Flow requests. This setting may be used in environments where PKCE is unnecessary, such as when all clients are highly secure and confidential, or if authorization is managed in a controlled, internal environment.

    These PKCE options allow PAS administrators to enforce PKCE requirements based on their organization's security policies and the nature of the clients accessing the authorization server.

Example PKCE Authorization Request:

  1. Step 1: Generate a code_verifier and code_challenge:

    code_verifier = "random_string_for_verification"
code_challenge = base64urlEncode(SHA256(code_verifier))

  2. Step 2: Initiate the authorization request:

    GET https://pas.example.com/authentication/oidc/t1/authorize
?response_type=code
&client_id=your_client_id
&redirect_uri=https://clientapp.com/callback
&scope=openid profile
&code_challenge=your_code_challenge
&code_challenge_method=S256

  3. Step 3: After receiving the authorization code, use the code_verifier in the token exchange request:

    POST https://pas.example.com/authentication/oidc/t1/token
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&grant_type=authorization_code
&code=authorization_code_from_redirect
&redirect_uri=https://clientapp.com/callback
&code_verifier=your_code_verifier

    Response: PAS will return an access token if the code_verifier matches the code_challenge.

Client Authentication Methods

PAS supports multiple client authentication methods, allowing administrators to select an approach based on client capabilities and security needs. These methods are crucial for verifying the identity of the client application when it requests tokens, helping prevent unauthorized access.

  • Supported Methods:

    • Client Secret Post: The client includes its secret in the request body. Suitable for confidential clients where secure storage of the client secret is feasible.
    • Client Secret Basic: The client secret is included in the HTTP authorization header using Basic Authentication. This method is straightforward and commonly supported.
    • Client Secret JWT: The client creates a signed JWT using its secret, which PAS verifies. This approach adds security through cryptographic signing.
    • Private Key JWT: The client uses a private key to sign a JWT, enabling strong authentication without a shared secret. Ideal for high-security use cases where the client can securely manage private keys.

Example Client Authentication Requests:

  1. Client Secret Basic:

    POST https://pas.example.com/authentication/oidc/t1/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=authorization_code
&code=authorization_code
&redirect_uri=https://clientapp.com/callback

  2. Client Secret Post:

    POST https://pas.example.com/authentication/oidc/t1/token
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&client_secret=your_client_secret
&grant_type=authorization_code
&code=authorization_code
&redirect_uri=https://clientapp.com/callback

  3. Client Secret JWT:

    • First, create a JWT signed with the client’s secret, using HMAC-SHA256 (HS256):

      {
  "iss": "your_client_id",
  "sub": "your_client_id",
  "aud": "https://pas.example.com/authentication/oidc/t1/token",
  "exp": 1730991552,
  "jti": "unique_id_for_request"
}

    • Then, include this JWT in the token request:

      POST https://pas.example.com/authentication/oidc/t1/token
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=signed_jwt_assertion
&grant_type=authorization_code
&code=authorization_code_from_redirect
&redirect_uri=https://clientapp.com/callback

  4. Private Key JWT:

    • First, create a JWT using the client’s private key, signed with RS256:

      {
  "iss": "your_client_id",
  "sub": "your_client_id",
  "aud": "https://pas.example.com/authentication/oidc/t1/token",
  "exp": 1730991552,
  "jti": "unique_id_for_request"
}

    • Then, include this JWT in the token request:

      POST https://pas.example.com/authentication/oidc/t1/token
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=signed_jwt_assertion
&grant_type=authorization_code
&code=authorization_code
&redirect_uri=https://clientapp.com/callback

Configuring Private Key JWT and Client Secret JWT in PAS

PhenixID Authentication Services (PAS) supports Private Key JWT for secure client authentication. The following are the configuration steps to enable this method in PAS.

Configuring Private Key JWT

Private Key JWT requires clients to sign a JWT with a private key. PAS will validate this JWT signature using the corresponding public key registered for the client.

  • Steps to Configure:

    1. Generate a Public/Private Key Pair: Use an RSA or EC (Elliptic Curve) key pair to sign the JWT.
    2. Register the Public Key in PAS:
      • In the PAS client configuration, add the public key for the client.
      • You can configure this in PAS configuration manager by navigating to the RP settings and entering the public key in PEM format on a publicKey field.

  • Example Configuration in PAS:

    {
   "client_id": "your_client_id",
   "publicKey": "MIIBIjANBgkqh..."
}

Additional Considerations

  • Audience (aud) Claim: When creating the JWT for either method, ensure the aud (audience) claim matches the PAS token endpoint URL. This is critical for successful authentication.
  • JWT Lifetime (exp): The exp (expiration) claim should be set to a short duration to reduce the risk of token replay attacks.
  • jti Claim: Use a unique jti (JWT ID) to help prevent replay attacks by ensuring each JWT is unique.

These security features in PAS—PKCE, Private Key JWT, and Client Secret JWT—provide a robust framework to protect OAuth 2.0 and OIDC flows, preventing unauthorized access and supporting secure, user-friendly experiences across applications.

OIDC (OpenID Connect) OAuth2 SPA Single Sign-On