Implementing Single Sign-On (SSO) for Desktop
Overview
To increase adoption and provide a seamless experience, Deem provides single sign-on (SSO) capabilities for enterprise services, employing a wide variety of industry open standards. Through the use of SAML 2.0, an enterprise can provide seamless access for its employees without any additional user authentication, and without requiring users to remember new passwords.
For users, SSO is all about experience: fewer passwords to manage, and fewer barriers to getting their job done. Enterprise employees can automatically be provisioned and authenticated, becoming immediately productive with Deem services in a completely transparent manner. For an enterprise, SSO translates into higher adoption rates, tighter security, fewer help-desk calls, and enhanced return on existing technology investments.
By integrating Deem enterprise services with enterprise identity stores, it is also possible to include user provisioning information in the SAML single sign-on token. This allows a single process flow from the corporate Identity Provider into Deem, eliminating the need for a separate provisioning process. If the user does not already exist in the Deem system, or if there is updated information about the user, the SAML assertions may contain provisioning information, allowing for automated, simultaneous update or pre-population of the user's profile when they log in.
Note: We require SAML 2.0. The code examples in this document are based on SAML 2.0.
Introduction to SAML
Deem provides support for the Security Assertion Markup Language (SAML) to implement SSO. SAML version 2.0 is an XML-based framework for exchanging security information. SAML provides a standardized means for identity providers to issue security related statements about an identity in XML. SAML also defines an XML-based protocol for request and response of SAML assertions, so that there may be standardization of the client/server processing of these messages. SAML profiles the logistics of SAML message exchange for SSO between two SAML enabled entities, which is referred to as federation.
SAML assertions and protocol messages are encoded in XML and use XML namespaces. The structure of the SAML assertion is defined by an XML schema that is specified by the OASIS SAML standard. It contains header information, the subject, and statements about the subject in the form of attributes and conditions — such as a start and logout URL. SAML assertions and protocol messages are typically embedded in other structures for transport, such as HTTP POST requests or XML-encoded Simple Object Access Protocol (SOAP 1.1) messages.
The SAML authentication flow can start in one of two ways, Identity Provider (IdP)-initiated or Service Provider (SP)-initiated. An IdP-initiated login starts with the user first navigating to the enterprise services (IdP) and then going to Deem (SP) with a SAML assertion. A SP-initiated login starts with first navigating to Deem (SP), getting redirected to the enterprise services (IdP) with a SAML request, and then redirected back to Deem (SP) with a SAML assertion. IdP-initiated is more prone to man in the middle attacks making it less secure.
Because SP-initiated is more secure, all new implementations need to be SP-initiated and existing IdP-initiated implementations should be migrated to SP-initiated.
SAML Message Exchange
The SAML message exchange process follows these steps:
SP-initiated
The user navigates to Deem
The user navigates to Deem using either the Deem Domain URL (https://<domain>).deem.com or the Deem Domain Start SSO URL (https://<domain>.deem.com/rc/ssoStart.do). The user is redirected to the enterprise services with a SAML request.
The enterprise services authenticates the user
The user is authenticated using the existing security framework, such as a web access management system, authentication to an LDAP directory, or integration with Windows via Kerberos. After the user is authenticated, the system constructs a SAML assertion (see below), digitally signs the assertion, and returns it over a secure link to the browser, embedded as a hidden form field in a HTTP form. At this step, the SAML assertion may optionally include additional provisioning information about the user (see "Provisioning with SAML").
The SAML assertion is sent to Deem.
Using JavaScript, the HTTP form is sent to Deem over a secure link, thus passing the embedded SAML assertion. The user does not need to be prompted again for a username and password or another credential.
The user's session with Deem begins.
Deem receives the assertion, and validates its signature using the X509v3 certificate that was provided by the enterprise when the federated trust relationship was originally established and configured. Having validated the integrity of the assertion, Deem is able to trust the identity of the user as specified in the SAML Subject attribute of the token. Based on this trusted assertion, a new user session is created and the SSO is complete. Optionally, at this point, the user may be simultaneously provisioned as part of this process, if additional user provisioning data has been provided with the token. (For more information see "Provisioning with SAML").
IdP-initiated
The user logs into and accesses the corporate intranet.
The user logs into the corporate intranet and is authenticated using the existing security framework, such as a web access management system, authentication to an LDAP directory, or integration with Windows via Kerberos. The SAML-enabled intranet is aware of this authentication. Having validated the user, the user's browser session with the intranet is created, and the user can browse the intranet.
The user clicks the link to use Deem services.
The corporate intranet provides a link, and the user clicks it to access Deem services. When the user clicks the link, the system constructs a SAML assertion (see below), digitally signs the assertion, and returns it over a secure link to the browser, embedded as a hidden form field in a HTTP form. At this step, the SAML assertion may optionally include additional provisioning information about the user (see "Provisioning with SAML").
The SAML assertion is sent to Deem.
Using JavaScript, the HTTP form is sent to Deem over a secure link, thus passing the embedded SAML assertion. The user does not need to be prompted again for a username and password or another credential.
The user's session with Deem begins.
Deem receives the assertion, and validates its signature using the X509v3 certificate that was provided by the enterprise when the federated trust relationship was originally established and configured. Having validated the integrity of the assertion, Deem is able to trust the identity of the user as specified in the SAML Subject attribute of the token. Based on this trusted assertion, a new user session is created and the SSO is complete. Optionally, at this point, the user may be simultaneously provisioned as part of this process, if additional user provisioning data has been provided with the token. (For more information see "Provisioning with SAML").
The User's SSO Experience
Accounts for the enterprise's employees can be created for Deem services in the Partner Dashboard, uploaded in a feed from the enterprise Human Relations department, or provisioned automatically through SSO. Enterprises can also choose to allow open enrollment, which enables its employees to create accounts from the login page. Enterprises can choose whether or not to send activation emails to employees to access their accounts. By default, Deem generates an activation email with a link for accessing Deem services.
An enterprise can configure a Deem site to provide one of the following user experiences for logging in and SSO: direct-access link, "token not present" failover endpoint for deep-link access, or hybrid mode.
Direct-access link
An enterprise can configure a direct-access link to Deem services and place it in the corporate portal or intranet for employees to find. For either SP-initiated or IdP-initiated, this link can point to the Deem Company Start SSO URL, which will initiate the appropriate SAML authentication flow for the user. For IdP-initiated, this link should point to the enterprise or partner SAML service endpoint and pass the desired target to Deem. Note that it is possible to specify a TARGET or RelayState (SAML 1.1 or SAML 2.0) as either a parameter of the link or as part of the SAML token, which specifies a target other than the home page once SSO is established. If no RelayState is specified, the target defaults to the home page.
"Token not present" failover endpoint for deep-link access
Employees may want to use a bookmark rather than a direct-access link to access Deem services. A "Token Not Present" SSO error condition will occur if the user tries to access Deem services without presenting a valid SAML token as part of the request.
In this case, the user can be referred to initiate the appropriate SAML authentication flow or an error-handling endpoint within the enterprise SSO infrastructure. This endpoint can then validate the user within the intranet network context, and then seamlessly relay the user back to Deem with the appropriate SAML token. When authentication succeeds, the original desired URL is recovered from a cookie and the user accesses the desired page. This mechanism is useful for implementing SSO for bookmarks such as links to travel itineraries or notifications that are emailed to the user.
Hybrid model
Some enterprises may have two or more categories of users (such as employees and contractors) or may want to accommodate users that are not always able to connect to the corporate intranet.
Users without credentials on the corporate intranet, or who are unable to access them, are required to have issued to them separate Deem usernames and passwords in order to authenticate into Deem without relying on the intranet SSO infrastructure and identity store. By configuring a Deem site using the hybrid model, which combines a direct-access SSO link with regular login access, a user who accesses the home page without presenting a valid SAML token is shown a "hybrid login page" in which the user can enter an ID and password to log into Deem services. The "hybrid login page" also displays a link to the intranet SSO entry point — if the user has intranet credentials and the SAML infrastructure can access them, this link will initiate the appropriate SSO process for the user. If "Token not present" failover is configured for the domain, it is still possible to access other site URLs directly through SSO if the user has already been (or can be) authenticated on the corporate intranet.
Configuring SSO
Follow these steps to establish single sign-on (SSO) with Deem:
- Enter a support case to configure SSO. See Entering a Support Case for details.
- Coordinate with your Deem Activations Manager and Deem Integrations Manager. Configuring SSO is performed with a team of technical resources. Your Deem Activations Manager will coordinate the necessary resources to guide you through each step of the project.
Configure your SAML service for production access.
Provide information about your SSO infrastructure.
Configure the desired user experience.
- Test in the production environment. Work with your Deem Integrations and Activations Managers to establish a test of SSO as configured for your production environment. If there are any issues, collaboratively diagnose and correct.
Once you've successfully tested in production, your tasks are complete. Work with your Deem Activations Manager to establish a go-live date. You may wish to pilot the integration with a subset of users prior to full scale deployment.
Sample SAML Assertion
The following example shows a SAML assertion:
Customizing your SSO Configuration
Deem services for enterprises can be configured to support a wide variety of custom behaviors. You must provide the following data to your Deem Activations Manager to support a custom configuration.
Provide your company SSO user endpoint URL
The endpoint URL is generally the URL of your internal page where users can find a link to Deem services. It is provided in order that it may be displayed to users in a variety of places within the product, such as the hybrid login page (for the hybrid model), or as the page a user is referred to when they log out.
Determine your company SSO user endpoint URL
For SP-initiated, the endpoint URL is the PingFederate IdP Connection SSO Application Endpoint generated in your custom configuration by your Deem Activations Manager. For IdP-initiated, the endpoint URL is generally the URL of your internal page where users can find a link to Deem services. It is needed in order that it may be displayed to users in a variety of places within the product, such as the hybrid login page (for the hybrid model), or as the page a user is referred to when they log out.
Choose a unique identifier for your users
Your SAML assertions must contain a subject that uniquely identifies the user for which SSO is being performed. The externalID is a unique identifier within Deem that is intended to correlate to a key identified within the enterprise's system. This is typically an employee number, which should not change over time.
Other values that can identify the user include username, which is the internal user name that has been assigned to a particular user in Deem, and email, which is the user's email address. However, although it is possible to use any one of these three attribute values — externalID, username, or email — we recommend that you use externalID, since this value is the least likely to change over time and avoids some common problems with email addresses, which can change over time.
Whichever value type is selected, its actual value must always correspond with the value already loaded in the user's profile for the corresponding field (except in the case of new user provisioning).
Note: While the values for each of these elements in the user's profile must be unique, this requirement is limited to the particular attribute, and they need not be unique across attributes. For instance, an identical value for email address for a given user could be used for all three of these fields.
You must choose one of these three attributes to represent your users — preferably externalID — and always send this as the subject of your SAML assertions. The same attribute must be used for all users, and this value must be available in your user profiles.
Select an identifier and inform your Deem Activations Manager of the type you'll be sending.
Configure custom behaviors
Deem provides flexible behavior for user logouts, session timeouts, and various error conditions. In any of these cases users can either be redirected to a specified URL or be shown a custom message. For each of the following conditions, you should provide either a URL that users will be redirected to, or a message to be displayed to the user:
- Authentication token validation failure: This condition will occur if there is an issue with the SSO token, such as if it has expired or has been posted twice. Usually, the appropriate configuration is an error message, with a link back to the user SSO endpoint.
- Access without authentication token: This condition will occur if a user attempts to access the site without an SSO token. This handler can be used to transparently route users without tokens to a page or process whereby they can acquire a valid SAML token and be rerouted back to the original page they were accessing.
- Session timeout: This condition will occur if users have let their sessions sit idle for too long. Session timeout is configurable between 5 and 30 minutes.
- Sign out: This condition will occur if a user explicitly logs out of Deem services. If you are providing a URL, this URL must not initiate an SSO request, or the user will be automatically logged back in.
- Provisioning failures: These conditions will occur if there are issues with attributes provided for provisioning. For more information, see the section on "Dealing with Errors".
For each of these conditions, provide your Deem Activations Manager with either a URL for redirection, or a custom message to display to your users.
Provisioning with SAML
As an additional convenience, Deem supports automatically creating or updating user profiles as part of the SSO process. There are two mechanisms for doing this:
- Simple method: The simple method provides basic provisioning of a limited set of attributes using standard SAML attribute assertions. There is a separate SAML assertion corresponding to each of the various profile fields, and the fields are provisioned directly using the values provided with the various attribute element assertions. The Simple method has the advantage that it can usually be implemented with configuration options available in your SSO infrastructure.
- Advanced method: The advanced method allows any of the profile fields to be provisioned by means of an XML document which itself becomes the value of a special provisioning attribute. The Advanced method is more extensive by virtue of its ability to provision all profile fields but requires implementation of a custom plug-in for your SSO platform.
Organizations can send user profiles as part of the SSO messages, and changes to the user profile will be immediately reflected. Using this capability, users can truly be granted access to Deem services on demand.
Simple provisioning of attributes over SAML
Attributes for provisioning must be sent as part of a standard SAML attribute statement. This functionality is typically provided by your SAML infrastructure, assuming it has been integrated with an identity store containing the authoritative source of the provisioning information, such as a corporate LDAP directory.
When a message is received with a SAML attribute statement, Deem will extract the values. For each attribute you wish to pass, there must be a saml:Attribute element providing the name and value. Required and optional attributes are shown in "Required Profile Attributes".
Using these values, Deem will construct an internal provisioning request. If the user targeted in the SAML assertion does not exist, Deem will attempt to create this user, and then provide access directly. If the targeted user already exists, Deem will update the user's attributes with the data provided. The system behaves according to the following rules:
- If an externalID matches an existing externalID, the request is treated as an update.
- If there is no externalID, a match is attempted on userName, firstName, and lastName. If a match is made, the request is treated as an update.
- If no match is made, the request creates a new user profile.
Required profile attributes
The following case-sensitive attributes are required when sending a provisioning request:
- externalID: This is a unique identifier for the user that correlates to the enterprise's system. This is typically an employee number, or some other unique identifier that will not change over time.
- userName: This is another unique identifier for the user. Specifically, this will be the username that appears in the user interface for Deem services, and would be used for logging in, if SSO was not enabled.
- email: The user's email address. This must be unique within your company.
- firstName: The user's first name.
- lastName: The user's last name.
Optional profile attributes
The following case-sensitive attributes may optionally be sent along with the required attributes:
|
|
Sample SAML assertion for simple user provisioning
The following is a sample SAML assertion that contains some of the possible simple user provisioning elements specified as SAML attribute statements:
Advanced provisioning of attributes over SAML
Not all possible field settings are supported with simple provisioning. Additional profile field attributes that can't be provisioned using the simple provisioning method include all travel preferences settings, including credit cards. There is, however, a complete XML web services provisioning schema defined for Deem that allows all these fields to be specified. By including an XML document which conforms to this provisioning schema, and which contains all of the values to be provisioned as a single user attribute in the SAML document, any or all available profile fields may be provisioned as part of the SSO event.
In order to make use of the advanced provisioning capability, it is necessary to customize the federation infrastructure used to create the SAML token so that it can generate the necessary XML document. However, generating the XML document is probably not a built-in capability of the federation infrastructure. This capability requires the implementation of plug-in script that can generate the XML document. The specific mechanism for developing this capability is specific to the SAML infrastructure technology deployed within the enterprise's intranet.
The same required field information (externalID, username, email, firstName and lastName) is also required to be in the provisioning XML document in order to successfully provision a new user. (The fields are not also required to be specified as specific attributes as they are in simple provisioning.) The only user attribute that must be individually specified in addition to the userInfo provisioning document attribute itself is the SAML_SUBJECT attribute. For an example of advanced user provisioning, contact your Deem Activations Manager, who can also provide a complete XML format template for the allowed elements for the user attribute.
Encryption
Of paramount concern is the security and integrity of the attribute information transmitted as part of the SAML token. In general, this security is provided by the HTTPS (secure sockets) protocol for all of the SAML SSO infrastructure endpoints. The message is therefore secured with the strength of the SSL protocol.
SAML 2.0 also offers encryption of the SAML message itself. This is a matter of configuration of the respective SAML infrastructure components and the exchange of encryption and decryption certificates.
It is also possible to implement attribute-level encryption using a proprietary mechanism provided by the Deem SSO infrastructure. This requires the implementation of a plug-in on the Identity Provider side of the SSO infrastructure to implement an AES encryption routine, and the exchange of shared keys between the two systems. Consult your Deem Activations Manager, if this is the solution you need.
Dealing with Errors
Sometimes things go wrong. In such cases, there are a number of ways you can diagnose your issue or configure your infrastructure to deal with the error.
When errors occur during SSO, an error code is appended to the redirect URL provided for "Authentication Token Validation Failure" as the parameter ERROR=<errorcode>. For example, if you provided a redirect URL of "http://portal.customer.com/ssoError.jsp," the user would be redirected to "http://portal.customer.com/ssoError.jsp?ERROR=<errorcode>."
The following are possible error codes and their meaning:
1000: INVALID_TARGET_URL: This error occurs when either the TARGET URL specified in the SAML request is different than what has been configured.
- Verify that you are sending the proper TARGET URL as provided by your Deem Activation Manager.
- If the TARGET URL is correct, and you are currently in the deployment phase of SSO, please escalate with your Deem Activation Manager.
- If you are already in production with SSO, please contact support, and follow standard escalation procedures as required.
1001: SAML_SUBJECT_NOT_MAPPED_TO_NETWORK_ID: This error occurs when the Subject ID (username, email, or externalID) is not present in the SAML assertion. Make sure you are sending a proper SAML subject.
1002: SSO_TOKEN_GENERATION_ERROR: This error occurs if an internal issue occurred while processing your SSO request.
- If you are currently in the deployment phase of SSO, please contact your Deem Activation Manager.
- If you are already in production with SSO, please contact support, and follow standard escalation procedures as required.
1003: PROTOCOL_ERROR: This error is caused by an issue with the SAML protocol.
- Ask your SAML infrastructure team to verify the configuration.
- If you are currently in the deployment phase of SSO, please contact your Deem Activation Manager.
- If you are already in production with SSO, please contact support, and follow standard escalation procedures as required.
-99: Undefined error: In case of any other errors, the redirect URL will contain an error code of -99. This shouldn't happen.
- If you are currently in the deployment phase of SSO, please contact your Deem Activation Manager.
- If you are already in production with SSO, please contact support, and follow standard escalation procedures as required.
If you've decided to display a message to users instead of redirecting the users, your custom message appears. The actual error message appears in the HTML source as a comment and can be viewed by performing a "view source" in your browser.
For any other token validation failures and for provisioning failures, the system will perform a POST to the redirect URL with the parameter "error"=<errorMessage>, providing full details about the issue. You can choose to process the error parameter. The same error message appears in the HTML source if you perform a "view source" with your browser.
Partnership with Ping Identity
PingFederate is our federated identity server for enabling SSO to online services for employees, customers, and business partners. PingFederate is a standalone federation server that integrates and coexists with homegrown and commercial identity management deployments. As a result, enterprise-wide identity federation is achievable without requiring extensive upgrades to an entrenched identity management system.
Deem uses Ping Federate for multi-protocol SSO to Deem services. As part of this relationship, Deem and Ping have teamed up to provide low-cost access to a commercial grade federation server. Should you choose to use PingFederate, please contact your Deem account manager. We are able to provide you with direct contacts at Ping Identity, as well as preferred, pre-negotiated pricing.