SSO Configuration
Single Sign-On (SSO) allows users to log in to multiple applications using a single centralised account, without having to log in separately for each application.
How SSO Works
When a user signs in through Single Sign-On, instellix redirects the user to the configured identity provider for authentication.
After successful authentication, the identity provider returns user information to instellix. This information is used to:
- identify the user,
- create or update the user profile,
- optionally assign roles based on configured role mappings.
Each SSO provider is configured independently and can have its own protocol settings, synchronization behavior, and role mappings.
Supported protocols:
- OpenID Connect (OIDC)
- Security Assertion Markup Language (SAML)
Once configured, users can authenticate using the connected identity provider.
Before You Start
Before configuring SSO, ensure you have:
- Administrator access to your identity provider
- Administrator access to the instellix Webportal
- Required OIDC client credentials or SAML metadata
- A test user account for validation
Accessing the SSO Configuration
Navigate to:
Configuration → Global → Access Management
The SSO configuration page allows Admin Users to:
- Create new SSO providers
- Edit or Delete existing configurations
- Enable or disable providers
- Configure login behavior
- Manage role mappings
Creating an SSO Provider
Select Add SSO Provider and complete the required fields.
General Settings
| Field | Description |
|---|---|
| Enabled | Determines whether the provider is available for login. |
| Alias | Unique technical identifier used internally and in API integrations. Must not contain spaces. |
| Display Name | Human-readable name displayed to users during login. |
| Protocol | Select either OIDC or SAML. |
| Automatic User Creation | Automatically creates a new user upon the first successful SSO login. If this feature is disabled, only existing users can log in via SSO. |
OpenID Connect (OIDC)
For OIDC providers, configure the following information.
Discovery URL
The preferred configuration method is using the provider's Discovery URL.
The standard OIDC discovery endpoint depends on the provider. Below are examples of discovery URL templates for some providers.
Examples.
| Provider | Discovery URL template |
|---|---|
https://accounts.google.com/.well-known/openid-configuration | |
| Microsoft Entra ID / Azure AD | https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration |
| Keycloak | https://{host}/realms/{realm}/.well-known/openid-configuration |
| Amazon Cognito (AWS) | https://cognito-idp.{region}.amazonaws.com/USERPOOLID/.well-known/openid-configuration |
instellix automatically retrieves the required endpoints and metadata from the provider.
Manual Endpoint Configuration
If no Discovery URL is available, endpoints can be configured manually.
| Setting | Description |
|---|---|
| Authorization URL | Endpoint where users are redirected for authentication. |
| Token URL | Endpoint used to exchange authorization codes for tokens. |
| User Info URL | Optional endpoint for retrieving additional user profile information. |
| Logout URL | Optional endpoint used when logging users out of the identity provider. |
| Issuer | Expected issuer value contained in tokens. |
| Client ID | Client identifier configured at the identity provider. (Depending on the provider, this can also be found under ‘App ID’ or ‘App Client ID’) |
| Client Secret | Secret associated with the OIDC client. (Depending on the provider, this can also be found under ‘App Secret’ or ‘App Client Secret’) |
| JWKS URL | Endpoint used to validate token signatures. See more information. |
| Validate Signatures | Enables cryptographic validation of incoming tokens. See more information. |
| Trust Email | Treats email addresses received from the identity provider as verified. See more information. |
Refer to your identity provider documentation for the correct values.
SAML Configuration
For SAML providers, configure the information provided by your identity provider.
Typical SAML settings include:
| Setting | Description |
|---|---|
| Service Provider Entity ID | Entity ID of instellix. |
| Identity Provider Entity ID | Entity ID provided by the identity provider. |
| Single Sign-On Service URL | Login endpoint of the identity provider. |
| Single Logout Service URL | Optional logout endpoint. |
| NameID Policy Format | Format used to identify users. |
| Principal Type | Defines which attribute is used as unique identifier. |
| Principal Attribute | Name of the SAML attribute containing the user identifier. |
| Signature Settings | Configuration of request and response signatures. |
| Binding Settings | Defines how SAML messages are transmitted. |
| Certificate | Certificate used to validate SAML assertions. |
Refer to the documentation of your identity provider for the required values.
SAML User Attribute Mapping
SAML providers often use custom attribute names for user profile information.
To create user accounts correctly, instellix requires mappings for:
- Username
- First Name
- Last Name
Example:
| User Property | SAML Attribute |
|---|---|
| http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | |
| First Name | givenName |
| Last Name | surname |
| Username | userPrincipalName |
The configured attribute names must exactly match the values sent by the identity provider.
Client Credentials
Depending on the provider, additional credentials may be required.
| Field | Description |
|---|---|
| Client ID | Public application identifier provided by the identity provider. |
| Client Secret | Secret used to authenticate instellix against the identity provider. |
Note: Client Secrets are write-only. Existing secrets are never displayed after being saved.
Login Behavior
The login behavior can be configured per tenant under Configuration → Global → Access Management.
Three login behaviors are available:
| Login behavior | Description |
|---|---|
| Login Page with SSO Option | Users see the instellix login page and can choose between local login with username and password and SSO. |
| Direct Redirect to Identity Provider | Users are automatically redirected to the configured default identity provider. Local login with username and password remains available. |
| SSO Only (No Local Login) | Users are automatically redirected to the configured default identity provider. Local login with username and password is completely disabled. |
Login Page with SSO Option
Users first see the standard instellix login page and can choose between:
- local login with username and password, or
- Single Sign-On using a configured identity provider.
Use this option if both local and SSO login should be available.
Direct Redirect to Identity Provider
Users are automatically redirected to the configured default identity provider when accessing the login page.
Local login with username and password remains available.
A default identity provider must be configured and enabled before this login behavior can be used.
SSO Only (No Local Login)
With SSO Only, all users must authenticate through Single Sign-On. Users are automatically redirected to the configured default identity provider.
When this login behavior is enabled:
- local login with username and password is disabled,
- the instellix login page for local authentication is no longer available,
- the Forgot Password functionality is not available,
- password reset emails are not sent,
- welcome emails for local login are not sent,
- settings related exclusively to local authentication, such as password and 2FA settings, are no longer available.
Warning: If this login behavior is selected, users who are already registered will no longer be able to log in using their username and password. They must authenticate through an enabled SSO provider.
Existing users are not deleted or deactivated when switching to SSO Only.
A configured and enabled default identity provider is required to enable SSO Only. The option cannot be used without an active SSO provider.
Testing the Configuration
After saving:
- Ensure the provider is enabled
- Open a new browser session or private window
- Navigate to the Webportal login page
- Verify that authentication succeeds through the configured identity provider
Troubleshooting
Login fails after redirection
Verify:
- Client ID and Client Secret
- Redirect URI configuration at the identity provider
- Issuer value
- Endpoint URLs
User receives no role
Verify:
- The user authenticates through the correct SSO provider
- The configured claim exists in the token or SAML assertion
- The external value matches exactly
- Capitalization matches exactly
- The target role still exists
- The selected sync mode behaves as expected
Updated 9 days ago