Custom OIDC Provider
Configure a connection to an external identity provider, via the OIDC protocol. This configuration is used in tandem with the Invoke external IDP journey step to allow OIDC federation within a journey flow.
To add a new external connection, in Admin Portal proceed to Orchestration > External Connections, then select +Add, then under the External IDP category pick Custom OIDC Provider. Complete its configuration as described below.
To verify your OIDC provider is configured correctly, test the connection after creation. When the test is run, a new page is opened with either a test success or fail message, and a JSON object containing the response data.
| Field | Description |
|---|---|
| Name * | Name of external connection as will appear in the Invoke External IDP step. |
| Issuer * | Issuer, as defined by the OIDC specification. |
| Authorization Endpoint URL * | External URL used to invoke the OIDC Authorization Endpoint. |
| Token Endpoint URL * | External URL used to invoke the OIDC Token Endpoint. |
| UserInfo Endpoint URL * | External URL used to invoke the OIDC UserInfo Endpoint. |
| Authorization Flow | OIDC authorization flow to use: - Authorization Code Flow (Authorization Code Flow) - Authorization Code Flow with PKCE (OIDC Authorization Code Flow, together with Proof Key for Code Exchange (PKCE)). |
| Pass request parameters as Request Object JWT | Select this to pass all request parameters as a Request Object JWT. If selected, you can configure whether this JWT should be only signed, or if it should also be encrypted. - Sign Request Object: Signed using the configured JWT Signing Key (default). - Sign and encrypt Reject Object: Signed using the configured JWT Signing Key and encrypted using the configured Provider Certificate. |
| Specify max age accepted for ID Tokens | Select this to only accept ID Tokens within a specific time period since it was created, where the period is specified in seconds using the Max Age * field (by default, 600s). |
| Client Authentication Method | Client Authentication method to use to authenticate to the Authorization Server when using the Token Endpoint. Options are: - Client Credentials via HTTP Basic authentication scheme: Default. Client secret configured in OAuth 2.0 Client Credentials is sent using the HTTP Basic authentication scheme (client_secret_basic) - Client Credentials in request body: Client secret configured in OAuth2.0 Client Credentials is sent in the request body (client_secret_post) - JWT signed with Client Credentials: JWT is signed with client secret configured in OAuth 2.0 Client Credentials (client_secret_jwt) - JWT signed with private key of the client: JWT is signed with configured JWT Signing Key (private_key_jwt). |
| Client Authentication JWT Expiration * | If Client Authentication Method is set to one of the JWT-based methods, this is the token expiration in seconds (by default, 600). |
| Client ID * | If Client Authentication Method is set to JWT signed with private key of the client, this is the ID that corresponds to the key. |
| Credentials Alias * | These are the credentials used to perform OAuth 2.0 authentication with the OIDC Provider. Select an existing credential, or click Add Credentials to add a new one. |
| JWT Signing Key * | If Client Authentication Method is set to JWT signed with private key of the client or if Pass request parameters as Request Object JWT is selected, this is the private key used to sign the tokens. Select an existing key, or click Add Key to add a new one. |
| Provider Certificate | OIDC Provider Certificate used to encrypt the Request Object JWT, or to validate signatures (e.g., ID token validation). - Local Certificate: Default. Use a certificate stored in the internal DB. - Remote JWKS: Use a certificate based on keys obtained from the provider’s JWKS endpoint. This option allows the IDP or any other JWKS server to manage the certificate identities, which provides resilience to key rolling. In addition, it allows using a key for encryption that’s different than the key used for signature validation. |
| JWKS URL * | If Provider Certificate is set to Remote JWKS, this is the provider’s JWKS endpoint URL used to obtain the OIDC provider certificate identities for request object encryption and signature validation. The relevant certificate identity is selected according to the use returned for each key. Note: The URL must begin with https://. |
| Cache Expiration * | If Provider Certificate is set to Remote JWKS, this is the maximum time in seconds that a JWKS response may be cached. The cache is invalidated upon expiration, or failure to validate a signature (e.g., if the token kid does not match the cached response). Note: If keys are rotated while the cache is not expired and request object encryption is required, the user will not be able to authenticate until the cache expires. This can be avoided by supporting the previous key for a period that is greater than the cache expiration. |
| Local Certificate * | If Provider Certificate is set to Local Certificate, this is the OIDC provider certificate stored in the internal DB, used for request object encryption and signature validation. Select an existing certificate, or click Add Certificate to add a new one. |