Skip to content

Latest commit

 

History

History
111 lines (84 loc) · 5 KB

snowsight_sso_saml.md

File metadata and controls

111 lines (84 loc) · 5 KB
Raw

SSO SAML 2.0 Federated Authentication for Snowsight

Important

This is a work in progress document.

Many companies use SAML2 (also known as Federated Login) for authentication, allowing users to sign into various services using a centralised identity provider (IdP) such as Google, Azure, etc - SAML2 are usually locked behind enterprise pricing.

You can use whatever authentication provider you like - see the Overview of federated authentication and SSO documentation. Onelogin has a great WTF is SAML page.

Tip

If testing authentication on a personal/trial account, there are some great FREE hosted options out there now, such as Auth0 (7500 active users on their free plan, more than enough for testing, not affiliated, no referral yada yada), there are also many great self-hosted options as well.

Important

Create a test account when testing, so you don't lock out your main account! YOU ONLY GET A SINGLE EXTERNAL AUTH PROVIDER

SSO Setup Instructions

SSO Tips

Snowsight UI SSO Authentication Workflow Summary

  1. User visits https://{ACCOUNTNAME}.{REGION}.snowflakecomputing.com
  2. They click Sign in using <AUTHPROVIDER> (the name is whatever you set) Login with SSO
  3. They are redirected off to Authenticate through the IdP. Alt text
  4. Once they have authenticated through the IdP, they are redirected back to /fed/login.
  5. Authentication complete, they are logged in.

SSO Authentication Breakdown

Important

These instructions assume that you have correctly configured SSO/SAML 2.0, and everything is working as expected, and you can login as per above.

Important

Snowflake requires a local webserver, as the user needs to be redirected back to this for the token to be sent. The way the Snowflake drivers do it is they create a local webserver, listen on localhost, then close the server when authentication is complete.

Tip

I have created an example implementation for Python 3.x at snowsight_sso.py, which requires no external dependencies and should be helpful to showcase how the SSO works. It will create a local webserver, which will then have verbose logging turned on.

Login Request

Endpoint

/session/v1/login-request?__uiAppName=Login

Method

POST

Headers

  • Content-Type: application/json

Request Body

{
  "data": {
    "CLIENT_APP_ID": "SnowflakeSQLAlchemy",
    "CLIENT_APP_VERSION": "1.5.1",
    "SVN_REVISION": null,
    "ACCOUNT_NAME": "<ACCOUNT_NAME>",
    "LOGIN_NAME": "<EMAIL_ADDRESS>",
    "AUTHENTICATOR": "EXTERNALBROWSER",
    "BROWSER_MODE_REDIRECT_PORT": "56981"
  }
}

Snowflake UI is this.

{
	"data": {
		"ACCOUNT_NAME": "<ACCOUNT_NAME>",
		"REAUTHENTICATION_TYPE": "FEDERATED",
		"CLIENT_APP_ID": "Snowflake UI",
		"CLIENT_APP_VERSION": 20231228094509
	}
}
Request Notes
  1. ACCOUNT_NAME is your actual account name, without the region, as you're authenticating against the endpoint already.
  2. REAUTHENTICATION_TYPE is FEDERATED, which impies it's SSO.
  3. CLIENT_APP_ID - When set to Snowflake UI, a redirectURI is returned in the JSON. You'll need this when authenticating to Snowsight. Otherwise, if you pass any other value, the endpoint returns a masterToken/token.
  4. CLIENT_APP_VERSION doesn't really matter, it seems it's just meta information as of 2023-12.

Response

{
  "data": {
    "nextAction": "FED_SP_AUTH",
    "redirectUrl": "https://example.com",
    "authnMethod": "FEDERATED"
  },
  "code": "390137",
  "message": "Federated authentication request URL is generated.",
  "success": false,
  "headers": null
}
  1. code is the return code, 390137 means FED_REAUTH - Federated authentication request URL is generated. (see Federated authentication and SSO troubleshooting.
  2. redirectURI is where you will be redirected to.