--- title: "Configure a generic OIDC application" description: "Connect any application that supports a generic OIDC provider to UserLock Single Sign-On. " locale: "en" updated_at: "2026-10-29T12:39:51.303Z" canonical: "https://www.isdecisions.com/en/userlock/docs/guides/sso/configure-the-applications/configure-generic-oidc-application" --- # Configure a generic OIDC application Generic OIDC setup : client credentials, endpoints, and scopes. ## Introduction This guide explains how to connect an application to **UserLock Single Sign-On (SSO)** using **OpenID Connect (OIDC)**, an authentication layer built on top of OAuth 2.0. UserLock SSO acts as the OpenID Provider, and the application as the Relying Party. Use this guide when the application supports a generic or custom OIDC provider. If the application already appears in the UserLock application list, use its dedicated guide instead. If it supports SAML 2.0 rather than OIDC, see [Configure a generic SAML application](/userlock/docs/guides/sso/configure-the-applications/configure-non-supported-saas-application). When a user signs in, the application redirects them to the UserLock SSO login page. UserLock authenticates them against Active Directory and returns them to the application, signed in. Administrators can then enforce UserLock [access policies](/userlock/docs/reference/core-concepts/access-policies) (MFA, time, machine, or location restrictions) on those sessions. > **🚩️ Before starting:** > > - **UserLock SSO** must already be [installed and configured](/userlock/docs/guides/sso/install-configure-sso), and reachable publicly over HTTPS with a valid SSL certificate. > - You need administrator access to the application’s authentication settings. > - Each Active Directory account that will sign in must have its `mail` attribute set. UserLock sends that address as the `email` claim. ## Step 1. Create the OIDC profile in UserLock SSO 1. In the UserLock console, go to ⚙ **Server settings ▸ Single Sign-On**. 2. In the application list, select **CustomOidc**. 3. Add a new profile and complete the fields: | Settings | Values | | --- | --- | | Client ID | An identifier of your choice for the OIDC client, for example `myapp-oidc`. Any value accepted as a standard client identifier is valid | | ACS URL | The application’s Redirect URI, also called callback URL or redirect URL. Copy it exactly as the application displays it: a redirect that does not match is rejected | | Client secret | A secure secret is generated automatically. Keep the proposed value | 4. Save the profile. Keep the **Client ID** and **Client secret** at hand. You will enter both in the application in the next step. > **Note** > > UserLock supports several OIDC profiles, one per application. The **Client secret** cannot be regenerated from the console, but you can edit its value manually. If you change it, update the application at the same time: sign-in fails until both values match. ## Step 2. Configure the application Your UserLock SSO URL is displayed in ⚙ **Server settings ▸ Single Sign-On**. In this guide, `` is that URL without the protocol. For `https://sso.contoso.com`, the SSO address is `sso.contoso.com`. If the URL uses a custom port, include it in every endpoint: `https://sso.contoso.com:450` gives `sso.contoso.com:450`. In the application’s authentication settings, open the generic or custom OIDC provider and complete the following values: | OIDC setting | Value | | --- | --- | | Client ID | The **Client ID** from the UserLock profile | | Client secret | The **Client secret** from the UserLock profile | | Scopes | openid profile email | | Authorization endpoint | https:///connect/authorize | | Token endpoint | https:///connect/token | | UserInfo endpoint | https:///connect/userinfo | | Issuer | https:// | Applications name these fields differently. An authorization endpoint may appear as **Auth URL** or **Authorization URL**, and a userinfo endpoint as **API URL** or **User info URL**. Some applications ask only for the issuer or a discovery URL and retrieve every endpoint themselves. Save the configuration, and enable the provider if the application lists it as disabled. > **⚠️ Important** > > Keep only `openid profile email` in the scope list. Some applications add a default scope of their own that UserLock SSO does not allow, which causes the sign-in to fail. The scopes UserLock accepts are listed in `scopes_supported` in the discovery document. > **Note** > > UserLock SSO publishes an OIDC discovery document at `https:///.well-known/openid-configuration`. It lists every endpoint, the supported scopes and claims, and the signing key, and it is the authoritative source if an application expects a value this guide does not cover. ## Step 3. Test the OIDC connection 1. Open the application’s sign-in page in an incognito or private browser window. 2. Select the UserLock sign-in option. Its label is the display name configured in the application. 3. Confirm that you are redirected to the UserLock SSO login page. 4. Sign in with the domain credentials of an Active Directory test account whose `mail` attribute is set. 5. Confirm that you are redirected back to the application, signed in, and that the account shows the expected email address. ## Troubleshooting For common issues, see [Troubleshooting SSO](/userlock/docs/support/troubleshooting/sso-issues). If the problem persists, contact [IS Decisions Support](/userlock/docs/support/need-assistance). ### The application denies the login after a successful UserLock sign-in The UserLock SSO logs show a successful authentication, but the application refuses the user. Two causes are common: - The `email` claim is empty, because the Active Directory account has no `mail` attribute set. Set it, then sign in again. - The email address already belongs to another account in the application, which refuses to link the two. Use a different address, or remove or rename the conflicting account. ### The application cannot reach the UserLock endpoints Open `https:///.well-known/openid-configuration` from a browser outside your corporate network. It must be reachable over HTTPS and return the discovery document. If it is not, check the public DNS record, the HTTPS binding and SSL certificate, and any network rule blocking external access. A sign-in that reaches the UserLock login page but fails on the way back means UserLock SSO is reachable from your users’ browsers but not from the application’s servers. ### The redirect is rejected The **ACS URL** in the UserLock profile does not match the Redirect URI the application sends. Compare both values character for character, including the protocol, any port, the trailing path and the presence or absence of a trailing slash. ## Next steps You can extend the security of SSO sessions by applying UserLock access policies in addition to authentication. - [Apply MFA on SaaS connections](/userlock/docs/guides/mfa-implementation/mfa-for-sso) to require stronger authentication. - [Hour restrictions](/userlock/docs/reference/access-policies/time-restriction): define when users are allowed to connect. - [Geolocation rules](/userlock/docs/reference/access-policies/geolocation): enforce access policies based on user location. - [Session limits](/userlock/docs/reference/access-policies/session-limit): allow or deny SaaS logins entirely for specific users.