SAS Viya 3.4 Simplified SAML or OpenID Connect Integration
The SAS Viya 3.4 (May 2019 Upgrade), includes updates to SAS Logon Manager. In this article, I want to focus on another update that impacts the end-user experience when using a third-party SAML or OpenID Connect provider. This update makes it easier for end-users to access SAS Viya 3.4 and can simplify Single Sign-on. In this article, we’ll look at what the end-user now experiences and how this is configured.
Prior to SAS Viya 3.4 (May 2019 Upgrade) when a third-party SAML or OpenID Connect provider is configured, by default the end-user just sees a link on the standard login form, which looks like this:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
Where you can customize the text displayed on the link, in this case we’ve used "Log-in with OpenID". So, all the end-users would need to be "educated" that they needed to click the link to be able to log into the SAS Viya environment.
Alternatively, if all the users were going to use the same provider then some custom content could be added to the login page. This custom content would just use JavaScript to essentially click the link for the user. This custom content needs to be served from the same domain as the SAS Logon Manager, due to the security constraints on iFrame content. To tell SAS Logon Manager to use the custom content, you would create a configuration definition for sas.logon.custom in SAS Environment Manager and provide the relative URL to the page in the login field.
Or a more elegant solution exists using the login_hint parameter. This login_hint parameter is part of the OpenID Connect specification and is supported by the SAS Logon Manager. This query string parameter is passed in the authorize request, which is /SASLogon/oauth/authorize. SAS Logon Manager expects to receive an email domain in the hint, and this value is compared against a list of email domains configured for each SAML or OpenID Connect identity provider. If there is a match, the user is redirected automatically to that provider, bypassing the login page.
External identity providers are configured for one or more email domains via the emailDomain property. This exists under the sas.logon.oauth.providers.external_oauth configuration definition for OpenID Connect and is added with SAS Viya 3.4 (May 2019 Upgrade) for SAML. But with earlier releases it can be added manually by putting the property under sas.logon.saml.providers.external_saml using the sas-bootstrap-config CLI.
The next problem is how to get the login_hint query string parameter included in the authorize requests. This can be done by adding a RewriteRule to the Apache HTTP Server configuration. The placement of this rule is important. For deployments that are using HTTPS, this should be placed inside the VirtualHost of the SSL configuration. For deployments that are using HTTP, this should be placed in a new .conf file. Apache HTTP Server processes the .conf files in alphabetical order and this one needs to occur before the proxy configuration in proxy.conf so it should be named accordingly, for example login_hint.conf. Putting the redirect rule in both places is fine too.
Making Things Easier with SAS Viya 3.4 (May 2019 Upgrade)
With SAS Viya 3.4 (May 2019 Upgrade) the requirement to add a RewriteRule to the Apache HTTP Server configuration goes away. SAS Viya 3.4 (May 2019 Upgrade) introduces IdP-discovery. IdP-discovery is where SAS Logon Manager uses the domain of the user’s email address to automatically pick the identity provider to use. With this configured the user now sees the following prompt:
The user enters their email address, even if the email address is not what they use as their username in SAS Viya. SAS Logon Manager compares the domain of the email address to the email domains configured for each identity provider. If there is a match, the user is automatically redirected to that identity provider, just as if they had clicked the link on the standard login form. If there is no match, the standard login form is displayed. However, the username field will have already been populated with the value entered and all the user must enter is their password.
What Must be Configured
To enable IdP-discovery with SAS Viya 3.4 (May 2019 Upgrade) requires two configurations. First obviously the email domain must be configured for the third-party identity provider. This is available in SAS Environment Manager for both sas.logon.oauth.providers.external_oauth and sas.logon.saml.providers.external_saml.
Next a new configuration option idpDiscovery.enabled must be set to true. This can be found under the new configuration definition sas.logon.zone within SAS Environment Manager. The idpDiscovery.enabled option is shown here:
SAS Logon Manager should be restarted after adding the new configuration definition.
Impact on Single Sign-On
The new IdP-discovery feature also has an impact on single sign-on. If the user is already logged into the third-party Identity Provider, then all they need to do to access SAS Viya is type their email address. This provides a much easier process for the end-users and means that the administrator no-longer needs to maintain custom code; everything is completed using the default options within SAS Viya 3.4 (May 2019 Upgrade).
IdP-Initiated SAML Authentication
The other improvement included in SAS Viya 3.4 (May 2019 Upgrade) specifically impacts SAML. With SAML the authentication flow can either start with the Service Provider (SAS Viya) or with the Identity Provider. Service Provider flow starts with the user accessing SAS Viya and then being redirected to the Identity Provider for authentication, this is the type of flow we’ve already been discussing.
The Identity Provider Initiated flow starts from the Identity Provider, typically a portal application, and users click a link to SAS Viya. SAS Viya has always supported IdP-Initiated flow, however to provide a good user experience this again required some custom code. The IdP-Initiated flow will send the user to the SAS Logon Manager application, so custom content is needed to redirect the user into an application. Otherwise all the user gets to see is the SAS Logon Manager page saying they are signed in and inviting them to logout.
This changes with SAS Viya 3.4 (May 2019 Upgrade). SAML has a solution for the IdP-Initiated flow called the RelayState parameter. The RelayState was designed to be a state that the SP could pass to the IdP with the authentication request and get back in the subsequent response. In the IdP-initiated flow, the SAML RelayState has taken on a de facto use whereby the IdP can specify a URL to redirect the user to after authentication. Most SAML identity providers (e.g. Okta) already support the RelayState.
SAS Viya 3.4 (May 2019 Upgrade) now supports the RelayState parameter. This does not require any additional configuration within SAS Viya. Within the Identity Provider the RelayState is set to the URL of a given SAS Viya web application, for example SAS Drive (/SASDrive). This URL must be the relative URL for the SAS Viya web application. Then when a user goes through the IdP-Initiated flow they now end up at SAS Drive, rather than the SAS Logon Manager "You have signed in" page.
Conclusion
As you can see the additional features in SAS Viya 3.4 (May 2019 Upgrade) greatly streamline the use of either third-party OpenID Connect or SAML. The user experience is simplified, and the administrative work is less with SAS Viya 3.4 (May 2019 Upgrade). Please note that these features do not apply for the integration with SAS 9.4; while this appears similar a different approach is used when integrating with SAS 9.4.
