SSO Basics
- 05 Dec 2023
- 6 Minutes to read
- Print
- DarkLight
SSO Basics
- Updated on 05 Dec 2023
- 6 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Single Sign-On (SSO) is an authentication scheme that allows access to multiple systems using a username and password. This provides users with a simplified method to mitigate the need to create additional password/username combinations and use any additional authenticators.
SSO in Clustered Environment
In a clustered environment, users must configure Single Sign-On (SSO) on only one node. All the other nodes in the cluster automatically inherit the configuration.
Terms
| Term | Description |
|---|---|
| IdP (Identity Provider) | This is the SSO service. |
| SAML (Secure Assertion Markup Language) | Sends the user's identity from one place (IdP) to the requesting service provider (Decisions) through an exchange of digitally signed XML documents |
| OAuth 2.0 | A protocol used to provide client applications with "secure delegated access." Works over HTTPS and authorizes devices, APIs, servers, and applications with access tokens rather than credentials |
| OpenID/OpenIDConnect | Simple identity layer built on top of OAuth 2.0 |
| User Context | A critical part of the Decisions code base that identifies a user enforces permissions and enables auditing in every interaction. |
| Metadata | An XML document that contains information about the IdP and its connections/endpoints (Used in SAML) |
| Assertion Consumer URL | Directs the IdP where to send its SAML Response after authenticating a user. This can be overridden using the Override Assertion Consumer URL in Auth Requests setting. |
| Endpoint | URL with a handler for SSO events and requests (/Login) |
| Client and Client Secret | Public and private keys are used to identify an OAuth request (used in OpenID) |
Authentication Modules
Follow each link below to find information on installing and setting up each authentication module.
Accounts With SSO
Accounts tied to an IdP (SSO Account) behave very differently in Decisions than in a traditional or password-based account. Decisions does not retain the login information for these users but rather "outsources" this duty to an external provider. In addition, a standard and SSO Account may not share the same email address.
When SSO is configured, Decisions listens for a response from the provider, which could be a Token for OpenID or an XML Response for SAML. Once the response is received, a user session is created to log the user in. If this account does not exist, one is created.
Standard Account Login with SSO Enabled
To bypass the SSO login screen, navigate to: '[BASE_URL]/Account/Login?AutoSSOSignin=false' to bypass the SSO login screen.
To bypass the SSO login screen, navigate to: '[BASE_URL]/Account/Login?AutoSSOSignin=false' to bypass the SSO login screen.
Service Provider (SP) and IdP Logins
Decisions fully support SP and IdP-initiated logins.
For SP logins, the user will navigate to the DecisionsURL and be redirected to the IdP sign-in; once signed in, the user will be redirected back to Decisions.
For IdP logins, the user will navigate to the Identity Provider's Portal and initiate a login request to Decisions. In addition, IDP logins may require additional configurations depending on the user's provide and are not recommended for use in Multi-Tenant environments.
Converting Account Types
To convert a standard account into an SSO Account (and vice-versa), modify the following account fields via a Flow or SQL (requires service restart):
| Account Field | Modification |
| authentication_type | Change to either OpenID or SAML |
| user_identifier | Update with the accounts' email addresses (mandatory for Okta) |
| identity_provider_id | Update with the GUID of the configured identity provider in the module settings, sourced from the DB or an existing SSO account on the server that this IdP created during login |
User/Role Management
Considerations for user/role management vary according to the type of SSO selected:
| SSO Type | Consideration |
|---|---|
| OpenID | OpenID allows for the use of a Login Flow. Use the desired logic for the Flow to make a call to an external server (such as an AD Server) to get the users' roles. The return data can be used to update the accounts during login should the roles/permissions/groups change, then save the accounts' changes. |
| SAML | SAML relies on the same method mentioned in OpenID; however, it uses the SAML Login Flow. The SAML Login Flow will default have the XML Response and all Response Attributes available in the Data Explorer. The XPath can be used to find specific values or map values as desired into accounts. |
| Okta | Includes multiple Flows that handle account syncing and roles in Okta |
Okta Recommendation
Add the Sync All Okta Users/Roles/Groups Flow to a Scheduled Job and run it.; this will act as an AD Sync for the Okta domain.
If specific accounts require updating, several Flows can run individually.
The Decisions Support Team can provide utility Flows and SQL Queries for "batch conversion or processing" accounts at an initial run or for a temporary fix; however, it is strongly recommended to carefully consider how user management will be handled continually if Roles will be changing for multiple users.
If specific accounts require updating, several Flows can run individually.
The Decisions Support Team can provide utility Flows and SQL Queries for "batch conversion or processing" accounts at an initial run or for a temporary fix; however, it is strongly recommended to carefully consider how user management will be handled continually if Roles will be changing for multiple users.
Best Practices
- "Recovery Admin" account
It's highly recommended to keep a "recovery Admin" account (standard Account with Admin access) on the system; the default Admin account is sufficient.
This is vital when needing to regain system access for configuration changes, especially if an issue occurs on the providers' end and SSO needs to be toggled off to restore Portal access. - Test in an Incognito Window
When configuring SSO, perform all the testing in an Incognito Window while maintaining an active Admin session in a normal window. Keep the normal window (Admin session) open until the system setup is complete and Portal functionality is confirmed stable. - Deep-Linking
When configuring SSO with deep links, users must set the <DefaultSameSiteCookieMode> to None in Settings.xml. Restart the service after altering the Settings.xml.
Troubleshooting
| Issue | Solution |
| After configuring the SSO Module, the user still sees the default Login screen | Make sure that EnableSingleSignOn is set to true in Settings.xml and that the service has restarted |
| The user does not have permission to access this app (or a similar error) | Typically on the IdP side. The email/user trying to sign in has not been assigned to whatever app/tenant inside their IdP. Adding the user in question should remedy this. |
| The user attribute ‘http://schemas.xml…/[value]’ was not found | This is a mismatch in what the IdP and Decisions expect to use as the email address of a created account. In the SAML module, under the Authentication Method drop-down, change this to PersistentID, then paste the URL from the error into the box that appears below. Try to sign in again. If this doesn't work, read the SAML response to see what attributes are being sent that can be used to create the account info. |
| The user [USERNAME] is not configured to use SAML/OpenID/Okta | This Account already exists on the App Server as a Password Account. The Account can be converted using the queries above, or delete the Account in Settings (using an admin account) and re-run the SSO Login process. |
| The user gets an 'infinite redirect' after SSO login (typically SAML) | See what is set inside the user's IdP for the Response and/or Redirect URL. The response should be sent to [baseURL]/SAML/AssertionConsumer.ashx] Check that the Redirect/LogoutURL is not misconfigured. |
XML Attribute ‘AuthContextClassRef’ in XML namespace ‘urn:oasis:names:tc:SAML:2.0:assertion in the SAML message must be a URI | In the SAML module, check the box to specify Authentication Methods/Types. Uncheck all boxes except the top one that ended in 'unspecified.' |
| No LogoutURL defined | The user's IdP is expecting a Logout URL when technically not needed. Ideally, the LogoutURL would be removed from the user's IdP; if that is not an option, the LogoutHandler is located at '[baseportalURL]/Logout' (case-sensitive) |
| Error: RECEIVED SAML LOGIN RESPONSE IS NOT VALID | This is caused by a mismatch between the request and the response sent. Most common, this is the system time. Try resyncing the time on the server itself. If that doesn't work, get the SAML logs and inspect a matching set of Requests and Responses to see what is not matching. Alternatively, try checking the box for 'ignore date conditions' in the SAML module; however, this does reduce security. |
| Website redirection for SSO users | Make sure that the settings.xml file has DefaultSameSiteCookieMode set to Lax instead of None. See Securing a Decisions Install for more information. |
For further information on Modules, visit the Decisions Forum.
Was this article helpful?
