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.

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`	include `acr_values` in auth request query params. Multiple values must be space-separated. No `acr_values` will be sent if left empty.	`""`	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"
    }
}

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)