Using session policies¶
This topic provides examples on how to use session policies.
Standard session policy¶
The following steps are a representative guide to creating a session policy and setting the session policy on an account or user.
These steps assume a centralized management approach in which a custom role named policy_admin owns the session policy (i.e. has the
OWNERSHIP privilege on the session policy) and is responsible for setting the session policy on an account or user (i.e. has the APPLY
SESSION POLICY on ACCOUNT privilege or the APPLY SESSION POLICY ON USER privilege).
Note
To set a policy on an account, the policy_admin custom role must have the following permissions:
- USAGE on the database and schema that contain the session policy.
- CREATE SESSION POLICY on the schema that contains the session policy.
Follow these steps to implement a session policy.
-
Create a custom role that allows users to create and manage session policies. Throughout this example custom role is
policy_admin, although the role could have any appropriate name.If the custom role already exists, continue to the next step.
Otherwise, create the
policy_admincustom role: -
Grant privileges to the custom role.
If the
policy_admincustom role does not already have the following privileges, grant these privileges as shown below:- USAGE on the database and schema that will contain the session policy.
- CREATE SESSION POLICY on the schema that will contain the session policy.
- APPLY SESSION POLICY on the account.
- APPLY SESSION POLICY on each user, if you plan to set session policies at the user level.
If associating a session policy with an individual user:
For more information, see Summary of commands, operations, and privileges.
-
Create a new session policy.
For more information, see CREATE SESSION POLICY.
-
Set the session policy on the account with the ALTER ACCOUNT command, or a user with the ALTER USER command.
Important
To replace a session policy that is already set for an account or user, specify
FORCEin the statement that sets the new session policy. The existing policy stays in place until the new one replaces it, so the account or user is never without a policy during the transition. For example:Alternatively, unset the session policy first and then set the new session policy for the account or user. No policy is set between the two statements. For example:
Specifying secondary roles in a session policy¶
The following sections detail how to specify secondary roles in a session policy:
- Set the property in a session policy
- Unset the property in a session policy
- Disallow secondary roles for all users in the account
- Disallow secondary roles for a specific user
- Allow a user to use specific secondary roles
For more information about secondary roles in a session policy, see Secondary roles in a session policy
Set the property in a session policy¶
The security administrator can create a new session policy or modify an existing session policy to set the
ALLOWED_SECONDARY_ROLES property. For example:
-
Create a new session policy to allow all secondary roles:
-
Modify an existing session policy to disallow secondary roles:
The ALTER SESSION POLICY command can modify the property value if the property is already set.
For details about the syntax, see the Managing session policies.
You can use the DESCRIBE SESSION POLICY command or call the GET_DDL function to view
the value of the ALLOWED_SECONDARY_ROLES property.
Unset the property in a session policy¶
You can use an ALTER SESSION POLICY command to unset secondary roles in the session policy:
Disallow secondary roles for all users in the account¶
To prevent all users in an account from using secondary roles, set a session policy on the account that disallows secondary roles for the session. For example:
-
Modify a session policy to disallow secondary roles:
-
Assign the session policy to the account:
If a user tries to activate secondary roles with a USE SECONDARY ROLES command, such as USE SECONDARY ROLES analyst;, the following
error message occurs:
Disallow secondary roles for a specific user¶
To disallow a specific user from using secondary roles, set a session policy on the user that disallows secondary roles for the session. For example, if that session policy already exists:
If there is a session policy that is set on the account, the session policy assigned to the user overrides the session policy on the account.
If the user runs a USE SECONDARY ROLES command to activate secondary roles, such as USE SECONDARY ROLES (ANALYST, DATA_SCIENTIST);
they will see the following error message:
Allow a user to use specific secondary roles¶
To enable a user to use specific secondary roles, do the following:
-
Create a session policy that specifies the secondary roles a user can use:
-
Set the session policy on the user:
The user can activate the secondary roles as needed with a USE SECONDARY ROLES command. For example:
-
Activate all secondary roles:
-
Activate
DATA_SCIENTISTas a secondary role:
For details about the syntax, see USE SECONDARY ROLES.
Replicate the session policy to a target account¶
You can replicate a session policy and its references, which are the assignments to a user or the account, from the source account to the target account using database replication and account replication. For details, see:
For details about replicating a session policy that specifies secondary roles, see replicate session policies with secondary roles.
Example journeys¶
The following journeys show how common goals combine the facts documented elsewhere. They are examples, not the only supported paths. You
can combine the same settings in other ways, using the linked pages for the details. The SQL uses placeholders such as <minutes> for
values, so look up the valid range and defaults in the linked pages before you choose one.
Log human users out of Snowsight after a period of inactivity¶
Goal: Require human users to authenticate again to Snowsight after they have been idle for a different period of time than the default.
Check first:
- Confirm that your role has the privileges to create and apply a session policy. See Session policy privileges.
- Find out whether a session policy is already applied at the level you plan to use, and which policy takes precedence for a user. See Precedence and Auditing session policies.
- Choose the idle timeout. The setting for Snowsight is described in Session policies.
Steps:
-
Create a policy that sets only the Snowsight idle timeout:
-
Apply it to all human users. For which users this covers, see Applying a session policy.
If a policy is already set at this level, see Replacing an applied policy.
Verify:
For when a change takes effect for open sessions, see Secondary roles in a session policy. For what happens when a Snowsight session expires, see Snowsight session expiration and logout behavior.
Undo:
Set session limits for drivers, the CLI, and service users¶
Goal: Limit the idle time and total lifespan of sessions opened through drivers, the CLI, and service users.
Check first:
- Which interfaces the session timeouts cover. See Snowflake sessions.
- Which settings apply to service users. See Session policies.
- Whether a service user already has a policy of its own, which takes precedence over the account-level policy for its type. See Precedence.
Steps:
-
Create a policy with the programmatic idle timeout and maximum lifespan:
-
Apply it to all service users, or use
FOR ALL PERSON USERSfor human users who connect through drivers and the CLI:
Warning
A maximum lifespan ends the session when it is reached, regardless of activity, even when a client keeps the session alive. When a
session closes, its running queries and jobs are terminated. Before you set SESSION_MAX_LIFESPAN_MINS, check that your longest
running jobs finish within it. See Session policy considerations and
Snowsight session expiration and logout behavior.
Verify:
Undo:
Limit what an AI agent can do with a restricted session scope¶
Goal: Set a ceiling on what an agent can do in a session. Choose a predefined scope, or an RSS object.
Check first:
- What the predefined scopes allow and don’t allow. See Predefined scopes.
- If you need a custom scope, the privileges required to create an RSS object and its structure. See RSS YAML structure and Create an RSS object and reference it.
Steps:
-
Create a session policy that references the scope.
Use a predefined scope:
Or create an RSS object as described in Create an RSS object and reference it, and reference it by fully qualified name:
-
Apply the policy to the account or to a user. See Attach the session policy to the account or a user.
Verify: From a session where an agent is active, check the active scope:
For when the scope applies, see Restricted Session Scope for agents. For when a change to an RSS object takes effect, see RSS YAML structure.
Undo:
Change a policy that is already applied¶
Goal: Change settings on a session policy that users already have.
Check first:
- Who the policy reaches. See Auditing session policies.
- That your role owns the policy. See Session policy privileges.
- When a change takes effect for sessions that are already open. See Secondary roles in a session policy.
Steps:
-
Find out who the policy reaches:
-
Alter only the settings you mean to change. For the settings you can set, see ALTER SESSION POLICY:
Verify: Describe the policy and compare it with what you recorded before the change:
Undo: Set the changed setting back to the value you recorded before the change.
Apply a policy to a policy scope, or replace the policy already there¶
Goal: Apply a policy to the account, to all users of one type, or to one user. If a policy is already set at that level, replace it.
Check first:
- The three levels, and which clause selects each. See Applying a session policy.
- Which policy takes precedence when more than one applies. See Precedence.
- Which policy is already set. See Auditing session policies.
Steps:
-
Apply the policy at the level you chose, here to all service users:
-
If a policy is already set at that level, use
FORCEto replace it. The existing policy stays in place until the new one replaces it, so the level is never without a policy. WhatFORCEreplaces is described in Replacing an applied policy. Alternatively, unset the existing policy at that level first and then set the new one. No policy is set at that level between the two statements.
Verify: List the users the policy reaches, as in Auditing session policies.
Undo: Unset the policy at that level, and set the previous policy again if you replaced one: