Skip to content

SSO Configuration

ICP supports Single Sign-On via OpenID Connect (OIDC), allowing users to authenticate through your organization's identity provider. SSO coexists with local username/password authentication. Users can use either method.

Prerequisites

Before configuring SSO in ICP, complete the following in your identity provider:

  1. Register a new OIDC application (also called a "client" or "app registration").
  2. Note the Client ID and Client Secret issued for the application.
  3. Add the following Redirect URI to the allowed list:
    • Local/on-prem (distribution pack): http://localhost:9446/auth/callback
    • Production: https://<your-icp-domain>/auth/callback
  4. Ensure the identity provider includes the following claims in the ID token:
    • sub (required)
    • email or preferred_username (at least one required)
    • name (recommended, used for display names)

Step 1: Collect OIDC Endpoints

Gather the following endpoint URLs from your identity provider. Most providers publish these under the OpenID Provider Metadata document at /.well-known/openid-configuration.

Endpoint Description
Issuer URL Unique identifier for the authorization server
Authorization endpoint Where ICP sends users to authenticate
Token endpoint Where ICP exchanges the authorization code for tokens
End-session endpoint Where ICP sends users to log out

Step 2: Update deployment.toml

Locate conf/deployment.toml under your WSO2 Integrator installation:

OS Default path
macOS /Applications/WSO2 Integrator.app/Contents/components/icp/conf/deployment.toml
Windows %USERPROFILE%\AppData\Local\Programs\WSO2\Integrator\components\icp\conf\deployment.toml
Linux /usr/share/wso2-integrator/components/icp/conf/deployment.toml

Add the following SSO configuration to the file, replacing the placeholder values with your identity provider's details:

ssoEnabled = true
ssoIssuer = "https://your-provider.com"
ssoAuthorizationEndpoint = "https://your-provider.com/oauth2/authorize"
ssoTokenEndpoint = "https://your-provider.com/oauth2/token"
ssoLogoutEndpoint = "https://your-provider.com/oauth2/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "email"
ssoScopes = ["openid", "email", "profile"]

For production deployments, replace the redirect URI with your public domain (e.g. https://icp.example.com/auth/callback).

Restart the ICP server after saving changes.

Configuration parameters

Parameter Description
ssoEnabled Set to true to activate SSO
ssoIssuer Issuer URL from your identity provider
ssoAuthorizationEndpoint Authorization endpoint URL
ssoTokenEndpoint Token endpoint URL
ssoLogoutEndpoint End-session endpoint URL
ssoClientId Client ID from your identity provider
ssoClientSecret Client secret from your identity provider
ssoRedirectUri Redirect URI registered with your identity provider
ssoUsernameClaim Claim to use as the ICP username: email or preferred_username
ssoScopes OIDC scopes to request. openid is required.

Provider-specific examples

Asgardeo

ssoEnabled = true
ssoIssuer = "https://api.asgardeo.io/t/<org>/oauth2/token"
ssoAuthorizationEndpoint = "https://api.asgardeo.io/t/<org>/oauth2/authorize"
ssoTokenEndpoint = "https://api.asgardeo.io/t/<org>/oauth2/token"
ssoLogoutEndpoint = "https://api.asgardeo.io/t/<org>/oidc/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "email"
ssoScopes = ["openid", "email", "profile"]

Okta

ssoEnabled = true
ssoIssuer = "https://<domain>.okta.com/oauth2/default"
ssoAuthorizationEndpoint = "https://<domain>.okta.com/oauth2/default/v1/authorize"
ssoTokenEndpoint = "https://<domain>.okta.com/oauth2/default/v1/token"
ssoLogoutEndpoint = "https://<domain>.okta.com/oauth2/default/v1/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "email"
ssoScopes = ["openid", "email", "profile"]

Auth0

ssoEnabled = true
ssoIssuer = "https://<domain>.auth0.com/"
ssoAuthorizationEndpoint = "https://<domain>.auth0.com/authorize"
ssoTokenEndpoint = "https://<domain>.auth0.com/oauth/token"
ssoLogoutEndpoint = "https://<domain>.auth0.com/v2/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "email"
ssoScopes = ["openid", "email", "profile"]

Microsoft Entra ID (Azure AD)

ssoEnabled = true
ssoIssuer = "https://login.microsoftonline.com/<tenant-id>/v2.0"
ssoAuthorizationEndpoint = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize"
ssoTokenEndpoint = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
ssoLogoutEndpoint = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "email"
ssoScopes = ["openid", "email", "profile"]

Keycloak

ssoEnabled = true
ssoIssuer = "https://<keycloak-domain>/realms/<realm>"
ssoAuthorizationEndpoint = "https://<keycloak-domain>/realms/<realm>/protocol/openid-connect/auth"
ssoTokenEndpoint = "https://<keycloak-domain>/realms/<realm>/protocol/openid-connect/token"
ssoLogoutEndpoint = "https://<keycloak-domain>/realms/<realm>/protocol/openid-connect/logout"
ssoClientId = "your-client-id"
ssoClientSecret = "your-client-secret"
ssoRedirectUri = "http://localhost:9446/auth/callback"
ssoUsernameClaim = "preferred_username"
ssoScopes = ["openid", "email", "profile"]

User provisioning

When a user authenticates via SSO for the first time, ICP automatically creates a local account. The account username is taken from the claim specified in ssoUsernameClaim. The display name is resolved in the following order:

  1. name claim
  2. Local part of the email claim (before @)
  3. preferred_username claim

After the account is created, an administrator must assign the appropriate roles and permissions before the user can access ICP resources. See Access Control.

Security notes

  • Protect the client secret — do not commit it to version control. Use environment variables or a secrets manager and inject the value at deployment time.
  • Use HTTPS in production — ssoRedirectUri must use https:// for production deployments. http://localhost is an accepted exception in OIDC for local testing, but plain HTTP should never be used with a public hostname.
  • Redirect URI must match exactly — the URI in conf/deployment.toml must match the one registered with your identity provider character for character, including protocol, hostname, port (if non-standard), and path.

Troubleshooting

Symptom Cause Fix
SSO button does not appear on the login page ssoEnabled is not true, or the server was not restarted Set ssoEnabled = true in conf/deployment.toml and restart ICP. Check startup logs for configuration errors.
invalid_client or invalid_grant error Incorrect client ID or secret, or the IdP application is inactive Verify both values and confirm the application is enabled in your identity provider.
Redirect URI mismatch error ssoRedirectUri does not exactly match the URI registered in the identity provider Check for differences in protocol, hostname, port, and trailing slashes.
User is missing required claims The identity provider is not including sub and email or preferred_username in the ID token Configure your identity provider to include these claims. Verify ssoUsernameClaim matches a claim your provider returns.
User authenticated successfully but has no access User account was created but has no assigned roles An administrator must grant roles to the account in ICP. See Access Control.

Frequently asked questions

Can a user authenticate with both SSO and a local password?
SSO and local password authentication are independent. If the same email address is used for both, they are treated as separate accounts. Users should use one method consistently.

What happens if the identity provider is unavailable?
SSO login will fail during an outage. Local password authentication (if enabled) remains unaffected.

Can I configure more than one identity provider?
ICP currently supports one OIDC provider per deployment.

How do I rotate the client secret?
Generate a new secret in your identity provider, update ssoClientSecret in conf/deployment.toml, and restart the ICP server. Active user sessions are not affected.