Global Redirector Configuration Guide

Last updated
Save as PDF

Configure a service provider for OpenID Connect (OIDC) integration, which allows NiCE KM sites to authenticate users through external identity providers.

We recommend the Global Redirector Configuration Guide only if you have multiple NiCE KM sites and want to set up a single app in your identify provider via OIDC.

Prerequisites

Admin access to your NiCE KM site
Admin access to your identity provider (IdP)
Working knowledge of Supported OpenID Connect flows

Step 1: Collect information from your identity provider

To configure a basic OpenID Connect integration, you will need the following information from your IdP (same as OIDC guide):

Required information:

Client ID: The unique identifier for the site as a relying party.
Client Secret: The secret passcode to establish trust between the IdP and the site (this secret should not be shared over any public channel).
IdP Authorize Endpoint URL: The endpoint that will receive the site's authorization code request.
IdP Issuer: The unique identifier for the identity provider.
IdP Token Endpoint URL: The endpoint that will receive the site's identity token request.

Recommended information:

IdP JSON Web Key Set (JWKS) Endpoint URL: The endpoint that will provide the site with public keys to verify a signed identity token.
IdP Logout Endpoint URL: The endpoint that will receive the site's sign out request.
IdP UserInfo Endpoint URL: The endpoint that will provide the site with verbose user identity data, if not present in the identity token.
Scopes: The site will use identity token claims to enrich an authenticating user's profile on the site.

Optional information:

Additional (Custom) claims: Any custom identity token claims to save with the user's profile on the site.
IdP Token Endpoint URL Authentication Method: The authentication method the relying party will use to connect to the token endpoint URL.

Step 2: Configure service provider in NiCE KM

Navigate to your site's administrative interface and create a new service provider configuration:

service-name requirement: The service-name value must contain only letters and numbers (A–Z, a–z, 0–9). Hyphens, underscores, and spaces are not allowed. Example: mycompany, not my-company. Each service-name must be unique across all authentication services on your site.

Example

<service>
  <sid>sid://mindtouch/2019/03/sso/oidc</sid>
  <type>auth</type>
  <description>Foo Idp</description>
  <init>native</init>
  <name>foo</name>
  <config>
    <value key="rp-client-id">your-client-id</value>
    <value key="rp-client-secret">your-client-secret</value>
    <value key="rp-custom-redirect-uri">https://auth.mindtouch.us/callback</value>
    <value key="service-name">foo</value>
    <value key="idp-issuer">https://mycompany.foo.com</value>
    <value key="idp-authorize-url">https://mycompany.foo.com/oauth2/default/v1/authorize</value>
    <value key="idp-token-url">https://mycompany.foo.com/oauth2/default/v1/token</value>
    <value key="idp-token-url-auth">client_secret_post</value>
    <value key="idp-keys-url">https://mycompany.foo.com/oauth2/default/v1/keys</value>
    <value key="scopes">openid profile email</value>
  </config>
</service>

The global redirector configuration is permanent. Once rp-custom-redirect-uri is saved on a service, it cannot be removed via an update. If you need to remove the global redirector from a service, you must disable the existing service and create a new one without rp-custom-redirect-uri. Attempting to update the service without this key will return a 400 error: "Cannot delete global redirector configuration. Please disable this service and create a new one if you wish to remove global redirector."

Step 3: Configure redirect URIs in your IdP

In your IdP's administration console, add the following redirect URI:

https://auth.mindtouch.us/callback

Step 4: Enable group synchronization (optional)

If you want to synchronize user groups from your IdP to NiCE KM:

Create groups in NiCE KM before enabling group synchronization
Familiarize yourself with the behavior of group synchronization
Provide the group claim name as it will appear in identity tokens or verbose user identity token received by the relying party.

Step 5: Test your configuration

Test authentication by accessing a protected page on your NiCE KM site
Verify you are redirected to your IdP for authentication
Confirm successful login and user creation in NiCE KM
Check that user attributes and group memberships are correctly synchronized

Troubleshooting

Error	Cause	Resolution
Invalid redirect URI	The redirect URI registered in your IdP does not match the global redirector URI.	Ensure your IdP has exactly `https://auth.mindtouch.us/callback` registered as an allowed redirect URI.
Cannot delete global redirector configuration	You attempted to update the service without the `rp-custom-redirect-uri` key, which is not allowed once set.	Disable the existing service and create a new one if you need to remove the global redirector.
service-name already exists	Another authentication service on this site already uses the same `service-name` value.	Choose a unique `service-name` that is not used by any other service on the site.
service-name contains invalid characters	The `service-name` contains hyphens, underscores, spaces, or other non-alphanumeric characters.	Use only letters and numbers (A–Z, a–z, 0–9). Example: `mycompany`.
User receives 403 after authentication	The user's identity token claims do not match the `claims-authorization-allowed-pattern` configured on the service.	Verify the claim key and value in your IdP match the pattern exactly. The format is `claimKey:claimValue` (e.g., `tenantId:abc123`). Multiple values can be separated with `\|`.