OIDC Relying Party

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.

Configuration

Authenticator Type: OIDCRP | OIDCAuthCodeFlowRP

Common Authenticator configuration can be found here.

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

Properties

Name	Description	Default value	Mandatory
discovery_metadata_url	URL to the external OP.	N/A
internal_http_destination	ID of the internal http client used to communicate with the external OP.	N/A
custom_identifier	Custom identifier to be set inte the event logging entry	N/A
client_id	Client id used when communicating with the OP.	N/A
client_secret	Client secret used when communicating with the OP token endpoint. Optional when PKCE is used.	N/A
redirect_uri	Redirect URI used when communicating with the OP.	N/A
scope	OIDC scope used when communicating with the OP.	"openid"
use_pkce	Enables PKCE when the external OP advertises support for S256.	true
enable_user_info_lookup	If userinfo endpoint should be contacted. (The userinfo endpoint must also be part of the discovery metadata)	true
jwt_subject_parameter	JWT parameter used as subject/username.	"sub"
use_raw_claims	If the collected claims should be presented "raw" on the global state object. Otherwise the claims will be "stringified".	false
id_token_header_prefix	Prefix to use for the id_token header claims.	""
id_token_payload_prefix	Prefix to use for the id_token payload claims.	""
userinfo_prefix	Prefix to use for the userinfo claims.	""
disable_nonce	Disables sending nonce as part of the requests.	false
acr_values	include acr_values in auth request query params. Multiple values must be space-separated. No acr_values will be sent if left empty.	""
cancel_on_errors	Maps configured error codes from OP to this authenticators cancel_location. Array of strings.	[]
cancel_on_error_description_patterns	Maps configured error descriptions from OP to this authenticators cancel_location. Array of strings.	[]

Example

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)