Configure a generic OIDC application
Connect any application that supports a generic OIDC provider to UserLock Single Sign-On.
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.
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 (MFA, time, machine, or location restrictions) on those sessions.
🚩️ Before starting:
UserLock SSO must already be installed and configured, 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
mailattribute set. UserLock sends that address as theemailclaim.
In the UserLock console, go to ⚙️ Server settings ▸ Single Sign-On.
In the application list, select CustomOidc.
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 validACS 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
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.
Your UserLock SSO URL is displayed in ⚙️ Server settings ▸ Single Sign-On. In this guide, <SSO_address> 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://<SSO_address>/connect/authorize |
Token endpoint | https://<SSO_address>/connect/token |
UserInfo endpoint | https://<SSO_address>/connect/userinfo |
Issuer | https://<SSO_address> |
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://<SSO_address>/.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.
Open the application’s sign-in page in an incognito or private browser window.
Select the UserLock sign-in option. Its label is the display name configured in the application.
Confirm that you are redirected to the UserLock SSO login page.
Sign in with the domain credentials of an Active Directory test account whose
mailattribute is set.Confirm that you are redirected back to the application, signed in, and that the account shows the expected email address.
For common issues, see Troubleshooting SSO. If the problem persists, contact IS Decisions Support.
The UserLock SSO logs show a successful authentication, but the application refuses the user. Two causes are common:
The
emailclaim is empty, because the Active Directory account has nomailattribute 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.
Open https://<SSO_address>/.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 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.
You can extend the security of SSO sessions by applying UserLock access policies in addition to authentication.
Apply MFA on SaaS connections to require stronger authentication.
Hour restrictions: define when users are allowed to connect.
Geolocation rules: enforce access policies based on user location.
Session limits: allow or deny SaaS logins entirely for specific users.