FapiDcrFilterChain

A filter chain to validate dynamic client registration (DCR) requests and make sure they produce OAuth 2.0 clients that comply with the following FAPI specifications:

Put this filter before other filters to reject requests that would result in creating an OAuth 2.0 client that doesn’t comply with the FAPI specifications.

Usage

{
    "name": string,
    "type": "FapiAuthorizeFilterChain",
    "config": {
        "forwardedHost": string,
        "clientId": runtime expression<string>,
        "clientCertificate": runtime expression<certificate>,
        "jwkSetService": JwkSetService reference,
        "trustedDirectoryService": TrustedDirectoryService reference,
        "apiClientService": ApiClientService reference,
        "apiClientOrgService": ApiClientOrgService reference,
        "auditService": AuditService reference,
        "skewAllowance": configuration expression<duration>,
        "supportedSigningAlgorithms": [ configuration expression<string>, ... ],
        "supportedTokenEndpointAuthMethods": [ configuration expression<string>, ... ],
        "registrationObjectSigningFieldNames": [ configuration expression<string>, ... ],
        "allowPingIssuedTestCerts": configuration expression<boolean>
    }
}

Properties

"forwardedHost": string, required: The forwarded host added to the endpoint request.
"clientId": runtime expression<string>, required: The client ID. The filter evaluates this for every request.
"clientCertificate": runtime expression<certificate>, required: The client TLS certificate, often found in the request as shown in the examples that follow. The filter evaluates this for every request.
"jwkSetService": JwkSetService reference, required: The CachingJwkSetService to retrieve keys for the OAuth 2.0 client.
"trustedDirectoryService": TrustedDirectoryService reference, required: The TrustedDirectoryService referencing the TrustedDirectory that issues the OAuth2.0 software statements and their certificates for API clients and providers.
"apiClientService": ApiClientService reference, required: The ApiClientService to retrieve the API client, such as an IdmApiClientService.
"apiClientOrgService": ApiClientOrgService reference, required: The ApiClientOrgService to retrieve the API organizations, such as an IdmApiClientOrganisationService.
"auditService": AuditService reference, optional: The AuditService to record audit events. Provide either the name of an AuditService object defined in the heap or an inline AuditService configuration object.

Default: No audit service.
"skewAllowance": configuration expression<duration>, optional: The skew to allow when validating time-based claims.

Default: 5 seconds
"supportedSigningAlgorithms": array of configuration expression<strings>, optional: JSON Web Signature (JWS) algorithms supported for signing.

PingGateway uses this to validate the registration request object (JWT) alg header and to configure the signing algorithms for the OAuth 2.0 client.

Default: ES256, PS256
"supportedTokenEndpointAuthMethods": array of configuration expression<strings>, optional: The supported OAuth 2.0 token_endpoint_auth_method values.

Default: private_key_jwt, self_signed_tls_client_auth, tls_client_auth
"registrationObjectSigningFieldNames": array of configuration expression<strings>, optional: Registration request fields to validate against the "supportedSigningAlgorithms".

Default: id_token_signed_response_alg, request_object_signing_alg, token_endpoint_auth_signing_alg
"allowPingIssuedTestCerts": configuration expression<boolean>, optional: Whether to permit use of a PingGateway-issued JWKSet for client TLS certificate validation.

Default: false

Example

The following example gets the client certificate from an ssl-client-cert header:

{
    "name": "fapiDCRFilter",
    "type": "FapiDCRFilter",
    "config": {
        "forwardedHost" : "&{as.fqdn}",
        "clientId" : "${request.queryParams.client_id[0]}",
        "clientCertificate": "${pemCertificate(urlDecode(request.headers['ssl-client-cert'][0]))}",
        "jwkSetService": "jwkSetService",
        "trustedDirectoryService": "trustedDirectoryService",
        "apiClientService" : "auditService",
        "apiClientOrgService" : "idmApiClientOrgService"
    }
}

Get the client certificate

This section shows how to get the client certificate in various situations.

From HTTPS

When PingGateway terminates transport layer security (TLS), use the certificate associated with the incoming HTTPS connection:

"clientCertificate": "${contexts.client.certificates[0]}"

From a `Client-Cert` trusted header

When a proxy using the Client-Cert header fronts PingGateway and terminates TLS, it sends the client certificate with distinguished encoding rules (DER).

The following example gets the certificate from the header:

"clientCertificate": "${derCertificate(request.headers['Client-Cert'][0])}"

Learn more in RFC 9440, Client-Cert HTTP Header Field.

From an NGINX trusted header

When NINGX fronts PingGateway and terminates TLS, it can send the client certificate in a trusted header.

The following example uses x-ssl-cert as the trusted header. NGINX encodes the certificate in PEM format and URL-encodes the result:

"clientCertificate": "${pemCertificate(urlDecode(request.headers['x-ssl-cert'][0]))}"

Learn more in the NGINX Module ngx_http_ssl_module documentation.

From an Envoy or Istio trusted header

When Envoy or Istio fronts PingGateway and terminates TLS, it can send the client certificate in a field in a trusted header.

The following example uses x-forwarded-client-cert as the trusted header. Envoy puts the client certificate in the Cert field of the header value. Envoy encodes the certificate in privacy enhanced mail (PEM) format and URL-encodes the result:

"clientCertificate": "${pemCertificate(urlDecode(findGroups(request.headers['x-forwarded-client-cert'][0], 'Cert=([^;]+);?')[1]))}"

Learn more in the Envoy x-forwarded-client-cert documentation.

More information

org.forgerock.openig.fapi.dcr.FapiDcrFilterChainHeaplet

PingGateway