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: Register a new OIDC application (also called a "client" or "app registration"). Note the Client ID and Client Secret issued for the application. 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 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: name claim Local part of the email claim (before @) 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.