Table of Contents

OpenID Provider

In PAS 5.1, a completely new implementation of OpenID Connect Core is introduced, which significantly decreases the amount of configuration needed for functional OpenID Providers (OPs). By using the new system of protocol agnostic authenticators (also introduced in PAS 5.1), as well as setting up an OpenID Provider through simple steps in the configuration manager, you will immediately have access to a functional OIDC integration that includes the following features for the OpenID Provider:

  • All OIDC flows (code / implicit / hybrid)
  • Refresh tokens
  • Consent
  • All client authentication methods (client_secret_basic, client_secret_jwt, client_secret_body, private_key_jwt)
  • Session management
  • Explicit token lifetimes
  • Single-sign on
  • RP initiated logout
  • Backchannel logout
  • Proof key for code exchange (PKCE)

Additionally, the OP has been enhanced with the following OAuth 2.0 specifications required in many integrations:

This means that the new OIDC OP implementation now supports conformance profiles implicit and hybrid in addition to basic.

The configuration

You go through the basic configuration steps in the "OpenID Provider", enter your base url and tenant id which will be used to build the URLs of the endpoints. Then you select which OIDC scopes you would like to support in addition to the "openid" scope. Common values are "profile", "email", and "phone".

The next step is to add which claims you would like to include in which scopes. Your claims are the values which will be included in the userinfo endpoint, as well as in the issued id tokens (optionally). At this step you can really customize the data that PAS will release upon authentication, and how to mask it during the consent step if you desire. More details about the claims and id tokens is provided in the claims section. You will also select which authenticator the OpenID Provider will use. This is often an AgnosticDispatcher or AgnosticAuthSelector that can further direct the authentication flow to different authenticators, but will serve as an entrypoint to which the user is directed when authenticating.

After you finish the OpenID Provider guide in the configuration manager, you have a basic functional OIDC OP. In the edit-mode, you can access additional configuration options such as Access token lifetime, Refresh token lifetime, when to issue refresh tokens, whether to use PKCE, require consent, allow SSO, which additional audiences to include, and more.

The resulting store entity that is created is an OIDC OP that contains the values configured in the guide scenario. It will contain all the necessary data for OIDC Discovery, meaning Relying Parties (RPs) can find the correct endpoints, supported features, and claim data required for a successful integration.

The claims

Claims within OpenID Connect are values that are returned in the id token upon a successful authentication. They are also obtainable via the userinfo endpoint with a valid access token. By default, the userinfo endpoint will only return the sub claim which represents the authenticated user identity. The value of the sub claim is set automatically in the authenticator, and may be different depending on which method is used. BankID will for example use swedish personal number as its sub. The claim is of course possible to override, if the resulting item in your authentication contains a sub-attribute and the configuration parameter "allowSubOverride" is "true" in your OP configuration.

To include additional claims in your userinfo, you need to configure the different supported scopes to include the claims you want. For example, the profile claim usually includes the users name. When an RP initiates an authentication request, it will declare what scopes (and as derived from that, which claims) should be included. The userinfo will include sub, and all other claims that the authentication gave access to. The value for each claim is retrieved from the resulting item in the authentication pipe. Scopes and claims are configured when creating the OP, but can also be changed in the advanced-tab of the configuration manager. This is an example configuration:

"scope_claims" : [ {
  "name" : "openid",
  "claims" : [ {
    "name" : "acr"
  } ]
}, {
  "name" : "profile",
  "claims" : [ {
    "name" : "givenName",
    "include_in_id_token" : "true",
    "type" : "string",
    "consentLocalizationKey":"givenName"
  }, {
    "name" : "aJsonObjectProperty",
    "include_in_id_token" : "false",
    "type" : "object",
    "item_property_name": "myItemPropertyName"
  } ]
}, {
  "name" : "email",
  "claims" : [ {
    "name" : "mail",
    "include_in_id_token" : "true",
    "type" : "string",
    "consent_mask": "mail",
    "consentLabel": "Email address"
  } ]
} ]

You may configure properties for each claim included in a scope. The claim configuration properties are as follows:

  • name -- The name of the claim as it will appear in the userinfo and id token. No default value.
  • include_in_id_token -- Whether or not to include the claim in the id token. Default: "true".
  • include_in_access_token -- Whether or not to include the claim in the access token if issued as JWT. Default: "false".
  • type -- The property type. Can be "string", "boolean", "number" or "object". Default: "string".
  • item_property_name -- The name of the property in the resulting item from which the claim should take its value. Default is the same value as "name".
  • consent_mask -- If the claim value should be masked in the consent page. Can be "lastX", "firstX" (where X is the number of characters to mask), or "mail". No default value.
  • consentLabel -- What the attribute should be named in the consent display page. This should be end user friendly. Redundant if consentLocalizationKey is set. Default: The same value as "name".
  • consentLocalizationKey -- Localization key for the claim's consent display name.

So all the claims included in the authorized scopes will be included in the user info, but only the ones that are configured to be included in the id token will be added there. The sub claim is always present in the id token. The id token will also always include the following, non modifiable claims:

  • iss -- the issuer. This is our OIDC OP.
  • aud -- the intended audience. This will be the OIDC RP that initiated request, as well as any "additional audience" configured at the OIDC OP.
  • exp -- expiration time.
  • iat -- issued-at timestamp.
  • nbf -- not valid before timestamp.
  • nonce -- the OIDC nonce.
  • azp -- the authorized party. This is the OIDC RP that initiated the request.
  • sid -- a unique identifier for the authenticated session
  • c_hash -- hash value of the authorization code. Only present in hybrid flows.
  • at_hash -- hash value of the access token. Only present in implicit or hybrid flows.
  • jti -- id value of the JWT. Random uuid value.

Claims in access token, if issued as JWT

If the config property accessTokenAsJWT is set as true, access tokens will be issued as JWTs according to RFC 9068. This means that the JWT type will be at+jwt, and the claims included will be:

  • iss -- the issuer. This is our OIDC OP.
  • sub -- the subject identifier.
  • aud -- the intended audience. This will be the OIDC RP that initiated request, as well as any "additional audience" configured at the OIDC OP.
  • exp -- expiration time.
  • iat -- issued-at timestamp.
  • nbf -- not valid before timestamp.
  • client_id -- The client id. This is the OIDC RP that initiated the request.
  • jti -- id value of the JWT. Random uuid value.
  • scope -- The authorized scope for the token.

Additional claims regarding either authentication information like acr, or identity information in addition to sub can be added like normal claims as long as the claim has include_in_access_token set to true in the claim config.

Scope access

By default, all Relying Parties (RPs) that are configured to be allowed to use the OpenID Provider have access to all scopes available. This can however be changed per RP by configuring allowed_scopes at the RP. If an RP tries to access a scope that is not allowed, the authentication request will be denied.

Customized client authorization

In some cases you may want to fine-grain client authorization even further, for example if you want to enforce PKCE usage only during specific circumstances, or if you want to fetch RP access rules from an external database, or something entirely different. In those cases you may configure a clientAuthorizationPipeId on the OpenID provider. If configured, a pipe will be run where all request properties are available for you to configure logic around. If the pipe is executed successfully, the client may proceed with their authorization request. If the pipe fails however, the request will be denied. In such a pipe you may want to configure one or several FlowFailValves which executes only under specific circumstances.

Additional feature specification

The endpoints available are the standard endpoints as defined in OpenID Connect. These include:

  • Authorization endpoint -- where you log in/authenticate. No prior authentication required.
  • Token endpoint -- where you fetch your tokens. Client authentication and authorization code or refresh token required (except when using OAuth client credentials flow).
  • Userinfo endpoint -- where you fetch the user information. Access token required.
  • Check session endpoint -- where you fetch the OP iFrame for OIDC Session management. No authentication required (but session mgmt is only relevant after prior authentication)
  • End session endpoint -- where you log out and end your session. Session cookie or id token required.

These endpoints are developed to the specifications of OpenID Connect, but that includes some implementation freedom left at the discretion of the OP. Many integrations which make use of OpenID Connect also mix in some OAuth 2.0 specifications in their requirements, so these two OAuth 2.0 endpoints are also available:

  • Introspection endpoint -- where you can validate an access or refresh token. Client authentication required.
  • Revocation endpoint -- where you can revoke an access or refresh token. Client authentication required.

Another OAuth specific feature is the client_credentials flow. This is only available if you add the grant type client_credentials to the OP configuration property grant_types_supported. All RPs that want to use this flow will also have to have the configuration property allow_client_credentials_grant_type set to "true" in their configuration.

Notable additional details about OpenID Providers in PAS 5.1 are:

  • The "allowSSO" configuration parameter controls if SSO will be attempted for authentication requests towards the OP (read more about SSO in protocol agnostic authenticators before using)
  • The "accessTokenAsJWT" configuration parameter controls if access tokens should be issued as JWT or just an opaque string. Default is false.
  • The end session endpoint will trigger backchannel logout for all RPs that have "backchannel_logout_uri" configured.
  • The client authentication method "private_key_jwt" requires "publicKey" configured at the OIDC RP. The other, client secret based authentication methods require "password" configured at the OIDC RP. The client authentication method "none" is allowed only if the configuration parameter "allowNoAuthMethod" is "true" at the RP.
  • Loopback redirect URIs do not require specific ports in the allowedRedirects configuration of the OIDC RP.
  • Consent will be required if "consentRequired" is set at the config of the OP, RP or if the request prompt includes "consent"
Authentication Federation OIDC (OpenID Connect)