Advanced SAML SSO Features

This topic describes how to configure and use advanced SAML SSO features in Snowflake.

In this Topic:

Overview

The SAML2 security integration is the foundation for advanced SAML SSO features in Snowflake.

After configuring a SAML2 security integration, you can use the security integration to manage your SAML SSO configuration and encrypt SAML assertions.

Migrating to a SAML2 Security Integration

The SAML2 security integration specifies the IdP information in Snowflake and is meant to replace the information contained in the SAML_IDENTITY_PROVIDER parameter.

There are two options to specify the IdP in Snowflake:

  1. Use a system function to migrate existing IdP information to a security integration.

  2. Create or replace a security integration to contain the IdP information.

Option 1 is the recommended pathway if you already have an IdP configured to use federated authentication to Snowflake based on the SAML_IDENTITY_PROVIDER parameter.

Option 2 is the recommended pathway if your account does not have the SAML_IDENTITY_PROVIDER parameter.

Option 1: Use a System Function

You can migrate your existing IdP configuration from the SAML_IDENTITY_PROVIDER parameter to a security integration using the system function SYSTEM$MIGRATE_SAML_IDP_REGISTRATION.

After running this system function, you should not longer use the SAML_IDENTITY_PROVIDER parameter for SAML SSO configuration and management. Instead, manage your SAML2 security integration as shown in Managing your SAML2 Security Integration.

Note

If desired, prior to executing the system function, you can verify the SAML_IDENTITY_PROVIDER configuration by executing the following statement:

show parameters like 'SAML_IDENTITY_PROVIDER' in account;

Option 2: Create or Replace a Security Integration

If you do not have an existing IdP configured in Snowflake to use federated authentication and would like to configure your IdP in Snowflake for federated authentication, create a security integration where TYPE = SAML2 using CREATE SECURITY INTEGRATION.

If you have an existing security integration where TYPE = SAML2 and you need to update one or more parameters, execute an ALTER SECURITY INTEGRATION statement or replace the entire security integration with a CREATE OR REPLACE SECURITY INTEGRATION statement.

Encrypting SAML Assertions

Snowflake allows your organization’s IdP to send encrypted SAML2 assertions to Snowflake after the user successfully authenticates against the IdP.

Encrypted SAML2 assertions facilitate secure information transfer while users access Snowflake through federated SSO. Customers can encrypt their SAML assertions with Snowflake’s public certificate. Upon 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.

Encrypted SAML assertions are integrated into the SAML2 security integration. You can use an existing SAML2 security integration or create a new SAML2 security integration.

The general procedure to configure and use encrypted SAML assertions is as follows:

  1. Create a SAML2 Security Integration.

  2. Export the public certificate from Snowflake in PEM format.

  3. Import the public certificate into your SAML IdP.

  4. Connect to Snowflake.

Encrypted SAML Assertions Procedure

Follow these steps to configure encrypted SAML assertions and connect to Snowflake.

Step 1: Create or Migrate to a SAML2 Security Integration

If you have an existing SAML setup in Snowflake and would like to use this feature, you can migrate to a SAML2 security integration by executing this SQL statement. For more information on this system function, see SYSTEM$MIGRATE_SAML_IDP_REGISTRATION.

select system$migrate_saml_idp_registration('<integration_name>', '<issuer>');

Otherwise, create a SAML2 security integration by executing the following SQL statement. For more information, see CREATE SECURITY INTEGRATION.

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_sp_initiated_login_page_label = 'my_idp'
    saml2_enable_sp_initiated = false;

Step 2: Export the Public Certificate from Snowflake

To export the public certificate from Snowflake, complete these steps.

  1. Execute the following SQL statement on the SAML2 integration to obtain the SAML2_SNOWFLAKE_X509_CERT value (in row 7).

    desc security integration my_idp;
    
  2. Save the value in PEM format. Be sure to include the BEGIN CERTIFICATE and END CERTIFICATE delimiters. The following is a representative example of a truncated certificate in PEM format:

    -----BEGIN CERTIFICATE-----
    MIICrTCCAZWgAwIBAgIJAOF6EPk93wjlMA0GCSqGSIb3DQEBCwUAMBYxFDASBgNV
    BAMMC1RFU1RBQ0NPVU5UMB4XDTIwMDE....
    -----END CERTIFICATE-----
    

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 these steps.

  1. Generate a Certificate Signing Request (CSR) from Snowflake using the system function SYSTEM$GENERATE_SAML_CSR.

  2. Provide the CSR to the CA of your choice so that the certificate can be issued.

  3. Upload the Base64-encoded certificate into the SAML integration using the following ALTER statement, without the BEGIN CERTIFICATE and END CERTIFICATE delimiters.

    alter security integration my_idp set SAML2_SNOWFLAKE_X509_CERT = 'AX2bv...';
    

You can then upload the certificate for that private key using the CSR generated by the function into Snowflake.

Step 3: 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).

Step 4: Connect to Snowflake

After configuring your IdP, complete the following tasks.

  • Verify your IdP setup.

  • Create users and assign roles in Snowflake.

  • Determine whether users will connect to Snowflake through IdP-initiated or SP-initiated SSO.

    • For IdP-initiated SSO, inform your users on how to access Snowflake (e.g. access internal portal).

    • For SP-initiated SSO (i.e. users access Snowflake and then are redirected to the customer IdP), enable Snowflake-initiated SSO by setting the account parameter SSO_LOGIN_PAGE to true. As a user with the ACCOUNTADMIN role, execute the following statements.

      use role accountadmin;
      
      alter account set SSO_LOGIN_PAGE = true;
      
  • Access Snowflake as shown in Managing/Using Federated Authentication.

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.

Signed SAML requests are integrated into the SAML2 security integration. You can use an existing security integration of type = saml2 or create a new security integration to use signed SAML requests.

If your IdP supports accepting signed SAML requests, the general procedure to configure and use signed SAML requests is:

  1. Create or update the security integration.

  2. Update your SAML2 security integration.

  3. Configure your IdP to accept signed SAML requests.

  4. Connect to Snowflake.

Signed SAML Requests Procedure

Follow these steps to configure signed SAML requests and connect to Snowflake.

Step 1: Create or Migrate to a SAML2 Security Integration

If you have an existing SAML setup in Snowflake and would like to use this feature, you can migrate to a SAML2 security integration by executing this SQL statement. For more information on this system function, see SYSTEM$MIGRATE_SAML_IDP_REGISTRATION.

select system$migrate_saml_idp_registration('<integration_name>', '<issuer>');

Otherwise, create a SAML2 security integration by executing the following SQL statement. For more information, see CREATE SECURITY INTEGRATION.

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_sp_initiated_login_page_label = 'my_idp'
    saml2_enable_sp_initiated = false;

Step 2: Update the SAML2 Security Integration

To use signed requests in Snowflake, you must do the following in Snowflake:

  • Enable the security integration to sign requests.

  • Save the value of the saml2_snowflake_x509_cert for use in the next step.

As an account administrator (i.e. a user with ACCOUNTADMIN role), execute the following statements:

-- update the security integration

alter security integration my_idp set SAML2_SIGN_REQUEST = true;

-- view the updated security integration, save the certificate value in row 7.

desc security integration my_idp;

Step 3: 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.

Step 4: Connect to Snowflake

After configuring your IdP, complete the following tasks.

  • Verify your IdP setup.

  • Create users and assign roles in Snowflake.

  • Determine whether users will connect to Snowflake through IdP-initiated or SP-initiated SSO.

    • For IdP-initiated SSO, inform your users on how to access Snowflake (e.g. access internal portal).

    • For SP-initiated SSO (i.e. users access Snowflake and then are redirected to the customer IdP), enable Snowflake-initiated SSO by setting the account parameter SSO_LOGIN_PAGE to true. As a user with the ACCOUNTADMIN role, execute the following statements.

      use role accountadmin;
      
      alter account set SSO_LOGIN_PAGE = true;
      
  • Access Snowflake as shown in Managing/Using Federated Authentication.

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

If your IdP supports specifying the SAML NameID in a SAML assertion, the general procedure to configure and specify the NameID is:

  1. Create or migrate to a SAML2 security integration in Snowflake.

  2. Update your security integration to support NameId.

  3. Configure your IdP to specify the SAML NameID format.

  4. Connect to Snowflake.

SAML NameID Configuration Procedure

Follow these steps to configure the SAML NameID format and connect to Snowflake.

Step 1: Create or Migrate to a SAML2 Security Integration

If you have an existing SAML setup in Snowflake and would like to use this feature, you can migrate to a SAML2 security integration by executing this SQL statement. For more information on this system function, see SYSTEM$MIGRATE_SAML_IDP_REGISTRATION.

select system$migrate_saml_idp_registration('<integration_name>', '<issuer>');

Otherwise, create a SAML2 security integration by executing the following SQL statement. For more information, see CREATE SECURITY INTEGRATION.

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_sp_initiated_login_page_label = 'my_idp'
    saml2_enable_sp_initiated = false;

Step 2: Update the SAML2 Security Integration for NameID

To specify the SAML NameID format, execute the following statements as an account administrator (i.e. a user with ACCOUNTADMIN role):

-- update the security integration

alter security integration my_idp set SAML2_REQUESTED_NAMEID_FORMAT = '<string_literal>';

-- view the updated security integration

desc security integration my_idp;

Step 3: 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.

Step 4: Connect to Snowflake

After configuring your IdP, complete the following tasks.

  • Verify your IdP setup.

  • Create users and assign roles in Snowflake.

  • Determine whether users will connect to Snowflake through IdP-initiated or SP-initiated SSO.

    • For IdP-initiated SSO, inform your users on how to access Snowflake (e.g. access internal portal).

    • For SP-initiated SSO (i.e. users access Snowflake and then are redirected to the customer IdP), enable Snowflake-initiated SSO by setting the account parameter SSO_LOGIN_PAGE to true. As a user with the ACCOUNTADMIN role, execute the following statements.

      use role accountadmin;
      
      alter account set SSO_LOGIN_PAGE = true;
      
  • Access Snowflake as shown in Managing/Using Federated Authentication.

Exporting 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 identity provider.

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

Managing Your SAML2 Security Integration

You can use an ALTER 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';
    

For more information, see ALTER SECURITY INTEGRATION.