SSO Basics
- 20 Apr 2021
- 6 Minutes to read
- Print
- DarkLight
This documentation version is deprecated, please click here for the latest version.
SSO Basics
- Updated on 20 Apr 2021
- 6 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Overview
This article is an introduction to the concept of Single Sign-On (SSO) as it relates to Decisions. Simply stated, SSO is an authentication scheme that, when configured, allows access to many systems using a single user name and password.
Terms
| IdP | Identity Provider This is the SSO service |
| SAML | Secure Assertion Markup Language |
| OAuth 2.0 | Standard protocol (version 2.0) used to provide client applications with “secure delegated access” |
| OpenID/OpenIDConnect | Simple identity layer built on top of OAuth 2.0 |
| User Context | Critical part of the Decisions code base that identifies a user, enforces permissions, and enables auditing in every interaction |
| Metadata | XML document that contains information about the IdP and its connections/endpoints (Used in SAML) |
| Endpoint | URL with a handler for SSO events and requests (/Login.aspx) |
| Client and Client Secret | Public and private keys used to identify an OAuth request (Used in OpenID) |
Setup Documents
References
Process Visual
Accounts with SSO
Accounts tied to an identity provider (SSO Accounts) behave very differently in Decisions than a traditional Native or Password Account. Decisions does not retain the login information for these users but rather “outsources” this duty to an external provider. When SSO is configured, Decisions listens for a response of some kind back from the provider; this may be a token for OpenID or an XML Response for SAML.
Once the response is received, a user session is created for that user to log the user in. If this account does not exist, one is created.
Account Management is Key!
Native and SSO Accounts may not share the same email address.
- The mobile application does not support SSO; users will have an SSO account for use on the web and a native Decisions Account for the mobile application.
Native Account Login with SSO Enabled (v6.10 and higher)
To bypass the SSO login screen, navigate to:
'[baseURL]/Login.aspx?AutoSSOSignin=false' to bypass the SSO login screen
To bypass the SSO login screen, navigate to:
'[baseURL]/Login.aspx?AutoSSOSignin=false' to bypass the SSO login screen
Decisions fully supports SP and IdP initiated logins. In a login initiated by SP, the user will navigate to the DecisionsURL and be redirected to the IdP sign in and once signed in will be redirected back to Decisions. In a login initiated by IdP, the user will navigate to the identity provider's portal and initiate a login request to Decisions.
Logins initiated using IdP may require additional configurations depending on the user's provider and are not recommended for use in Multi-Tenant environments.
Converting Account Types
To convert Native Accounts to SSO accounts (and vice-versa), modify the following account fields via flow (preferred) or SQL (requires SHM restart):
| Account Field | Modification |
| authentication_type | change to either OpenID or SAML |
| user_identifier | update with the accounts' email address (mandatory for Okta) |
| identity_provider_id | update with the GUID of the configured identity provider in the module settings, sourced from the DB or from an existing SSO account on the server that was created by this IdP during login |
User / Role Management
Considerations for user/role management vary according to the type of SSO selected:
● OpenID - OpenID allows for the use of a Login Flow. Check the box inside this module to create a Login Flow. Use the desired logic in this flow to make a call to an external server (like an AD server) and get the users' roles. The return can be used to update the accounts during login should their roles/permissions/groups change, then save the changes to the accounts.
● SAML - SAML relies on the same method as OpenID (above), however, the SAML Login flow is only available in v6.10 and higher. This Login flow will have the XML Response and all Response Attributes available in the Data Explorer by default. The XPath can be used to find specific values, or map values as desired, into accounts.
● Okta - This module ships with 4 Flows that handle account syncing and roles in Okta, natively and cleanly.
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 but for the Okta domain. If specific accounts require updating, there are several Flows that 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 (Native account with admin access) on the system; the default admin account is sufficient. This is vital when needing to regain system access for making configuration changes, especially if an issue occurs on the providers' end and SSO needs to be toggled off for restoring 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.
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 SHM has been restarted thereafter |
| The user does not have permission to access this app (or similar error) | Typically on the IdP side. The email/user that is trying to sign in has not been assigned to whatever app/tenant inside their IdP. Adding the user in question should remedy. |
| The user attribute ‘http://schemas.xml…/[value]’ not found | This is a mismatch in what the IdP and Decisions are expecting to use as the email address of a created account. In the SAML module, under the Authentication Method dropdown, 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 then re-run the SSO Login process. |
| The user gets an ‘infinite redirect’ after SSO login (typically SAML) | Check to 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’s 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 for the top one - the one ended in ‘unspecified’. |
| No LogoutURL defined | 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.aspx’ (case-sensitive) |
| Error: RECEIVED SAML LOGIN RESPONSE IS NOT VALID | This is caused by a mismatch of something between the request and 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 Request and Response to see what is not matching. Alternatively, try checking the box for ‘ignore date conditions’ in the SAML module, however, this does reduce security. |
Was this article helpful?
