SAS Viya 2022.10 UID and GID Changes
With the SAS Viya 2022.10 Stable release there are changes in the way in which UID & GID information is handled by the Identities microservice. Starting with the SAS Viya 2022.10 Stable release SAS Viya moves to an EITHER-OR model for the user and group identifier information. Either, as the SAS Administrator, you choose to Bring Your Own (BYO) UID and GID information, which would be loaded to the Identities microservice. Or, as the SAS Administrator, you chose to allow the Identities microservice to generate the UID and GID information. You can load UID and GID information either from LDAP or manually. In this blog we’ll examine this new model in more detail and look at some implications of the change.
Why be Concerned with UID & GID
Before we delve into the details, why should you be concerned with the UID & GID? In your SAS Viya environment the Launcher service, SAS Cloud Analytic Services, and the SAS/CONNECT Spawner all can launch processes as your end-users. The Launcher Service always fetches the user attribute information from the Identities microservice, which includes the UID and possibly the GID information. This is used for the pod that is then launched. For SAS Cloud Analytic Services, the default option is CASCLOUDNATIVE=1 which means that for Host Launched sessions the user attribute information will be returned from the Identities microservice. Equally, for the SAS/CONNECT Spawner since the default option here is SASCLOUDNATIVE=1, the user attribute information is queried from the Identities microservice. Therefore, if your end-users will be interacting with the file system from the SAS Compute Server, SAS Cloud Analytic Services host-launched sessions, or from SAS/CONNECT sessions the UID and GID used will be crucial to the implementation of file system permissions.
How to Choose the Mode
The SAS Viya 2022.10 Stable release introduces the following new configuration settings for the Identities microservice:
- sas.identities.identifier.generateUids = true/false
- sas.identities.identifier.generateGids = true/false
- sas.identities.identifier.disableGids = true/false
First, let’s consider the setting sas.identities.identifier.generateUids:
Next, let’s consider the two settings (sas.identities.identifier.disableGids and sas.identities.identifier.generateGids) for controlling GID values:
As a SAS Administrator you choose to either Bring Your Own (BYO) values or to generate values based on these configuration settings. Any previous configuration settings are not used.
How to Configure the Settings
These three configuration options are under the sas.idenities group of settings. The sas.identities settings are not tenant specific, which means in an application multi-tenant environment you would only configure the settings once in the multi-tenant provider. You as a SAS Administrator can set the values, if you do not want to use the defaults, in any of the following ways:
- Using SAS Environment Manager to manually configure the settings. The Identities microservice will automatically pick up the configuration change after a couple of minutes.
- Use the SAS Viya CLI to either create or patch the configuration by providing a JSON configuration file.
- Use the sitedefault.yaml to load these new configuration settings, since these are new properties this can also be done when upgrading to the SAS Viya 2022.10 Stable release from an earlier release. Your sitedeafult.yaml content would look like the following example:
--- config: application : ... ... sas.identities: ... identifier.generateUids: 'true' identifier.generateGids: 'true' identifier.disableGids: 'false' ...
The Default Behaviour
By default, with the SAS Viya 2022.10 Stable release and later, the following will occur:
- The Identities microservice will always provide a generated UID even if your LDAP Provider has a valid POSIX UID attribute
- The Identities microservice will not allow you as a SAS Administrator to load UID values through the Identities microservice endpoint
- The Identities microservice will allow you as a SAS Administrator to provide GID values from your LDAP Provider
- The Identities microservice will allow you as a SAS Administrator to load GID values through the Identities microservice endpoint
- The Identities microservice will not generate a GID value, if GID values are not provided by your LDAP Provider or loaded nothing is returned
This means that the default is to generate UID values and BYO GID values.
Is UID Treated the Same As GID
As we can see from the above the UID values are not treated the same as the GID values. In the default case the assumption is that you want the Identities microservice to generate UID values, but if you don’t provide GID values then no GID values are returned. So as a SAS Administrator you can choose:
- To generate UID values and only Bring Your Own GID values
- To only Bring Your Own UID values and generate GID values
- To Bring Your Own UID & GID values
- To generate both UID & GID values
- To ignore GID values altogether
How Are Values Generated
When the Identities microservice is configured to generate values for GID and/or UID the same approach is used. Values are only generated when the Identifier endpoint is called; for a user the Identifier endpoint is https://viya.customer.com/identities/users/{{USERNAME}}/identifier , while for a group it is: https://viya.customer.com/identities/groups/{{GROUPID}}/identifier. To generate values the Identities microservice takes the Identity type (either USER or GROUP) along with the accountId value and generates a SHA hash of the string. This ensures that a user with the same accountId value as a group will generate a different hash value. The hash value is then mapped onto a numerical space to generate either the UID or GID value. If the UID is generated for a user their primary GID (returned as just gid from the Identifier endpoint) is always set to the same value. Only when generating GID values for groups will these values be populated as secondaryGid for the end-user’s Identifier endpoint. For example, looking at the user Identifier endpoint when we are generating both values, we will see the following:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
Whereas, if we look at the user Identifier endpoint when we are generating only the UID values we will see the following:
The same output will be provided by the user Identifier endpoint if we set sas.identities.identifier.disableGids to true as well, so only the primary GID will be returned.
How Are Values Loaded
When you as a SAS Administrator decide to Bring Your Own values, you have a choice in how to provide them. If you have a LDAP Provider with a POSIX schema the Identities microservice can fetch the UID and/or the GID values from your LDAP Provider along with the other user and group attributes. Alternatively, you can load UID and/or GID information directly into the Identities microservice. This can be done with either the SAS Viya CLI or the Identities microservice REST API.
With the SAS Viya CLI you can update individual users:
/opt/sas/viya/home/bin/sas-viya identities update-user
Command requires the following flags: id
NAME:
sas-viya identities update-user - Updates information about an existing user. Currently only supports updating the user identifier (uid/gid) values.
USAGE:
sas-viya identities update-user [command options] [arguments...]
OPTIONS:
--gid "0" Specifies the gid number to set or update for the user. This value must be greater than 0.
--id Specifies the ID of the user that is being updated.
--uid "0" Specifies the uid number to set or update for the user. This value must be greater than 0.
Command requires the following flags: id
Or individual groups:
/opt/sas/viya/home/bin/sas-viya identities update-group
Command requires the following flags: id
NAME:
sas-viya identities update-group - Updates information about an existing group.
USAGE:
sas-viya identities update-group [command options] [arguments...]
OPTIONS:
--description Specifies a new description for the group.
--gid "0" Specifies the gid number to update for the group. This value must be greater than 0.
--id Specifies the ID of the group that is being updated.
--name Specifies a new name for the group.
Command requires the following flags: id
With the next release of the identities plugin version 1.18.11 you will also be able to bulk load either users or groups by providing either a JSON or CSV input file. In addition, the Python Tools for SAS Viya also offers an option to set the POSIX user attributes for users and groups.
Ignore GID Values
The setting sas.identities.identifier.disableGids when enabled (set to true) will prevent the Identities microservice from fetching GID information entirely. This is irrespective of the method of providing GID information, whether Bring Your Own or generated GID values. If you as a SAS Administrator are not concerned with GID information, perhaps your file system security model is purely based around UID, then you can set sas.identities.identifier.disableGids=true. This means the Identities microservice will respond slightly faster since there will be no internal processing for GID values. Meaning that there will be no LDAP queries for GID information, nor any internal database queries for GID information.
Generated Conflicts
As discussed above the generated values are calculated by taking a SHA hash and then mapping the resulting hash value onto a numerical space. While the SHA hash will be unique there is a chance that when mapping onto the numerical space two different hash values could result in the same numerical value. A conflict or clash will occur when the Identifier endpoint is called for a user or group and the value generated is the same as an existing generated value. If such a clash does occur, the Identities microservice will retry generating the value, moving slightly the numerical space the hash is mapped onto. This will prevent clashes in generate mode from producing an exception and you will be guaranteed to correctly generate a value.
However, if you are in the very rare case of experiencing a conflict and you happen to have multiple environments such as DEV, TEST, and PROD where you expect the generated values to be the same you might have an issue. Since the UID or GID values are only generated when the Identifier endpoint is called, for example by logging into SAS Studio. You might find that your end-users have triggered the generation in a different order. If user1 and user2 both generate the same UID then whichever one is queried first gets the original UID value and the second one gets the newly generated alternative. If on DEV, user1’s identifier was queried first and got 1234 and user2 was queried second and got 9876, that is their identifiers. Then if on TEST, user2’s identifier was queried first it would get 1234 and the user1 query is now second, it would get the newly generated alternative.
A way to resolve this issue would be to use the SAS Viya CLI to remove the two identifier values and have them regenerated. The SAS Viya CLI provides the following command to delete user identifier information:
/opt/sas/viya/home/bin/sas-viya identities delete-user-identifier
Command requires the following flags: id
NAME:
sas-viya identities delete-user-identifier - Deletes the identifier for the specified user.
USAGE:
sas-viya identities delete-user-identifier [command options] [arguments...]
OPTIONS:
--id Specifies the ID of the user whose identifier is being deleted.
Command requires the following flags: id
As well as an equivalent for groups:
/opt/sas/viya/home/bin/sas-viya identities delete-group-identifier
Command requires the following flags: id
NAME:
sas-viya identities delete-group-identifier - Deletes the identifier for the specified group.
USAGE:
sas-viya identities delete-group-identifier [command options] [arguments...]
OPTIONS:
--id Specifies the ID of the group whose identifier is being deleted.
Command requires the following flags: id
Or you could move to the Bring Your Own values mode instead.
Changing Mode
If you decide to change mode for either UIDs and/or GIDS with the SAS Viya Stable release 2022.10 and higher you can. If you change the value of the options from true to false, or vice-versa, the Identities microservice will automatically clean-up the next time the Identifier endpoint is called. For example, if you start generating both UID & GID values, but then decide that you need to provide the GID values you can change sas.identities.identifier.generateGids to false. You can then provide those GID values either from your LDAP with POSIX attributes or by loading them. The next time the Identifier endpoint is called, for example by a user logging into SAS Studio, the new value will be used.
However, while the Identities microservice will now use the value you want; separately, you will need to ensure any file system or other external content is correctly updated.
Upgrading to SAS Viya 2022.10 and higher
If you are upgrading to SAS Viya 2022.10 and higher from an earlier release of SAS Viya then the new EITHER-OR model will apply after you upgrade. Any previous configuration settings to enable the generation of UID/GID information no-longer apply and will have no effect. If you as a SAS Administrator do not choose a mode, as we discussed above, you will have the default behaviour. Also, since the Identities microservice will automatically clean-up, then previous values for UID or GID used by SAS Viya might be lost.
For example, if in a previous release you were leveraging LDAP with POSIX attributes to provide your UID values – in the new default case you will now generate UID values. As soon as the Identifier endpoint is called for a given user their UID values will be replaced. This would happen as soon as your end-users log into SAS Studio, since the Launcher service will call the Identifier endpoint.
Therefore, before you upgrade you should understand how your existing environment is configured and how this will map to the new EITHER-OR model for the provision of UID/GID information. Otherwise, your end-users will not be able to access content after the upgrade.
What Should I Choose?
Finally, let’s review some different scenarios and look at the options you could choose to use.
Scenario: SCIM Environment with no file system access
In this case you don’t really care what UID and GID values are used. It makes sense to use generated UID and primary GID values, but you do not need secondary GID values. As such, you would set the options to:
- sas.identities.identifier.generateUids = true
- sas.identities.identifier.generateGids = false
- sas.identities.identifier.disableGids = true
Scenario: POSIX Attributes in LDAP and using shared file systems
In this case you already have one version of the truth for user attributes in your LDAP. As such you want to ensure SAS Viya uses these LDAP POSIX attributes so you would set the options to:
- sas.identities.identifier.generateUids = false
- sas.identities.identifier.generateGids = false
- sas.identities.identifier.disableGids = false
Scenario: Environment with shared file systems leveraging an existing group-based security model
In this case you are not particularly concerned with the UID values, but the secondary GID values are vital to your file system security model. This file system security model already exists, and SAS Viya must use the same GID values as your existing systems. As such, you would allow SAS Viya to generate the UID values, but you would provide your own GID values so you would set the options to:
- sas.identities.identifier.generateUids = true
- sas.identities.identifier.generateGids = false
- sas.identities.identifier.disableGids = false
If you have an LDAP with the POSIX group attributes, you could use this. Alternatively, if you don’t have the GID values in LDAP you could instead load these into SAS Viya, as we discussed above.
Scenario: Environment with shared file systems leveraging a new group-based security model
In this case you are not particularly concerned with the UID values, but the secondary GID values are vital to your file system security model. But this is a new group-based security model, and it will only apply to SAS Viya. So, you will be able to use the GID values generated by SAS Viya to build this new file system security mode. As such, you would allow SAS Viya to generate both the UID & GID values so you would set the options to:
- sas.identities.identifier.generateUids = true
- sas.identities.identifier.generateGids = true
- sas.identities.identifier.disableGids = false
You can then call the group identifier endpoint to discover the generated GID values to use in building your new security model.
Conclusion
With the SAS Viya 2022.10 Stable release changes have been made to how UID and GID information is made available to SAS Viya. The change to an EITHER-OR model will ensure that in the future there are no confusing setups where some UID/GID information for a set of users is provided whilst for another set, within the same environment, this information is generated. There might be some initial confusion as we move to this new model, but I hope that the information we have discussed here makes it much clearer. Moving forward this will be a more robust model for the provisioning of user attributes.
Find more articles from SAS Global Enablement and Learning here.
