SSO Basics
  • 05 Dec 2023
  • 6 Minutes to read
  • Dark
    Light

SSO Basics

  • Dark
    Light

Article summary

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

TermDescription
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
Allows clients to verify the identity of a user based on the authentication performed by an external source, as well as to obtain basic profile information about the user
Assertion - the data sent to the requesting service (Decisions) confirming this user has been validated by the provider and is safe to log in.

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 URLDirects 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.
EndpointURL with a handler for SSO events and requests (/Login)
Client and Client SecretPublic 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.

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 FieldModification
authentication_typeChange to either OpenID or SAML
user_identifierUpdate with the accounts' email addresses (mandatory for Okta)
identity_provider_idUpdate 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 TypeConsideration
OpenIDOpenID 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.
SAMLSAML 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.
OktaIncludes 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.

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

IssueSolution
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 usersMake 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?