Skip to content

SAML2SecurityIntegration

Snowflake Documentation | Snowcap CLI label: saml2_security_integration

A SAML2 security integration, which federates Snowflake authentication to an external identity provider (Okta, ADFS, or any SAML2 IdP). With one in place, clients can connect with authenticator = externalbrowser. Describe the IdP one of two ways: set metadata_url, which Snowflake supports for Okta and Microsoft Entra ID only, or set all four of saml2_issuer, saml2_sso_url, saml2_provider and saml2_x509_cert. The two are mutually exclusive. metadata_url is CREATE-only in snowcap: Snowflake reads the metadata once and reports the derived values, so editing the URL later produces no diff and no error, and the change has to be applied out of band with ALTER SECURITY INTEGRATION <name> SET METADATA_URL = '...'. Microsoft Entra ID uses saml2_provider: CUSTOM. Take saml2_issuer from the enterprise app's Microsoft Entra Identifier, saml2_sso_url from its Login URL, and saml2_x509_cert from the Base64 SAML signing certificate. Both URLs embed the tenant id, so pass them as vars rather than committing them. Snowflake matches the IdP's NameID to the user's login_name, so every federated user needs a login_name that matches what the IdP sends. To stop the browser from opening on every new connection, also set the ALLOW_ID_TOKEN account parameter to true, which lets the client cache the SSO token in the local OS keystore. Caching also depends on the driver: the Python connector caches on Linux from 5.0 on, earlier versions need the secure-local-storage extra. Creating the integration and setting ALLOW_ID_TOKEN both require ACCOUNTADMIN. saml2_x509_cert takes either the bare base64 body of the IdP signing certificate or a full PEM block; the PEM header, footer and whitespace are stripped, because that is how Snowflake stores it.

Examples

Python

sso_saml = SAML2SecurityIntegration(
    name="sso_saml",
    enabled=True,
    saml2_provider="OKTA",
    saml2_issuer="http://www.okta.com/exk1abcdefg",
    saml2_sso_url="https://example.okta.com/app/snowflake/exk1abcdefg/sso/saml",
    saml2_x509_cert="MIIDpDCCAoygAwIBAgIGAV2ka...",
    saml2_enable_sp_initiated=True,
    saml2_sp_initiated_login_page_label="Datacoves SSO",
)

YAML

# The IdP values identify your tenant and rotate independently of this config,
# so keep them out of the repo: SNOWCAP_VAR_SAML2_X509_CERT becomes
# {{ var.saml2_x509_cert }}. Declaring them here with no default makes a missing
# value fail the run before it reaches Snowflake.
vars:
  - name: saml2_issuer
    type: string
  - name: saml2_sso_url
    type: string
  - name: saml2_x509_cert
    type: string
security_integrations:
  - name: sso_saml
    type: SAML2
    enabled: true
    saml2_provider: OKTA
    saml2_issuer: "{{ var.saml2_issuer }}"
    saml2_sso_url: "{{ var.saml2_sso_url }}"
    saml2_x509_cert: "{{ var.saml2_x509_cert }}"
    saml2_enable_sp_initiated: true
    saml2_sp_initiated_login_page_label: Datacoves SSO

Fields

  • name (string, required) - The name of the security integration.
  • metadata_url (string) - The IdP metadata URL, in place of the four saml2_* IdP fields. Okta and Microsoft Entra ID only. Set at creation only.
  • saml2_issuer (string) - The EntityID or Issuer of the IdP. Required unless metadata_url is set, and rejected if it is.
  • saml2_sso_url (string) - The IdP SSO URL where Snowflake sends the SAML request. Required unless metadata_url is set, and rejected if it is.
  • saml2_provider (string or SAML2Provider) - The IdP vendor, one of 'OKTA', 'ADFS', or 'CUSTOM'. Required unless metadata_url is set, and rejected if it is.
  • saml2_x509_cert (string) - The IdP signing certificate, base64 encoded or as a PEM block. Required unless metadata_url is set, and rejected if it is.
  • enabled (bool) - Specifies if the security integration is enabled. Defaults to True.
  • saml2_enable_sp_initiated (bool) - Shows the IdP button on the Snowflake login page for SP-initiated login. Defaults to False.
  • saml2_sp_initiated_login_page_label (string) - The label of that button on the Snowflake login page.
  • saml2_snowflake_acs_url (string) - The Snowflake assertion consumer service URL the IdP posts to. Defaults to the account's own URL.
  • saml2_snowflake_issuer_url (string) - The Snowflake EntityID sent to the IdP. Defaults to the account's own URL.
  • saml2_force_authn (bool) - Forces the user to re-authenticate at the IdP on every login. Defaults to False.
  • saml2_requested_nameid_format (string) - The NameID format Snowflake requests from the IdP.
  • saml2_post_logout_redirect_url (string) - Where the user lands after logging out of Snowflake.
  • saml2_sign_request (bool) - Signs the SAML request Snowflake sends to the IdP. Defaults to False.
  • allowed_user_domains (list) - Email domains allowed to authenticate through this integration.
  • allowed_email_patterns (list) - Regular expressions for email addresses allowed to authenticate through this integration. A pattern containing a comma (a {2,10} quantifier, say) is read back split, so the plan never converges; avoid commas in patterns for now.
  • comment (string) - A comment about the security integration.