How to Manage UIDs and GIDs with the Identities Service

UID & GID Considerations

In your SAS Viya platform environment, the Launcher Service, SAS Cloud Analytic Services, and the SAS/CONNECT Spawner can all launch processes as end users. Here are some considerations for each of these:

• The Launcher Service always obtains the user attribute information from the Identities service or the values registered to a custom application, 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. For Host Launched sessions, the user attribute information is returned from the Identities service or the values registered to a custom application.

  For more information about the CASCLOUDNATIVE option see The CASHostAccountRequired Custom Group.

• For the SAS/CONNECT Spawner, the default option is SASCLOUDNATIVE=1. The user attribute information is queried from the Identities service or the values registered to a custom application.

  For more information about the SASCLOUDNATIVE option see SASCLOUDNATIVE in SAS Viya Platform: Programming Run-Time Servers.

If users interact 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 that is used is crucial to the implementation of file system permissions.

Selecting Configuration Settings

Below are new configuration settings for the Identities service:

• sas.identities.identifier.generateUids = true/false
• sas.identities.identifier.generateGids = true/false
• sas.identities.identifier.disableGids = true/false

The following table shows expected behaviors for the setting sas.identities.identifier.generateUids:

The following table shows expected behavior for the two settings used to control GID values; sas.identities.identifier.disableGids and sas.identities.identifier.generateGids:

As a SAS Administrator, you choose to either provide your own values or to generate values based on these configuration settings. Any previous configuration settings are not used.

How to Configure the sas.identities Settings

The sas.identities.identifier configuration options are part of the sas.identities group of settings. If you do not want to use the default values, a SAS Administrator can set the values. Here are the different ways that you can set the values. You can use either of these methods to set the configuration options:

1. Use SAS Environment Manager to manually configure the settings. The Identities service automatically retrieves the configuration change after a few of minutes.
2. Use the SAS Viya platform CLI to either create or patch the configuration by providing a JSON configuration file.

Default Behaviors of UID and GID

By default, with SAS Viya platform 2022.10 and later releases, the following occurs:

• The Identities service always provides a generated UID, even if your LDAP Provider has a valid POSIX UID attribute.
• The Identities service does not allow you, as a SAS Administrator, to load UID values through the Identities service endpoint.
• The Identities service allows you, as a SAS Administrator, to provide GID values from your LDAP Provider.
• The Identities service allows you, as a SAS Administrator, to load GID values through the Identities service endpoint.
• The Identities service does not generate a GID value if either of the following are true:
  • GID values are not provided by your LDAP Provider.
  • Nothing is returned when the identities service is loaded.

The default behavior is to generate UID values and to provide GID values.

Managing UID and GID Values

As shown in Default Behaviors of UID and GID , UID values are not treated the same as the GID values. In the default case, the assumption is that you want the Identities service to generate UID values, but if you do not provide GID values, then no GID values are returned. As a SAS Administrator, you can choose one of the following:

• generate UID values and provide your own GID values
• provide your own UID values and generate GID values
• provide your own UID & GID values
• generate both UID & GID values
• ignore GID values altogether

How Are UID and GID Values Generated

When the Identities service is configured to generate values for GID or UID, the same approach is used. Values are generated when the Identifier endpoint is called. The following table lists the identifier endpoints.

To generate values, the Identities service takes the identity type (either USER or GROUP) along with the accountId value and generates an SHA hash of the string. This ensures that a user with the same accountId value as a group generates 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 are these values populated as secondaryGid for the end-user’s Identifier endpoint. For example, the following output shows the user Identifier endpoint when generating User and GID values:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <identityIdentifier version="1"> <links>
<link href="/identities/users/sasadm/identifier" method="GET" 
rel="self" type="application/vnd.sas.identity.identifier" uri="/identities/users/sasadm/identifier"/>
<link href="/identities/users/sasadm" method="GET" 
rel="user" type="application/vnd.sas.identity.user" uri="/identities/users/sasadm"/>
 <link href="/identities/users/sasadm/identifier" method="PUT" 
rel="update" type="application/vnd.sas.identity.identifier" uri="/identities/users/sasadm/identifier"/>
</links>
<gid>1681596511</gid>
<id>sasadm</id>
<secondaryGids>
    <secondaryGid>456501765</secondaryGid>
    <secondaryGid>436234771</secondaryGid>
    <secondaryGid>1713176570</secondaryGid>
    <secondaryGid>1180074129</secondaryGid>
    <secondaryGid>1729685794</secondaryGid>
    <secondaryGid>940932761</secondaryGid>
    <secondaryGid>173401048</secondaryGid>
    <secondaryGid>114936103</secondaryGid>
    <secondaryGid>661725102</secondaryGid>
</secondaryGids>
<uid>1681596511</uid>
</identityIdentifier>

Whereas, the following output shows the user Identifier endpoint if you are generating only UID values.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <identityIdentifier version="1"> <links>
<link href="/identities/users/sasadm/identifier" method="GET" rel="self" 
type="application/vnd.sas.identity.identifier" uri="/identities/users/sasadm/identifier"/>
<link href="/identities/users/sasadm" method="GET" 
rel="user" type="application/vnd.sas.identity.user" uri="/identities/users/sasadm"/>
<link href="/identities/users/sasadm/identifier" method="PUT" rel="update" 
type="application/vnd.sas.identity.identifier" uri="/identities/users/sasadm/identifier"/>
</links>
<gid>1681596511</gid>
<id>sasadm</id>
<uid>1681596511</uid>
</identityIdentifier>

The same output is provided by the user Identifier endpoint if you set sas.identities.identifier.disableGids to true as well. Only the primary GID is returned.

How Values Are Loaded

When, as a SAS Administrator, you decide to provide your own values, you have a choice in how to provide them. If you have an LDAP Provider with a POSIX schema, the Identities service can retrieve the UID or the GID values from your LDAP Provider along with the other user and group attributes. Alternatively, you can load UID or GID information directly into the Identities service. This can be done with either the SAS Viya platform CLI or the Identities service REST API.

With the SAS Viya Platform 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

With the SAS Viya Platform CLI you can also update 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

In addition, the Python Tools for SAS Viya Platform also offers an option to set the POSIX user attributes for users and groups.

Beginning with release version 1.18.11 of the identities plug-in, you can also bulk load either users or groups by providing either a JSON or CSV input file. The current available version of the identities plug-in is 1.18.9.

Ignoring GID Values

Setting sas.identities.identifier.disableGids to true prevents the Identities service from completely retrieving GID information. This applies regardless of the method of providing GID information, that is, whether you provide your own values or you generate GID values.

If your file system security model is primarily based on UID, you can, as a SAS Administrator, set sas.identities.identifier.disableGids to true. This means that the Identities service responds slightly faster since there is no internal processing for GID values. With this setting, there is no LDAP queries for GID information or any internal database queries for GID information.

Managing UID and GID Generated Conflicts

The UID- and GID-generated values are calculated by taking an SHA hash and then mapping the resulting hash value onto a numerical space. The SHA hash is unique. However, it is possible that when mapping onto the numerical space, two different hash values could result in the same numerical value. A conflict or clash occurs when the Identifier endpoint is called for a user or group and the value that is generated is the same as an existing generated value. If such a clash does occur, the Identities service retries generating the value, moving slightly the numerical space the hash is mapped onto. This prevents clashes in generate mode from producing an exception, and you are guaranteed to correctly generate a value.

However, if a conflict occurs and you have multiple environments (where you expect the generated values to be the same) you still might have a conflict issue. Since the UID or GID values are generated when the Identifier endpoint is called (for example: logging in to SAS Data and AI Studio), you might find that your end users have triggered the generation in a different order.

The following is an example scenario:

• If user A and user B both generate the same UID, then whichever one is queried first gets the original UID value. The second user gets the newly generated alternative value .
• On the first system, User A is queried first and is given the value 1234. User B is queried second and is given the value 9876. These are their identifiers.
• Then, if on a different system, user B’s identifier is queried first and is given the value 1234. User A's identifier is queried second and is given the newly generated, alternative value.

One way to resolve this issue is to use the SAS Viya Platform CLI to remove the two identifier values and then regenerate them. The SAS Viya Platform 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

The SAS Viya Platform CLI also provides the following command to delete group identifier information:

/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

Alternatively, you could provide your own UID and GID values.

Changing UID and GID Values

Starting with 2022.10, you can change the values for either UIDs or GIDs. If you change the true or false value of one of the settings, the Identities service automatically corrects the value the next time the Identifier endpoint is called.

For example, if you are generating both UID and GID values, but then decide that you need to provide the GID values, you can change the setting 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 Data and AI Studio ), the new value is used.

Although the Identities service now uses the value that you want, separately, you must ensure that any file system or other external content is correctly updated.

Upgrading to SAS Viya Platform 2022.10 and Later

If you are upgrading to 2022.10 or later from an earlier release, then the new settings for managing the user and group identifier information apply after you upgrade. Any previous configuration settings that enable the generation of UID or GID information no-longer apply and have no effect.

If, as a SAS Administrator, you do not choose a model for managing the user and group identifier information, then the default settings apply. In addition, the Identities service automatically updates and corrects your user and group identifier information. As a result, previous values for UID or GID used by the SAS Viya platform might be lost.

Therefore, before you upgrade to 2022.10 or later you should understand how your existing environment is configured and how this maps to the new model for the provision of UID and GID information. Otherwise, your end users will not be able to access content after the upgrade.

For example, if you leveraged LDAP with POSIX attributes to provide your UID values in a previous release, after upgrading the new default model would generate UID values. As soon as the Identifier endpoint is called for a given user, their UID values are replaced. This happens as soon as your end users log in to SAS Data and AI Studio (known as SAS Studio prior to 2026.06) because the Launcher service calls the Identifier endpoint.

Deciding Which Combination of UID and GID Setting Values to Use

Here are some different scenarios for setting the UID and GID identifier values.

Bulk Load Identifiers for the Identities API

The Identities API now provides endpoints that enable you to bulk load UID and GID values for identities that are stored in the extended_attributes Postgres table. The input can contain both UID and GID values, and the API handles JSON input for the REST call.

The identity must exist in the system prior to calling an endpoint to add identifier values to them. If the user or group is not found, the entry is logged in the identities service log and skipped. The system continues processing the entries. Here are the required input values:

• IdentityType - user or group identity.
• IdentityId -the ID of the user or group whose identifier values you are updating or adding.
• GID Value - the primary GID for a user or the GID value of the group. If this value is not specified for a user, the endpoint currently assigns the UID value as the primary gid value for a user.
• UID Value -the UID value for the user.

Here is an example JSON input:

[   

   {  "type" : "user", "id : "user1",  "uid" : 200001, "gid" : 300001 },

   {  "type" : "user", "id : "user2",  "uid" : 200002, "gid" : 300002 },

   {  "type" : "user", "id : "user3",  "uid" : 200003 }

]

Bulk Load Identifiers for the Identities CLI

The SAS Viya Identities CLI provides bulk loading of user and group identifiers. The input can be either a JSON file or a CSV file for either user or group identifiers.

For bulk-loading group identifiers with the SAS Viya Identities CLI, the bulkload-group-identifiers command is used. You can bulk load group identifiers from a JSON or CSV file. You must specify the file name of a JSON or CSV file to load identifiers with. Here is an example:

sas-viya identities bulkload-group-identifiers --file path-to-file.

For bulk-loading user identifiers with the SAS Viya Identities CLI, the bulkload-user-identifiers command is used. You can bulk load user identifiers from a JSON or CSV file. You must specify the file name of a JSON or CSV file to load identifiers with.

sas-viya identities bulkload-user-identifiers --file path-to-file.

Here is a JSON file example:

[   
   {  "type" : "user", "id : "user1",  "uid" : 200001, "gid" : 300001 },
   {  "type" : "user", "id : "user2",  "uid" : 200002, "gid" : 300002 },
   {  "type" : "user", "id : "user3",  "uid" : 200003 }
]

Here is a CSV file example:

user,user1,200001,300001
user,user2,200002,300002
user,user3,200003,                 

For more information about the SAS Viya Identities CLI see Identity Management: How to (CLI).