Azure Active Directory SCIM Custom Attributes
In the last post we talked about enabling custom attributes for Azure Active Directory OIDC Authentication. This was only half the picture; for those users to be able to authenticate to SAS Viya we need the Identities microservice to also leverage the same custom attribute for the accountID of the end-user. Otherwise, our end-user’s will not be able to log in. In this post we will examine how we can configure SCIM to send the custom attribute as the username.
Why?
First and foremost, why would you want to use something other than email address, user principal name, or objectID as the unique identifier for your end-users? If you are doing everything within Microsoft Azure; you are running SAS Viya, you are accessing data sources such as Azure SQL Server, utilising ADLS, accessing file in Azure storage accounts, etc. then there really is no need to look at changing the unique identifier for your end-users. Either of the three attributes; email, upn, or objectID, will be sufficient. However, if you need to access a mixture of cloud and on-prem resources you might want to consider using a different attribute to identify your end-users. For example, if you want to use Kerberos Hybrid authentication with Protocol Transition, you’ll need to ensure the unique identifier matches the Kerberos User Principal Name. Quite often the Kerberos User Principal Name will not match the Azure Active Directory user principal name.
Basic Setup
You need to have completed the basic setup for SCIM. This involves both the configuration of your SAS Viya environment and the basic setup with Azure Active Directory, as covered in the documentation. Equally I have also previously posted about the SAS Viya configuration and the Azure Active Directory configuration. This will result in you having an Enterprise Application registered in Azure Active Directory with the required Tenant URL and Secret Token configured. Then we can move onto looking at the attribute mappings.
User Mapping Settings
You should first make the changes to the Provision Azure Active Directory Users settings as per the documentation.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
If you select the userName attribute, the first in the list, you will find that you are able to select from several default source attributes. This list includes the extensionAttributes for the user, but only includes the onPremisesSecurityIdentifier. No other on-premises attributes are available for selection. When you select the option Show advanced options you only have the option to Edit attribute list for customappsso or the option to Use the expression builder, as shown here:
If you follow the link to Request additional attributes you would like to see supported here it opens the following page. This page has an important note with the following text:
So, as the note describes the only way to edit the attributes presented by Azure Active Directory is to start from the link: https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true. Following this link will log you into the Azure Portal again and you will need to navigate to your Enterprise Application again and then edit the attribute mappings. Then once you get back to the user attribute mappings page and now select Show advanced options you will see the following:
Notice that now you have the option to Edit attribute list for Azure Active Directory. This means that you can edit the attribute list used by the first column in the attribute mapping table, that is the source attributes for the mapping. Selecting the link Edit attribute list for Azure Active Directory will take you to a table containing the available Azure Active Directory attributes. You can then add to the bottom of this list:
- Name = onPremisesUserPrincipalName, Type = String
- Name = onPremisesSamAccountName, Type = String
Which will look like the following:
Then select Save at the top of the screen and select Yes when prompted "Are you sure you want to make these changes". This will return you to the attribute mapping page and you can now use either attribute for the customappsso userName attribute, the first in the list. Select Save again at the top of the screen to save your changes and select Yes when prompted.
This completes the changes required to use either the on-premises User Principal Name or SAM Account Name as the userName attribute with SCIM. This means that SAS Viya will leverage this attribute as the unique identifier for your end-users and this will match the attribute used in the ODIC configuration.
Validate
You can now either provision all your users and groups to SAS Viya; or a better option is to provision a single user to validate your settings. From the main Provisioning page of your Enterprise Application there is an option to Provision on demand. The option to Provision on demand will allow you to provision a single selected user and so validate your settings. On the Provision on demand screen, you can select the user you want to test with, as shown here:
The results from provisioning on demand allow you to review the status and resolve any issues before provision all your users. For example, setting the userName to onPremisesUserPrincipalName and validating with Provision on demand for my test user shows the following:
If I also check in SAS Environment Manager, I can see my test user correctly provisioned into SAS Viya:
As you can see in SAS Viya, my test user is now identified with its on-premises User Principal Name rather than any other Azure Active Directory attribute.
Hopefully, this shows how helpful the option to Provision on demand is for validating the correct configuration before you attempt to provision hundreds of users.
Removing SCIM Users/Groups from SAS Viya
If we are testing our changes against a SAS Viya environment, you will probably need to remove the existing users and groups that Azure Active Directory has already provisioned into the environment. I previously wrote about an easy method to remove the SCIM users and groups. This leverages the existing valid OAuth Bearer token providing access to the SCIM endpoints of the Identities microservice and submits a HTTP DELETE request. In that previous post I also provided an example script to remove all the SCIM users and groups from a SAS Viya environment.
Conclusion
If you need to use an attribute such as on-premises User Principal Name for your users of SAS Viya, perhaps to make use of Kerberos Hybrid authentication with Protocol Transition, then you’ll need to complete the steps we have covered here and in the previous post. With both SCIM and ODIC configured to use the on-premises User Principal Name, your end-users accessing your SAS Viya environment with OIDC authentication will now be correctly identified by their on-premises User Principal Name. Then the SAS Kerberos Proxy will be able to obtain Kerberos credentials for your users using the correct UPN value and make these credentials available to your SAS Cloud Analytics Services and SAS Compute Server sessions. These credentials can then be used to access your data sources using Kerberos.
Find more articles from SAS Global Enablement and Learning here.
