OpenID Provider in PAS 5.1 and beyond
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)
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" }, { "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", "consent_display_name": "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".
- 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.
- consent_display_name -- What the attribute should be named in the consent display page. This should end user friendly. Default: The same value as "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.
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.
- 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. 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 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"