Configure Federated OIDC Provider

Overview and Application Config

In a Federated OIDC Provider RSA, the RSA delegates user authentication and user details to a 3rd party OAuth Provider. Its own access tokens and other OAuth materials are linked to corresponding access tokens/refresh tokens/ materials at the 3rd party OAuth Provider. See the image below for more details:

RSA Overview

The RSA must be registered as an OAuth Client of the Federated OIDC Provider. This relationship is managed in the RSA's database through the oauth_provider table.

The properties shown in the next two paragraphs refer to those defined in the Application Config of the Helm Chart.

The following configuration controls which OAuth Provider will act as the federated OIDC Provider. The RSA may have many OAuth Providers (each Authorization Server for example is an OAuth Provider), but only one manages user authentication. fpx.oidc.provider.self-hosted must be set to 'false' and fpx.oidc.provider.federated must be 'true'. This ensures that authentication (for connecting a resource owner with the data-source/RSA of their choice) is handled by the Federated Provider and not self-hosted at the RSA itself. The exact provider is controlled by the fpx.oidc.provider.federated.federated_issuer value, which must match exactly with the issuer_uri column in the corresponding database entry. The fpx.oidc.provider.federated.client_id must be the OAuth Client ID for the RSA-OIDC to authenticate to the federated provider.

fpx.oidc.provider.federated.useDownstreamToken must be set to 'true' as it enables the RSA to recognize that it must use the access tokens issued by the federated provider at the last step of the flow when the resource is requested. If the access token has expired, the RSA will check whether any refresh tokens were issued along side the access token (which has since expired). If a refresh token was found, the RSA will subsequently attempt to refresh the access tokens as outlined by https://tools.ietf.org/html/rfc6749#page-47.

fpx:
  oidc:
    provider:
      self-hosted:
        enabled: false
      federated:
        enabled: true
        client_id: example-client-id
        federated_issuer: https://example-issuer-url.com
        useDowntreamToken: true
    client:
      callback: /oidc/callback

Request Attributes

JSON-API type: oauth-provider

Parameter	Description	Example value	Required
name	A human-readable name for the OAuth Provider.	Keycloak IDP	Yes
issuerUri	The base URL of the OAuth Provider.	https://keycloak.dev.identos.ca/auth/realms/identos-qa	Yes
clientId	This value is used to identify the RSA-OIDC to the OAuth Provider.	identos-qa	Yes
clientSecret	A secret the RSA-OIDC uses with the OAuth Provider.	some-secret-value	Yes
clientAuthenticationMethod	The authentication method the RSA-OIDC uses with the OAuth Provider. If left null, defaults to `client_secret_basic`. It is recommended to use `private_key_jwt`.	client_secret_post	No
defaultScopes	Default scopes to include in requests to the OAuth Provider.	"openid profile email address"	No
defaultPrompt	Default prompt to include in requests to the OAuth Provider.	null	No
additionalRequestParams	Additional parameters to include in requests to the OAuth Provider.	{}	No
metaDataRaw	Metadata can be provided in raw text format using this field.	null	No

Sample Requests using Admin API

Configure the Federated OIDC Provider

This step must be performed in addition to those outlined above. Note that the values of clientId and issuerUri in this request should match the values for the fpx.oidc.provider.federated.client_id and fpx.oidc.provider.federated.federated_issuer configuration properties that have been defined in the RSA's application configuration, shown here.

curl -X POST '{{RSA_ADMIN_URI}}/oauth-provider' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --data-raw '{
  "data": {
    "type": "oauth-provider",
    "id": 1,
    "attributes": {
      "name": "Keycloak IDP",
      "issuerUri": "https://keycloak.dev.identos.ca/auth/realms/identos-qa",
      "clientId": "identos-qa",
      "clientSecret": "some-secret-value",
      "clientAuthenticationMethod": "client_secret_post",
      "defaultScopes": "openid profile email address",
      "defaultPrompt": null,
      "additionalRequestParams": {},
      "metaDataRaw": null
    }
  }
}'

Retrieve the Federated OIDC Provider

curl -X GET '{{RSA_ADMIN_URI}}/oauth-provider/1' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \

Update the Federated OIDC Provider

curl -X PATCH '{{RSA_ADMIN_URI}}/oauth-provider/1' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: {{RSA_ADMIN_VERSION}}' \
  --header 'Authorization: {{RSA_ADMIN_STATIC_TOKEN}}' \
  --data-raw '{
  "data": {
    "type": "oauth-provider",
    "id": 1,
    "attributes": {
      "name": "A New Name",
      "issuerUri": "https://another.uri",
      "clientId": "identos-qa",
      "clientSecret": "some-secret-value",
      "clientAuthenticationMethod": "client_secret_post",
      "defaultScopes": "openid profile email address newscope",
    }
  }
}'

Note: private_key_jwt is the preferable option for clientAuthenticationMethod as the RSA's authentication method against any OAuth Provider as long as that provider can support Private Key Authentication.

Overview and Application Config​

Request Attributes​

Sample Requests using Admin API​

Configure the Federated OIDC Provider​

Retrieve the Federated OIDC Provider​

Update the Federated OIDC Provider​