Configuring Snowflake to use Federated Authentication¶
This topic describes how to configure Snowflake for federated authentication using a SAML2 security integration. This topic assumes you have already configured your IdP to work with Snowflake.
Note
A SAML2 security integration replaces the deprecated SAML_IDENTITY_PROVIDER parameter.
If you have an existing SSO implementation that uses this deprecated parameter, you should migrate to a SAML security integration before continuing to configure Snowflake for federated authentication.
Snowflake will continue to support the deprecated parameter as long as there are implementations that use it.
Create a SAML2 Security Integration¶
Snowflake uses a SAML2 security integration to integrate with the IdP you are using to implement federated authentication. Use the CREATE SECURITY INTEGRATION command to start configuring Snowflake for SSO.
Important
When you configure an IdP for SSO, provide a URL for the Snowflake
account. The format of this URL must match the URLs in the SAML2_SNOWFLAKE_ISSUER_URL
and
SAML2_SNOWFLAKE_ACS_URL
parameters of the security integration.
If you do not define these parameters when creating the security integration, then they default to the legacy URL of the account.
For example, to create a security integration that uses an account name URL with private connectivity, run the following SQL command:
create security integration my_idp
TYPE = saml2
ENABLED = true
SAML2_ISSUER = 'https://example.com'
SAML2_SSO_URL = 'http://myssoprovider.com'
SAML2_PROVIDER = 'ADFS'
SAML2_X509_CERT = 'my_x509_cert'
SAML2_SNOWFLAKE_ISSUER_URL = 'https://<orgname>-<account_name>.privatelink.snowflakecomputing.com'
SAML2_SNOWFLAKE_ACS_URL = 'https://<orgname>-<account_name>.privatelink.snowflakecomputing.com/fed/login';
Note that /fed/login
is appended to the URL for the SAML2_SNOWFLAKE_ACS_URL
parameter. For more details about URL formats for
Snowflake accounts, see Connecting with a URL.
After configuring a SAML2 security integration, you can use the security integration to do the following tasks:
Encrypt SAML Assertions
Send Signed SAML Requests
Specify the SAML NameID Format
Export the SAML2 Security Integration Metadata
Force Re-authentication to Snowflake Procedure
Note
You can use a SAML2 security integration with Client Redirect if your account is a Business Critical Edition or higher.
For more information, see Redirecting Client Connections.
Configure SSO Login for Users¶
After you have created a SAML2 security integration, you can configure whether the user starts their SSO login from the IdP or from Snowflake.
An IdP-initiated SSO does not require configuration in Snowflake. You only need to inform your users about how to access Snowflake (e.g. using an internal portal).
The SAML2_ENABLE_SP_INITIATED parameter enables Snowflake-initiated SSO. The SAML2_SP_INITIATED_LOGIN_PAGE_LABEL parameter defines a string that identifies the IdP. This string appears on the Snowflake login page so users can access the IdP.
Use the ALTER SECURITY INTEGRATION
command to set these parameters:
alter security integration my_idp set SAML2_ENABLE_SP_INITIATED = true;
alter security integration my_idp set SAML2_SP_INITIATED_LOGIN_PAGE_LABEL = 'My IdP';
For information about how clients connect to Snowflake after you have configured SSO login for users, see Using SSO with Client Applications That Connect to Snowflake
Encrypt SAML Assertions¶
The SAML2_SNOWFLAKE_X509_CERT parameter ensures that SAML2 assertions are encrypted using Snowflake’s public certificate, securing traffic when users access Snowflake through federated authentication.
After receiving the encrypted assertions from the customer IdP, Snowflake decrypts the encrypted assertions with its private key. Snowflake never exports or makes its private key available.
Step 1: Set the SAML2_X509_CERT Parameter¶
If you do not have an existing SAML2 security integration, execute the following SQL statement to create a SAML2 security integration and set the SAML2_x509_cert parameter:
create security integration my_idp
TYPE = saml2
ENABLED = true
SAML2_ISSUER = 'https://example.com'
SAML2_SSO_URL = 'http://myssoprovider.com'
SAML2_PROVIDER = 'ADFS'
SAML2_X509_CERT = 'my_x509_cert'
Step 2: Export the Public Certificate from Snowflake¶
After you have created a SAML2 security integration, follow the steps below:
Execute the following SQL statement on the SAML2 integration.
desc security integration my_idp;
Find the SAML2_SNOWFLAKE_X509_CERT value in row 7, which is the public certificate in PEM format.
Save the value, ensuring you include the
BEGIN CERTIFICATE
andEND CERTIFICATE
delimiters. For example, the codeblock below contains a truncated certificate in PEM format:-----BEGIN CERTIFICATE----- MIICrTCCAZWgAwIBAgIJAOF6EPk93wjlMA0GCSqGSIb3DQEBCwUAMBYxFDASBgNV BAMMC1RFU1RBQ0NPVU5UMB4XDTIwMDE.... -----END CERTIFICATE-----
Step 3: Create a Certificate Signing Request (CSR) — Optional¶
By default, a SAML2 security integration in Snowflake uses a self-signed certificate for the SAML IdP to encrypt SAML assertions. If your organization requires using a certificate issued from a Certificate Authority (CA), then complete the steps below:
Generate a Certificate Signing Request (CSR) from Snowflake using the system function SYSTEM$GENERATE_SAML_CSR.
Provide the CSR to the CA of your choice so that the certificate can be issued.
Upload the Base64-encoded certificate into the SAML integration using the following ALTER statement, without the
BEGIN CERTIFICATE
andEND CERTIFICATE
delimiters.alter security integration my_idp set SAML2_SNOWFLAKE_X509_CERT = 'AX2bv...';
Execute the DESCRIBE INTEGRATION command to view the updated security integration:
desc security integration my_idp;
You can then upload the certificate for your private key using the CSR generated by the function into Snowflake.
Step 4: Configure Your SAML IdP¶
Upload the saved certificate in PEM format to your organization’s IdP as the SAML Encryption certificate.
Configure your IdP to encrypt SAML Assertions for the Snowflake service provider (SP).
Send Signed SAML Requests¶
You can send a signed SAML request from Snowflake to the IdP to verify Snowflake as an authentic service provider. To verify Snowflake, you can configure your IdP to use the certificate stored in the SAML2 security integration to ensure the SAML request originates from Snowflake, not a third-party that is impersonating Snowflake.
Step 1: Set the SAML2_SIGN_REQUEST Parameter¶
If you are creating a SAML2 security integration for the first time, ensure you set the SAML2_SIGN_REQUEST parameter.
If you created a SAML2 security integration without setting the SAML2_SIGN_REQUEST parameter, follow the steps below:
Execute the ALTER SECURITY INTEGRATION command as a user with an ACCOUNTADMIN role to update the security integration:
alter security integration my_idp set SAML2_SIGN_REQUEST = true;
Execute the DESCRIBE INTEGRATION command to view the updated security integration:
desc security integration my_idp;
Step 2: Configure Your IdP to Accept Signed Requests¶
Configure your IdP to accept signed requests from Snowflake. During the configuration, your IdP needs to have the certificate stored in the SAML2_SNOWFLAKE_X509_CERT parameter. Your IdP uses this certificate to verify that the SAML request originates from Snowflake.
Note
Snowflake is not responsible for configuring your IdP. For help with configuring your IdP, please consult your internal security administrator.
Execute the DESCRIBE INTEGRATION command:
desc security integration my_idp;
Save the value of the SAML2_SNOWFLAKE_X509_CERT parameter in row 7 to use in your IdP settings.
Specify the SAML NameID
Format¶
Snowflake supports allowing the administrator (i.e. user with the ACCOUNTADMIN role) to specify the SAML NameID
format that will be requested in the
outgoing SAML authentication request sent from Snowflake to the IdP.
Specifying the SAML NameID
format allows Snowflake to set an expectation of the identifying attribute of the user (i.e. SAML Subject) in the SAML
assertion from the IdP to ensure a valid authentication to Snowflake.
The SAML NameID
format can be integrated into the SAML2 security integration. You can specify the SAML NameID
in the security integration
using one of the following values:
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
If the SAML NameID
format is not specified, Snowflake uses the following value:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Step 1: Set the SAML2_REQUESTED_NAMEID_FORMAT parameter¶
If you are creating a SAML2 security integration for the first time, ensure you set the SAML2_REQUESTED_NAMEID_FORMAT parameter.
If you created a SAML2 security integration without setting the SAML2_REQUESTED_NAMEID_FORMAT parameter, follow the steps below:
Execute the ALTER SECURITY INTEGRATION command as a user with an ACCOUNTADMIN role to specify the SAML
NameId
format:alter security integration my_idp set SAML2_REQUESTED_NAMEID_FORMAT = '<string_literal>';
Execute the DESCRIBE INTEGRATION command to view the updated security integration:
desc security integration my_idp;
Step 2: Configure Your IdP to Specify the NameID
¶
Configure your IdP to specify the SAML NameID
format in SAML assertions.
Note
Snowflake is not responsible for configuring your IdP. For help with configuring your IdP, please consult your internal security administrator.
Export the SAML2 Security Integration Metadata¶
Snowflake provides SAML 2.0 metadata for the SAML2 security integration to facilitate configuring the Snowflake service provider in your IdP.
The SAML 2.0 metadata is contained in the SAML2_SNOWFLAKE_METADATA
property and can be obtained by executing a
DESCRIBE INTEGRATION command on the SAML2 security integration. For example:
desc security integration my_idp;
------------------------------------+---------------+-----------------------------------------------------------------------------+------------------+
property | property_type | property_value | property_default |
------------------------------------+---------------+-----------------------------------------------------------------------------+------------------+
SAML2_X509_CERT | String | MIICrTCCAZWgAwIBAgIJAOF6EPk93wj... | |
SAML2_PROVIDER | String | OKTA | |
SAML2_ENABLE_SP_INITIATED | Boolean | false | false |
SAML2_SP_INITIATED_LOGIN_PAGE_LABEL | String | my_idp | |
SAML2_SSO_URL | String | https://okta.com/sso | |
SAML2_ISSUER | String | https://okta.com | |
SAML2_SNOWFLAKE_X509_CERT | String | MIICrTCCAZWgAwIBAgIJAOF6EPk93wj... | |
SAML2_REQUESTED_NAMEID_FORMAT | String | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress | |
SAML2_SNOWFLAKE_ACS_URL | String | https://example.snowflakecomputing.com/fed/login | |
SAML2_SNOWFLAKE_ISSUER_URL | String | https://example.snowflakecomputing.com | |
SAML2_SNOWFLAKE_METADATA | String | <md:EntityDescriptor entityID="https://example.snowflakecomputing.com"> ... | |
SAML2_DIGEST_METHODS_USED | String | http://www.w3.org/2001/04/xmlenc#sha256 | |
SAML2_SIGNATURE_METHODS_USED | String | http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 | |
------------------------------------+---------------+-----------------------------------------------------------------------------+------------------+
As a representative example, the formatted SAML 2.0 XML metadata from the SAML2_SNOWFLAKE_METADATA
property is shown below. Note that the
X509certificate
values for signing
and encryption
are truncated.
<md:EntityDescriptor xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" entityID="https://example.snowflakecomputing.com">
<md:SPSSODescriptor AuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<dsig:KeyInfo>
<dsig:X509Data>
<dsig:X509Certificate>MIICrTCCAZWgAwIBAgIJAOF6EPk93wj... </dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<dsig:KeyInfo>
<dsig:X509Data>
<dsig:X509Certificate>MIICrTCCAZWgAwIBAgIJAOF6EPk93wj... </dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</md:KeyDescriptor>
<md:AssertionConsumerService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example.snowflakecomputing.com/fed/login" />
</md:SPSSODescriptor>
</md:EntityDescriptor>
For reference, the following table maps the XML metadata tags to the Snowflake SAML2 security integration properties.
XML Output |
SAML2 Security Integration Property |
---|---|
entityID |
SAML2_SNOWFLAKE_ISSUER_URL |
AuthnRequestsSigned |
SAML2_SIGN_REQUEST |
Signing Certificate |
SAML2_SNOWFLAKE_X509_CERT |
Encryption Certificate |
SAML2_SNOWFLAKE_X509_CERT |
Assertion Consumer Service URL |
SAML2_SNOWFLAKE_ACS_URL |
Force Re-authentication to Snowflake¶
Snowflake supports configuring your SAML2 security integration to require the authenticating user to re-authenticate to access Snowflake during the initial authentication SSO flow or when a current Snowflake session expires.
When enabling this feature in the Snowflake SAML2 security integration, Snowflake sets the SAML specification ForceAuthn
parameter to True
in
the outgoing SAML request from Snowflake to the IdP. Once the IdP receives the request with ForceAuthn
parameter set to True
, the IdP sends a
request to Snowflake which results in users being prompted to re-enter their authentication credentials (e.g. username, password) to access Snowflake.
This feature provides enhanced security through re-authentication. In addition, the re-authentication prompt allows users to input a different set of credentials than those used to initiate SSO to access Snowflake.
Important
Before implementing this feature, verify that your IdP supports switching identities during an SSO authentication flow.
If this feature is implemented in Snowflake and your IdP does not support switching identities during the initial SSO authentication flow, users might not be able to access Snowflake using the different set of credentials provided in the re-authentication prompt.
If you are creating a SAML2 security integration for the first time, ensure you set the SAML2_FORCE_AUTHN parameter.
To update an existing SAML2 security integration to support forced re-authentication to access Snowflake, follow the steps below:
Execute the ALTER SECURITY INTEGRATION command to update the security integration:
alter security integration my_idp set SAML2_FORCE_AUTHN = true;
Execute the DESCRIBE INTEGRATION command to view the updated security integration:
desc security integration my_idp;
Where:
SAML2_FORCE_AUTHN = TRUE | FALSE
The Boolean indicating whether users, during the initial authentication flow, are forced to authenticate again to access Snowflake. When set to
TRUE
, Snowflake sets theForceAuthn
SAML parameter toTRUE
in the outgoing request from Snowflake to the identity provider.
TRUE
forces users to authenticate again to access Snowflake, even if a valid session with the identity provider exists.
FALSE
does not force users to authenticate again to access Snowflake.Default:
FALSE
.
Custom Logout Endpoint¶
Snowflake supports defining a custom endpoint URL to redirect users to after logging out of Snowflake. The endpoint is set through the
SAML2_POST_LOGOUT_REDIRECT_URL
property in the SAML2 security integration.
Once enabled for users who access Snowflake through SAML SSO, clicking the Log Out button in the Classic Console results in Snowflake terminating the Snowflake session and redirecting users to the specified endpoint.
Important
This behavior does not apply to Snowsight.
Defining a logout endpoint provides administrators the option to control where users are redirected after logging out of Snowflake. For example, a custom endpoint could trigger a script to simultaneously terminate the IdP session. The advantage of this implementation is that both the Snowflake and IdP sessions are terminated, which forces users to re-authenticate against the IdP to access Snowflake.
If you are creating a SAML2 security integration for the first time, ensure you set the SAML2_POST_LOGOUT_REDIRECT_URL parameter.
If you created a SAML2 security integration without setting the SAML2_POST_LOGOUT_REDIRECT_URL parameter, execute the ALTER SECURITY INTEGRATION command to configure the custom logout endpoint:
alter security integration my_idp set SAML2_POST_LOGOUT_REDIRECT_URL = 'https://logout.example.com';
Manage Your SAML2 Security Integration¶
You can use an ALTER SECURITY INTEGRATION command to manage the SAML2 security integration. For example:
Upload an X.509 certificate as a string into an existing SAML2 security integration.
alter security integration my_idp set SAML2_SNOWFLAKE_X509_CERT = 'AX2bv...';
Overwrite the existing private key and self-signed certificate and generate a new private key and self-signed certificate.
alter security integration my_idp refresh SAML2_SNOWFLAKE_PRIVATE_KEY;
Enable signed requests.
alter security integration my_idp set SAML2_SIGN_REQUEST = true;
Specify the
NameID
format.alter security integration my_idp set SAML2_REQUESTED_NAMEID_FORMAT = 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified';
Set or unset forced re-authentication to Snowflake.
-- update an existing security integration to enable forced re-authentication alter security integration my_idp set SAML2_FORCE_AUTHN = true; -- unset forced re-authentication alter security integration my_idp unset SAML2_FORCE_AUTHN;
Specify the custom logout endpoint.
-- Update the endpoint URL alter security integration my_idp set SAML2_POST_LOGOUT_REDIRECT_URL = 'https://logout.example.com';
For more information, see ALTER SECURITY INTEGRATION.
Replicate the SSO Configuration¶
Snowflake supports replication and failover/failback of the SAML2 security integration from a source account to a target account.
For details, see Replication of Security Integrations & Network Policies Across Multiple Accounts.