SAS Viya 2021.2.4 Bypass SAS Logon Manager

1 Like

Prior to the SAS Viya 2021.2.4 release SAS provided a sample patch transformer to update the SAS Logon Manager Ingress definition. This patch transformer used a server snippet annotation to insert a login_hint into requests. Adding the login_hint allowed customers using SAML or OpenID Connect to bypass SAS Logon Manager, meaning that end-users would automatically get redirected to the third-party SAML or OIDC Identity Provider (IdP). However, an issue with custom snippets was discovered, as documented in CVE-2021-25742. With SAS Viya 2021.2.4 the sample patch transformer has been removed and SAS is providing a configuration option to enable bypassing SAS Logon Manager. In this blog we will discuss this updated approach for bypassing SAS Logon Manager.

General Concepts

Quite often, once you have configured either SAML or OpenID Connect authentication your end-users no-longer need to interact with the SAS Logon Manager login form. The end-users will authenticate with your chosen OIDC or SAML Identity Provider (IdP). As such, making the end-users select a link on the SAS Logon Manager login form only delays gaining access to the SAS Viya applications and might confuse some end-users. The ideal solution is to have the end-user interaction with SAS Logon Manager happen automatically, handled by their browser. There are three ways you can implement bypassing SAS Logon Manager for your end-users:

Add custom Java-script content to the SAS Logon Manager login form. This requires an additional web server to host the Java-script content and requires you to relax the default security constraints defined for SAS Logon Manager. Otherwise, SAS Logon Manager will not load the Java-script from another domain into the iFrame placeholder on the login form.
Add a custom server snippet to the SAS Logon Manager Ingress definition. As stated above this is no-longer a suitable approach. Also, this only works for the Kubernetes NGINX Ingress controller, so will not work on OpenShift.
Leverage the existing code and APIs already built into SAS Logon Manager to trigger the redirect to the OIDC or SAML Idp. This does not require any custom content, any relaxing of the default security constraints, and operates with any supported Ingress Controller. With SAS Viya 2021.2.4, the new configuration option enables this path. In this blog we will look at what happens behind the scenes with this configuration option and how we might use the same approach in prior releases.

SAS Logon Manager is built to support a multi-tenant architecture. Each tenant is referred internally to as an identity zone. An identity zone is a logic boundary around the entities SAS Logon Manager manages. The entities in a zone include, but are not limited to:

Client registrations
Identity providers and access
ID and refresh tokens

The default identity zone has the ID=uaa. In a single tenant SAS Viya environment, the uaa identity zone is the only identity zone. In a multi-tenant SAS Viya environment, the uaa identity zone is the multi-tenant provider and each tenant has its own identity zone. For example, if we have the multi-tenant provider, a marketing tenant, and a sales tenant then we will have three identity zones with IDs of uaa, marketing, and sales.

Within each identity zone we have one or more identity providers, which dictate how users can sign into the zone. Each identity provider has an origin key which can be thought of as a type. There is always an identity provider with origin uaa for internal users such as sasprovider and sasboot, and an identity provider with origin ldap for LDAP logins, even if it is not used. It is the origin key field that the login_hint relates to.

In addition, within the identity zone you can configure a setting defaultIdentityProvider, which is an optional string value. This value can be set to the origin key of an identity provider within the identity zone. If set, the end-user will be directed to this identity provider automatically if no other identity provider is discovered or selected via login_hint.

The origin key of the identity provider will be the name used in the configuration of either OIDC or SAML. So, that would be the value of either sas.logon.oauth.providers.name or sas.logon.saml.providers.name. In addition, if the environment is configured for LDAP authentication there will be an identity provider with an origin key of ldap. Finally, the internal identity provider, for users like sasprovider and sasboot, also has an origin key of uaa.

Now we can look at how we can set the value of defaultIdentityProvider for our SAS Viya environment to trigger the automatic redirect to either the SAML or OIDC IdP.

From SAS Viya 2021.2.4

With the release of SAS Viya 2021.2.4 an additional configuration option has been added to the settings under sas.logon.zone called defaultIdentityProvider. The two configuration settings now available under sas.logon.zone are:

defaultIdentityProvider - Name of the identity provider to automatically redirect logins to
idpDiscovery.enabled - Redirect logins to the appropriate external identity provider by matching email domain

If we just set the value of defaultIdentityProvider to match either the value of sas.logon.oauth.providers.name or sas.logon.saml.providers.name then from their browsers the end-users will just get automatically redirected to the associated third-party Identity Provider (IdP), such as Azure Active Directory. If they already have a session established with the third-party IdP they will be seamlessly logged into the SAS Viya web applications. If they don’t have an existing session with the third-party IdP they will be prompted to log in with the third-party IdP and then provided access to the SAS Viya web applications.

Alternatively, the setting idpDiscovery.enabled changes the UI flow of using SAS Logon Manager. With idpDiscovery.enabled set to true, end-users will be prompted for their email address. SAS Logon Manager will examine the text entered and compare the string after the ‘@’ with the values configured for emailDomain in any OIDC or SAML providers. If there is a string match, then SAS Logon Manager will redirect the browser to the corresponding third-party IdP. If there isn’t a string match, then SAS Logon Manager displays the standard login form.

So you can see that most often you will not want to set both options under sas.logon.zone. You will set defaultIdentityProvider if you have one OIDC or SAML IdP and want your end-users to be automatically redirected. Alternatively, if you have multiple configured OIDC or SAML IdPs you’ll set idpDiscovery.enabled, then entering the corresponding email address will automatically redirect to the correct third-party IdP.

The settings for sas.logon.zone can be applied separately in a SAS Viya multi-tenant environment. You can set the configuration in the multi-tenant provider and have those settings apply to the multi-tenant provider and all tenants. Or you can set the configuration in an individual tenant.

For example, to set the configuration in a tenant with the name marketing using the SAS Viya CLI you first create a JSON configuration:

tee $deploy/site-config/JSON/MarketingZone.json > /dev/null << EOF
{
  "name": "addMarketingZone",
  "items": [
    {
      "version": 1,
      "metadata": {
        "services": ["SASLogon"],
        "isDefault": false,
        "tenant": "marketing",
        "mediaType": "application/vnd.sas.configuration.config.sas.logon.zone+json;version=2"
      },
      "defaultIdentityProvider": "azure",
      "idpDiscovery.enabled": false
    }
  ]
}
EOF

Which will set defaultIdentityProvider to the value azure. The configuration can then be loaded with the SAS Viya CLI:

/opt/sas/viya/home/bin/sas-viya --profile marketing auth login -u sasprovider 
/opt/sas/viya/home/bin/sas-viya --profile marketing configuration configurations create \
    --file $deploy/site-config/JSON/MarketingZone.json
/opt/sas/viya/home/bin/sas-viya --profile marketing auth logout

This configuration targets the marketing tenant since the metadata section of the configuration includes "tenant": "marketing".

Upgrading to SAS Viya 2021.2.4

If you have an existing SAS Viya 2020.1 (and higher) environment where you have used the server snippet to insert the login_hint to requests, you should consider making changes. Using the server snippet is no-longer the recommended approach to bypass SAS Logon Manager. If you have already used the server snippet; you can remove it and switch to using the new sas.logon.zone.defaultIdentityProvider configuration setting.

To stop using the server snippet you would just update your kustomization.yaml and remove reference to site-config/sas-logon-app/login-hint-transformer.yaml from the transformers block. Then use the documented commands described in the SAS Viya Deployment Guide to apply the new settings.

Prior to SAS Viya 2021.2.4

If your SAS Viya environment is a version prior to SAS Viya 2021.2.4 you can still leverage the defaultIdentityProvider setting. However, you will not be able to configure this using the SAS Viya CLI or SAS Environment Manager. How you set the value of defaultIdentityProvider will be different if you have a single tenant environment or a multi-tenant environment. For a single tenant environment and for the multi-tenant provider you will need to set a JVM option. For tenants in a multi-tenant environment, you will use the SAS Logon Manager API.

Single Tenant Configuration

First, we will consider the case of a single tenant SAS Viya environment. We will also need to use the same approach for the multi-tenant provider in a multi-tenant environment. We need to set a JVM option for SAS Logon Manager that will specify the value of defaultIdentityProvider. This can either be performed in SAS Environment Manager or by using the SAS Viya CLI to update the configuration. The JVM option is -Dlogin.defaultIdentityProvider={{name}}, where {{name}} matches the value of either sas.logon.oauth.providers.name or sas.logon.saml.providers.name.

If we take the value of either sas.logon.oauth.providers.name or sas.logon.saml.providers.name to be azure, then we can use the following JSON file to set the value of defaultIdentityProvider to azure.

tee $deploy/site-config/JSON/LogonJVM.json > /dev/null << EOF
{
  "name": "updateLogonJVM",
  "items": [
    {
      "version": 1,
      "metadata": {
        "services": ["SASLogon"],
        "isDefault": false,
        "mediaType": "application/vnd.sas.configuration.config.jvm+json;version=1"
      },
      "JAVA_OPTION_DEFAULT_IDENTITY_PROVIDER": "-Dlogin.defaultIdentityProvider=azure"
    }
  ]
}
EOF

Which will set defaultIdentityProvider to the value azure. The configuration can then be loaded with the SAS Viya CLI:

/opt/sas/viya/home/bin/sas-viya auth login -u sasprovider 
/opt/sas/viya/home/bin/sas-viya configuration configurations update \
    --file $deploy/site-config/JSON/LogonJVM.json
/opt/sas/viya/home/bin/sas-viya auth logout

Since we have set a JVM option for SAS Logon Manager, SAS Logon Manager must be restarted for this to take effect.

With this complete, any browser-based access to SAS Logon Manager will result in the end-user being redirected to the third-party Identity Provider configured for the mechanism with the origin key of azure. If the end-user has already established a session with the third-party IdP they will be seamlessly logged into the SAS Viya web application. Otherwise, they will be presented with the login prompt from the third-party IdP and after logging in they will be seamlessly logged into the SAS Viya web application.

Multi-Tenant Configuration

Now we will consider the case of a multi-tenant configuration, where we have the multi-tenant provider and two tenants, a marketing tenant, and a sales tenant. The JVM option we covered above only applies to the multi-tenant provider. The multi-tenant provider has the identity zone of uaa and the JVM option only sets defaultIdentityProvider for the identity zone of uaa. Instead, we can use the SAS Logon Manager API to set defaultIdentityProvider within the tenant. This will need to be repeated for each tenant where we want to bypass SAS Logon Manager.

Again, if we take the value of either sas.logon.oauth.providers.name or sas.logon.saml.providers.name to be azure, then we can use the following commands to set the value of defaultIdentityProvider to azure.

# 1 login
/opt/sas/viya/home/bin/sas-viya auth login -u sasboot; \

# 2 get the token
myToken=`cat ~/.sas/credentials.json |jq -r '.Default."access-token"'`; \

# provide the tenant name
myTenant="marketing"; \

# provide the name of your site ingress here
myHost={{INGRESS_NAME}}; \

# 3 fetch the identity zone’s current config
myConf=`curl https://${myHost}/SASLogon/identity-zones\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer ${myToken}"\
 -H "X-Identity-Zone-Id: ${myTenant}"|jq -r .[0]`;\

# 4 insert azure as the defaultIdentityProvider
myConf=`echo $myConf|jq -r '.config += {"defaultIdentityProvider": "azure",}'`; \
curl -X PUT https://${myHost}/SASLogon/identity-zones/${myTenant}\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer ${myToken}"\
 -H "X-Identity-Zone-Id: ${myTenant}" \
 -d "${myConf}" ; \

# 5 fetch the identity zone config to verify
curl https://${myHost}/SASLogon/identity-zones\
 -H "Content-Type: application/json"\
 -H "Authorization: Bearer ${myToken}"\
 -H "X-Identity-Zone-Id: ${myTenant}" | jq -r ; \

# 6 logout
/opt/sas/viya/home/bin/sas-viya auth logout

The commands above use the SAS Logon Manager API. We authenticate against the multi-tenant provider, but we now use the X-Identity-Zone-Id header to identify the tenant we are configuring. To run the commands, you must be authenticated to the SAS Logon Manager API as a member of SAS Administrators or the sasboot user. As such, use the SAS Viya CLI to initially obtain the Access Token for the user and set that value to the myToken variable. Using the SAS Logon Manager API to set the configuration persists the changes in SAS Logon Manager schema of the Shared Services database.

We use the myTenant variable to set the tenant’s name in the commands. In our case myTenant variable could take one of two possible values:

Value = marketing, for the marketing tenant
Value = sales, for the sales tenant

We use the SAS Logon Manager API to fetch the current configuration for the identity zone. Which we set as the myConf variable. Then we use jq to insert the configuration setting defaultIdentityProvider with the value azure into the myConf variable.

We use curl with PUT to load the updated configuration to the SAS Logon Manager API. Then fetch the identity zone configuration one last time to ensure the configuration has loaded correctly. Finally, we logout with the SAS Viya CLI to remove the Access Token.

Again, once the identity zone configuration has been updated the browser will automatically redirect the end-user to the configured third-party IdP.

How to Access SAS Logon Manager login form

Now that we have configured the defaultIdentityProvider setting when we access the SAS Viya web applications, we are automatically redirected to the third-party IdP. This accounts for 99% of usage of the SAS Viya web applications. But what happens if we need to access something like SAS Environment Manager with the sasboot or sasprovider internal users. Remember the definition of defaultIdentityProvider stated we would not be automatically redirected if the login_hint was provided. So, to be able to still access the standard SAS Logon Manager form and authenticate with either sasboot or sasprovider we just need to craft a specific URL. For example, the following is an example URL setting the login_hint to uaa:

https://{{tenant_name}}.{{INGRESS_NAME}}/SASLogon/login?login_hint=%7B%20%22origin%22%3A%20%22uaa%22%20%7D

Which is setting the login_hint to the URL encoded value of { "origin": "uaa" }. We used uaa in this example to indicate we want to use the internal identity provider and login as sasboot or sasprovider. Remember every identity zone always includes the internal identity provider with an origin key of uaa. However, you can specify uaa or ldap and it will have the same effect of bringing up the login page. After authenticating as sasboot or sasprovider you can then enter the URL for the specific SAS Viya web application you require such as SAS Environment Manager.

Conclusion

In this blog we have discussed why you might want to bypass SAS Logon Manager for your end-users. We have presented the three ways you can trigger bypassing SAS Logon Manager and discussed the best option of using the configuration setting defaultIdentityProvider. Additionally, we have shown how you can still access the SAS Logon Manager login form even when defaultIdentityProvider is configured.

Through-out this blog we have addressed SAS Viya 2021.2.4. However, the use of the defaultIdentityProvider setting can also be performed with earlier releases of SAS Viya including SAS Viya 3.5. The important thing to remember with SAS Viya 2021.2.4 (and later) is that the sample patch transformer, to insert the login_hint into requests via NGINX server snippets, will be withdrawn and the new configuration option made available in SAS Environment Manager or via the SAS Viya CLI.

Find more articles from SAS Global Enablement and Learning here.