Skip to main content

Configure an OpenID Connect (OIDC) identity provider (IdP)

This guide provides detailed step-by-step instructions to configure an OpenID Connect (OIDC) identity provider using two methods:

Prerequisites

Some prerequisites to be aware of are as follows:

  • Administrator access to Single Sign On (SSO) configuration.
  • OpenID Connect Identity Provider (for example, Okta, Google, or another Keycloak instance).
  • Admin credentials for the IdP (for testing).

Method 1: Automatic configuration

The discovery endpoint simplifies configuration by autofetching metadata. This approach:

  • Reduces manual errors
  • Enables automatic key rotation using JWKS
  • Adapts to future IdP updates more easily
  • Complies with the OIDC Discovery standard

Automatically configure an OpenID Connect identity provider

To automatically configure an OpenID Connect identity provider, follow these steps:

  1. In the SSO Configuration screen, select + Provider and select OpenID Connect v1.0.
  2. In the Configuring OpenID Connect Provider screen:
    • Unique name: A unique name for your OpenID Connect provider (only letters, numbers, dashes, and underscores are allowed).
    • Display name: The name that will be displayed to users during login (for example, ACME Systems).
    • Display order: Controls the login display order if more than one IdP is in use.
  3. Enter the discovery endpoint URL in the Import configuration from URL field:
    • For example: https://accounts.google.com
  4. Select the fetch icon (two arrows) to the right of the field—the IdP will be populated automatically.
  5. Complete the additional required fields:
    • Client ID: The unique identifier used when authenticating with the IdP.
    • Client secret: A confidential key paired with the Client ID.
  6. Select Save.

What happens under the hood

When you enter a URL (for example, https://idp.example.com) and click the fetch icon, the system automatically appends /.well-known/openid-configuration to that URL and performs an HTTP GET request. This endpoint is defined by the OpenID Connect Discovery Specification.

A metadata document is retrieved that includes all necessary configuration data:

  • authorization_endpoint
  • token_endpoint
  • userinfo_endpoint
  • jwks_uri
  • end_session_endpoint (if supported)
  • issuer
  • Supported algorithms, scopes, response types, grant types, etc.

The matching fields in the identity provider configuration are set using this data.

Method 2: Manual configuration

Use this method if the discovery endpoint isn’t available or if you want finer control over the settings.

Manually configure an OpenID Connect identity provider

To manually configure an OpenID Connect identity provider, follow these steps:

  1. In the SSO Configuration screen, select + Provider and select OpenID Connect v1.0.
  2. In the Configuring OpenID Connect Provider screen:
    • Unique name: The IdP name (only letters, numbers, dashes, and underscores are allowed).
    • Display name: Friendly name for this IdP (for example, ACME Systems).
    • Display order: Controls the login display order if using more than one IdP.
  3. Leave the Import configuration from URL field blank and select Show configuration details.
  4. Manually fill in the fields:
    • Issuer: The IdP’s unique identifier string. This is the value of the iss claim expected in tokens. It validates that tokens come from the expected issuer (for example, https://idp.example.com).
    • Authorization URL: The URL where users are redirected to authenticate with the OpenID Connect provider (for example, https://idp.example.com/oauth2/auth).
    • Token URL: The endpoint URL used to exchange authorization codes for access tokens (for example, https://idp.example.com/oauth2/token). Tokens are retrieved after the user logs in.
    • Validate signature: A security feature to verify that the ID token was signed by the expected IdP. This prevents tampering or token forgery.
    • Use JWKS: Automatically retrieves the public keys needed to validate token signatures. This simplifies key management and rotation.
    • JWKS URL: This field only appears when you enable Validate signature and then enable Use JWKS. Enter the URL where the OpenID Connect provider’s JSON Web Key Set (JWKS) can be retrieved (for example, https://idp.example.com/.well-known/jwks.json). This set contains the public keys used to verify the signatures of tokens issued by the provider.
    • Validating public key: The public key used to validate the token’s digital signature. This ensures the token was signed by a trusted identity provider.
    • Validating public key id: A unique key ID (kid) that identifies the correct public key from a set. This helps to select the correct key when multiple public keys exist.
    • Logout URL (optional): The URL to trigger logout at the IdP (for example, https://idp.example.com/oauth2/v1/logout). This supports single logout (RP-initiated logout).
    • User Info URL: The endpoint URL to retrieve user profile information from the OpenID Connect provider (for example, https://idp.example.com/oauth2/userinfo). Retrieves user attributes that aren’t present in the ID token.
    • Scopes: A space-separated list of scopes to request during authentication. The email scope is required.
    • Use PKCE: An OAuth 2.0 security enhancement for public clients. This prevents interception of authorization codes in browser-based apps.
    • PKCE method: The options are as follows:
      • Plain: Sends the original code verifier (less secure and not recommended).
      • S256: Sends an SHA-256 hash of the code verifier (more secure and recommended).
  5. Complete the additional fields:

    • Client ID: The unique identifier assigned to your application by the OpenID Connect provider. This public identifier is used to identify your application during the authentication flow and is typically provided when you register your application with the identity provider.

    • Client authentication method: Select the method your OpenID Connect provider uses to authenticate the client. The options are:

      • Client secret basic: Sends the client ID and client secret in the Authorization header using HTTP Basic authentication.
      • Client secret post: Sends the client ID and client secret in the body of the POST request.
      • Client secret JWT: Uses a JWT (JSON Web Token) signed with the client secret for authentication.
      • Private key JWT: Uses a JWT signed with a private key for authentication. The default is Client secret post.

    • Client secret: The confidential secret key assigned to your application by the OpenID Connect provider. This private credential authenticates your application when making secure requests to the identity provider’s token endpoint.

    • Client assertion signature algorithm: The algorithm used to sign JWTs for client authentication in JWT-based methods. The options are as follows:

      • RS256: RSA SHA-256 (most common)
      • RS384, RS512: RSA with longer hashes
      • ES256, ES384, ES512: Elliptic Curve variants
      • PS256, PS384, PS512: RSA-PSS (recommended for new systems)
      • EdDSA: Edwards-curve Digital Signature Algorithm (modern, fast, and secure; uses Ed25519 curve)
      • HS256, HS384, HS512: HMAC with SHA-2 (shared secret-based; suitable for symmetric key scenarios)

    • Attribute Mappings: Map the Email User attribute to the email Claim.

  6. Save your changes.
  7. Configure additional fields as needed.
  8. Select Save.
  9. Click the three dots to the right of the provider to view its configuration details.
  10. Copy the Redirect URL as shown. In your external identity provider, add this URL to the allowed callback URLs. The Redirect URL already includes your tenant FQDN. For example: https://platform.example.com:31000/realms/infra360/broker/34c64198-68ca-4588-84f7-38d024819821-Auth0-provider/endpoint

After you complete the OpenID Connect configuration, existing users can sign in to the platform using their OpenID Connect credentials. You can also invite new users to access the platform through OpenID Connect SSO authentication.

Troubleshooting

Error: Invalid redirect URI

Ensure the redirect URI in the IdP matches the one configured in the system.

Token validation failure

Check the clock skew, client secret, and issuer value.

Discovery URL fails to import

Validate that the URL is accessible and returns a proper OIDC metadata JSON (example below).

 {
     "issuer": "https://idp.example.com",
     "authorization_endpoint": "https://idp.example.com/oauth2/authorize",
     "token_endpoint": "https://idp.example.com/oauth2/token",
     "userinfo_endpoint": "https://idp.example.com/oauth2/userinfo",
     "jwks_uri": "https://idp.example.com/.well-known/jwks.json",
     "response_types_supported": ["code", "id_token", "token id_token"],
     "subject_types_supported": ["public"],
     "id_token_signing_alg_values_supported": ["RS256"]
 }

Thank you for your feedback!

×