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. |
OpenID Connect (OIDC)
For OIDC providers, configure the following information.
Discovery URL
The preferred configuration method is using the provider's Discovery URL.
Example:
https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configurationinstellix 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. |
| Client Secret | Secret associated with the OIDC client. |
| JWKS URL | Endpoint used to validate token signatures. |
| Validate Signatures | Enables cryptographic validation of incoming tokens. |
| Trust Email | Treats email addresses received from the identity provider as verified. |
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 experience can be configured per tenant.
Direct Redirect
Users are automatically redirected to the configured identity provider when opening the login page.
Recommended when:
- All users authenticate through SSO
- Local username/password login is not required
Login Page with SSO Option
Users first see the standard login page and can choose between:
- Local login
- Single Sign-On
Recommended when:
- Both local and SSO users exist
- A fallback login method is required
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