Organization users¶

Organizations with multiple accounts often need to have the same person be a user in more than one of those accounts. To avoid the repetition of creating a user object for the person in each account separately, the organization administrator can create an organization user in the organization account. Each organization user acts as a global user entity that can be imported into regular accounts by account administrators, simplifying the process of having the same person have a user object in multiple accounts.

Account administrators don’t add organization users directly to their regular account. Rather, they add organization user groups, which are logical groupings of organization users. When the account administrator imports the organization user group, its organization users are added to the account.

Note

If you want to create organization users for people who already have a user object in one or more regular accounts, you’ll need to link the organization user with the existing user object after importing the organization user group. For more information, see Resolve conflicts after importing users.

Get started¶

The basic workflow of getting organization users into one or more accounts is as follows:

  1. As a global organization administrator in the organization account:

    1. Create an organization user for each person that you want to be a user in multiple regular accounts.

    2. Create an organization user group that is a logical grouping of the users.

    3. Add the organization users to the organization user group.

    4. Make the organization user group available to the account administrators in regular accounts.

  2. As an administrator in a regular account:

    1. Import the organization user group into the account.

    2. Check for and resolve any conflicts.

For an end-to-end example of this workflow, see Extended example.

Create an organization user¶

The organization administrator creates an organization user with the basic properties of a user object such as the login name and email. Only an email is required, but these basic properties can’t be set in a regular account after the user is imported. For a list of these basic properties, see CREATE ORGANIZATION USER.

As an example, the following command creates an organization user:

USE ROLE GLOBALORGADMIN;

CREATE ORGANIZATION USER asmith
   EMAIL = 'asmith@example.com'
   LOGIN_NAME = 'asmith@example.com';
Copy

Organization user groups¶

Organization user groups are logical groupings of organization users. The organization administrator creates these organization user groups, then adds the organization users that should belong in each group. When the account administrator imports an organization user group into an account, all the organization users in the group become user objects in the regular account. An organization user can be a member of multiple organization user groups.

When the account administrator imports an organization user group into a regular account, Snowflake creates an access control role of the same name. For example, if the organization user group is named data_stewards, then importing the group to the regular account creates a role named data_stewards. Each user imported from the organization user group is granted this role.

Administrators in the regular account can fine-tune access control by granting and revoking privileges to the role that has been granted to each of the users that were imported from the organization user group. You can also grant account-specific roles to the new role or grant the new role to account-specific roles.

You can import the same organization user group into multiple regular accounts to implement consistent roles across the organization. Each regular account can assign account-specific privileges to the role, but the naming will be consistent. Alternatively, you could create a separate organization user group for each account, then add the organization users that are needed in a particular account to the appropriate organization user group.

If the administrator imports multiple organization user groups that contain the same organization user, only one local user is created, and this user is granted the roles from all of the organization user groups.

The organization administrator task of preparing an organization user group for the account administrator of regular accounts is a three-step process:

  1. Create the organization user group.

  2. Add organization users to the group.

  3. Set the visibility of the group to specify which regular accounts can access it.

Create an organization user group¶

The organization administrator executes the CREATE ORGANIZATION USER GROUP command to create a new organization user group in the organization account.

As an example, the following command creates an organization user group that represents a logical grouping of data engineers.

CREATE ORGANIZATION USER GROUP data_engineers_group;
Copy

Add organization users to an organization user group¶

After the organization administrator creates an organization user group, they can execute the ALTER ORGANIZATION USER GROUP command to add organization users to the group as a comma-delimited list. For example, to add two existing organization users to the organization user group data_engineers_group, execute:

ALTER ORGANIZATION USER GROUP data_engineers_group
   ADD ORGANIZATION USERS asmith, sjohnson;
Copy

Make organization user groups available to regular accounts¶

After you have created an organization group, you need to specify which regular accounts can view and import the group. Account administrators cannot use the organization user group to import users until you use the ALTER ORGANIZATION USER GROUP command to set the visibility of the group. You can specify that all regular accounts can import the organization user group or you can restrict access to specific accounts.

Important

Executing the ALTER ORGANIZATION USER GROUP command to set the visibility overwrites previous visibility settings. For example, if the visibility was set to ALL, and then the ALTER command was executed to set visibility to account_a, the users and roles created from the organization user group will be removed from all accounts except for account_a.

The following command only allows the account qa_env to add the organization user group:

ALTER ORGANIZATION USER GROUP data_engineers_group
   SET VISIBILITY = ACCOUNTS qa_env;
Copy

Import users in a regular account¶

After the organization administrator has created an organization user group, administrators in regular accounts can import the organization users by executing the ALTER ACCOUNT command to add the organization user group. These administrators can only import an organization user group if the organization administrator has set the visibility of the group so the regular account can access it.

By default, only users with the ACCOUNTADMIN role can import organization user groups into the regular account. To allow other users to import an organization group, grant them the IMPORT ORGANIZATION USER GROUPS privilege.

The syntax to import an organization user group to a regular account is as follows:

ALTER ACCOUNT ADD ORGANIZATION USER GROUP <group_name>
Copy

For an example of importing an organization user group to add users, see Extended example.

Resolve conflicts after importing users¶

The account administrator who imports organization users in their regular account must manually check for conflicts. These conflicts can arise between the properties of users or the name of the organization user group.

Conflict between organization user group and existing role¶

A conflict occurs when the name of the organization user group matches the name of an existing role in the regular account. The users in the group are not imported until you resolve the conflict.

To check whether there is a conflict after importing an organization user group, do the following:

  1. Execute the SHOW ORGANIZATION USER GROUPS command.

  2. In the is_imported column, check if the value is TRUE. If the value is FALSE, the organization user group was not successfully imported, which might indicate that there is a conflict.

You can resolve the conflict between a role and an organization user group by linking the role with the group. Linking a role allows it to be managed as an organization user group going forward. After you link the conflicting role, the organization user group is added to the account without further action. Call the SYSTEM$LINK_ORGANIZATION_USER_GROUP function to link a role with an organization user group.

For example, suppose the role marketing_team existed in your account before importing the organization user group marketing_team to the account. To link the role to the organization user group and complete the process of importing the group, execute the following:

SELECT SYSTEM$LINK_ORGANIZATION_USER_GROUP('marketing_team');
Copy

Conflict between organization user and existing user¶

A conflict occurs when any of the following is true:

  • The name property of an organization user matches the name of an existing user in the regular account.

  • The login_name property of an organization user matches the login_name of an existing user in the regular account.

To check whether there is a user conflict after importing an organization user group, do the following:

  1. Execute the SHOW ORGANIZATION USERS IN ORGANIZATION USER GROUP command.

  2. In the is_imported column, find rows where the value is FALSE. At least one property of the user in that row conflicts with the properties of an existing user.

Tip

You can use the RESULT_SCAN function to post-process the output of SHOW ORGANIZATION USERS and filter on the is_imported column. For example, to search for organization users that were not successfully imported from the marketing_team organization user group, execute the following:

SHOW ORGANIZATION USERS IN ORGANIZATION USER GROUP marketing_team;
SELECT * FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE "is_imported" = 'false';
Copy

If an existing user object corresponds to the same person as an organization user, and you want to manage the user as an organization user going forward, you can link the existing user with the organization user to resolve the conflict. Call the SYSTEM$LINK_ORGANIZATION_USER function to link an existing user with an organization user. For example, to link the existing user jloeb with the organization user jloebsmith, execute the following:

SELECT SYSTEM$LINK_ORGANIZATION_USER('jloeb', 'jloebsmith');
Copy

If you do not want to link the existing local user with the new organization user, you can rename the user object or its properties in the regular account to resolve the conflict. For example, if the pre-existing user and the organization user both have the login name JOE_LOGIN, you could execute the following in the regular account to avoid the conflict without linking:

USE ROLE ACCOUNTADMIN;
ALTER USER joe SET LOGIN_NAME = joe_login_renamed;
Copy

Modifying imported users¶

Administrators in a regular account can use the ALTER USER command to modify a subset of the properties of a user object after it has been imported. The administrator can modify all properties except the properties that can be set on the organization user in the organization account. For a list of the properties that can only be set in the organization account, see CREATE ORGANIZATION USER.

Removing organization users and groups¶

Organization users and organization user groups can be removed from a single account or removed from all accounts by dropping them in the organization account.

Removing users from a single regular account¶

An account administrator can execute an ALTER ACCOUNT command to remove an organization user group from the account. Removing the organization user group drops all of the users that were imported and removes the role that was created when the organization user group was imported. This command does not affect the organization users and organization user groups in other regular accounts, nor in the organization account.

Note

An organization user can be a member of multiple organization user groups. If a user was imported from more than one organization group, removing one of the groups from the regular account does not remove the user. The user isn’t removed until all of the organization user groups are removed.

For example, the following command drops all of the users imported from the data_stewards group and deletes the data_stewards role:

ALTER ACCOUNT REMOVE ORGANIZATION USER GROUP data_stewards;
Copy

Removing users from all regular accounts¶

When an organization user is dropped in the organization account, the corresponding user object is dropped from every regular account that imported the user. To drop an organization user, execute the DROP ORGANIZATION USER command in the organization account.

When an organization user group is dropped in the organization account, the effect on organization users depends on whether the users in the regular account belong to other organization user groups that were also imported into the account. If an organization user belongs to a different organization user group that was imported, the user is not removed from the account. Otherwise, dropping the organization user group removes all of the users imported from the group.

Dropping an organization user group also removes the role that was created when the group was imported.

To drop an organization user group, execute the DROP ORGANIZATION USER GROUP command in the organization account.

Unlinking organization users and organization user groups¶

When organization users are successfully imported into a regular account, the local user object is linked to the organization user. If you decide you want to keep the user object in an account, but no longer want it associated with the organization user, you can use the SYSTEM$UNLINK_ORGANIZATION_USER function to unlink the local user from the organization user. All of the properties of the user are preserved and it can be managed as a local user going forward.

Similarly, you can use the SYSTEM$UNLINK_ORGANIZATION_USER_GROUP function to unlink a role that was created by adding an organization user group. This keeps everything about the role the same, but unlinks it from the organization user group.

Extended example¶

Organization administrator workflow

  1. As the organization administrator, sign in to the organization account.

  2. Create organization users for two people who are data stewards:

    USE ROLE GLOBALORGADMIN;

CREATE ORGANIZATION USER joe_kelley
EMAIL = 'jkelley@example.com'
LOGIN_NAME = 'jkelley@example.com';

CREATE ORGANIZATION USER grace_vivian
EMAIL = 'gvivian@example.com'
LOGIN_NAME = 'gvivian@example.com';
    Copy

  3. Create an organization user group that represents a logical grouping of data stewards.

    CREATE ORGANIZATION USER GROUP data_stewards_group;
    Copy

  4. Add the organization users to the new organization user group.

    ALTER ORGANIZATION USER GROUP data_stewards_group
   ADD ORGANIZATION USERS joe_kelley, grace_vivian;
    Copy

  5. Allow all regular accounts to import the organization user group.

    ALTER ORGANIZATION USER GROUP data_stewards_group
   SET VISIBILITY = ALL;
    Copy
Account administrator workflow

  1. As the account administrator, sign in to the regular account where you want to import the organization users.

  2. List the organization user groups that can be imported into the account.

    USE ROLE ACCOUNTADMIN;

SHOW ORGANIZATION USER GROUPS;
    Copy

  3. Import the organization user group into the account.

    ALTER ACCOUNT
  ADD ORGANIZATION USER GROUP data_stewards_group;
    Copy

  4. Check for conflicts between the organization user group and an existing role:

    SHOW ORGANIZATION USER GROUPS;
    Copy

    Make sure the value of the is_imported column is TRUE, which indicates there was no conflict.

  5. List the users that have been added to the account and check for conflicts:

    SHOW ORGANIZATION USERS IN ORGANIZATION USER GROUP data_stewards_group;
    Copy

    Make sure the value of the is_imported column is TRUE for all of the organization users, which indicates there were no conflicts.

Language: English