OIDC Relying Party

Configuration and usage guidance for OIDC Relying Party in Fortified ID Access.

Note: There are two sections related to the OIDC Relying Party. This section describes when Fortified ID Access acts as an OIDC Relying Party (RP).
If you are looking for information about when Access acts as an OIDC OpenID Provider (OP), click the following link.

This page covers ordinary OpenID Connect discovery. To resolve the OP through an OpenID Federation trust chain and publish RP entity metadata, see OpenID Federation RP. The two modes use the same OIDC authorization code flow after provider metadata has been resolved.

Configuration

Common Authenticator configuration can be found here.

Properties
Example

Name	Description	Default value	Mandatory
`discovery_metadata_url`	URL to the external OP.	N/A	true
`internal_http_destination`	ID of the internal HTTP client used to communicate with the external OP.	N/A	true
`custom_identifier`	Custom identifier to be set in the event logging entry	N/A	false
`client_id`	Client id used when communicating with the OP.	N/A	true
`client_secret`	Client secret used when communicating with the OP token endpoint. Optional when PKCE is used.	N/A	false
`redirect_uri`	Redirect URI used when communicating with the OP.	N/A	true
`scope`	OIDC scope used when communicating with the OP.	`"openid"`	false
`use_pkce`	Enables PKCE when the external OP advertises support for `S256`.	`true`	false
`enable_user_info_lookup`	If userinfo endpoint should be contacted. (The userinfo endpoint must also be part of the discovery metadata)	`true`	false
`jwt_subject_parameter`	JWT parameter used as subject/username.	`"sub"`	false
`use_raw_claims`	If the collected claims should be presented "raw" on the global state object. Otherwise the claims will be "stringified".	`false`	false
`id_token_header_prefix`	Prefix to use for the id_token header claims.	`""`	false
`id_token_payload_prefix`	Prefix to use for the id_token payload claims.	`""`	false
`userinfo_prefix`	Prefix to use for the userinfo claims.	`""`	false
`disable_nonce`	Disables sending nonce as part of the requests.	`false`	false
`acr_values`	Space-separated ACR values requested from the OP. With `acr_requirement: preferred`, sent as the `acr_values` authorization parameter. With `required`, requested as an essential ID token claim instead.	`""`	false
`acr_requirement`	`preferred` requests ACR values without enforcing the returned value; `required` rejects an ID token whose `acr` is missing or not configured.	`"preferred"`	false
`cancel_on_errors`	Maps configured error codes from OP to this authenticator's `cancel_location`. Array of strings.	`[]`	false
`cancel_on_error_description_patterns`	Maps configured error descriptions from OP to this authenticator's `cancel_location`. Array of strings.	`[]`	false

{
    "id": "oidc_rp",
    "type": "OIDCRP",
    "config": {
        "base_path": "/oidcrp/authn",
        "custom_identifier": "fortifiedid",
        "discovery_metadata_url": "https://192.168.50.228/oidc/mycompany/.well-known/openid-configuration",
        "internal_http_destination": "oidcrp_httpclient",
        "client_id": "my_client_id",
        "client_secret": "my_client_secret",
        "redirect_uri": "http://127.0.0.1:8080/oidcrp/authn/oidc_rp",
        "use_pkce": true,
        "jwt_subject_parameter": "given_name"
    }
}

Require a returned ACR

Use acr_requirement when the RP must enforce an authentication context class reference (ACR) returned by the OP. In Management Center, set Requested ACR values and ACR requirement under Request & authentication. Use the exact ACR values agreed with the OP; separate multiple values with spaces.

For example, to accept either of two ACR values:

{
  "acr_values": "urn:example:loa2 urn:example:loa3",
  "acr_requirement": "required"
}

With required, Access requests acr as an essential ID token claim with these values. It does not also send the acr_values authorization parameter. Access rejects the authentication if the signed ID token omits acr or returns a value outside the configured list. At least one ACR value and ID token signature validation are required. The OP must support the essential acr claim request.

With preferred (the default), Access sends nonempty acr_values as an authorization request parameter and does not enforce the returned acr. This preserves the behavior of configurations that omit acr_requirement. A requested value alone does not guarantee the authentication level.

The same setting applies to federated RPs. In automatic registration mode, Access places the essential acr claim request in the signed Request Object.

PKCE and `client_secret`

client_secret does not enable or disable PKCE.

For OIDCRP, PKCE is controlled separately by the authenticator setting use_pkce, which defaults to true. When use_pkce is enabled and the external OP advertises support for S256 in discovery metadata, Access sends code_challenge in the authorization request and code_verifier in the token request.

This means:

client_secret can be omitted for public clients that use PKCE
omitting client_secret does not turn PKCE on by itself
if client_secret is omitted and PKCE is not used, the token request will not have client authentication and the flow will fail

Cancel instead of failure on OP errors

A couple of common error codes from an OP:

invalid_request
unauthorized_client
access_denied
unsupported_response_type
invalid_scope

All OP errors go to the failure_location, either explicitly set or inherited, unless configured to go to the cancel_location:

// This should only be used if you know that the specific OP you integrate
// with uses access_denied to represent a user cancellation in your flow.
"cancel_on_errors": ["access_denied"]

You can also configure a regex pattern matched against the full error_description from the OP.

"cancel_on_error_description_patterns": [
  ".*user cancelled.*",
  ".*denied by user.*"
]

The following applies to opt-in mapping to cancel:

cancel_on_errors is checked first
cancel_on_error_description_patterns is checked afterwards
if neither matches, the callback goes to failure_location

This means:

both can be used individually
both can be used together
neither of them needs to be configured

Logging

On a successful authentication, an event is logged containing the following:

WEB_100021
IDENTIFIER (user traceid)
SOURCE_SERVICE_NAME (issuer from metadata)
SOURCE_USER_NAME (jwt_subject_parameter from any of the claims)
SOURCE_ADDRESS (user IP address)
CUSTOMER_IDENTIFIER (custom_identifier if configured)

On a failed authentication, the following event is logged:

WEB_100028
IDENTIFIER (user traceid)
SOURCE_SERVICE_NAME (issuer from metadata)
SOURCE_ADDRESS (user IP address)
CUSTOMER_IDENTIFIER (custom_identifier if configured)

Data exposed to global state

After successful validation, data stored in the global state are:

id_token header claims
id_token payload claims
userinfo claims (if enable_user_info_lookup=true)