Skip to main content
This guide walks you through setting up Snowflake OAuth authentication for Gumloop. By following these steps, you’ll configure a secure OAuth integration that allows Gumloop to connect to your Snowflake account on behalf of your users.
Intended Audience: Snowflake administrators with ACCOUNTADMIN role or users with CREATE INTEGRATION privilege. This setup is performed once and enables OAuth authentication for your organization’s Snowflake connection.
This guide provides basic setup instructions for integrating Snowflake with Gumloop. For production environments and security best practices, please refer to the official Snowflake OAuth documentation to ensure your configuration meets your organization’s security requirements.

​
What This Guide Covers

This documentation will help you:
  1. Create a Snowflake OAuth Integration - Register Gumloop as a custom OAuth client in Snowflake
  2. Retrieve OAuth Credentials - Get the Client ID and Client Secret needed for Gumloop
  3. Configure Gumloop (Administrator) - Add the Snowflake OAuth Config to your workspace
  4. User Authentication - Connect individual user accounts with proper scopes
Once complete, your team will be able to authenticate Snowflake connections through OAuth in Gumloop.

​
Overview

Snowflake OAuth integration enables secure authentication between Gumloop and your Snowflake account. Instead of sharing static credentials, OAuth allows users to authorize Gumloop to access Snowflake on their behalf with automatic token refresh and better security controls.

​
Why Use Snowflake OAuth with Gumloop?

Enhanced Security

OAuth tokens are temporary and can be revoked, reducing the risk of credential exposure

Automatic Token Refresh

Refresh tokens keep your connection active without manual re-authentication

Centralized Control

Manage access and permissions directly in Snowflake

Audit Trail

Track OAuth authentication events in Snowflake’s audit logs

​
Prerequisites

Before you begin, ensure you have:
  • Snowflake Account Access - You need the ACCOUNTADMIN role or a role with CREATE INTEGRATION privilege
  • Snowflake Account URL - Your Snowflake account URL (e.g., https://myorg-account123.snowflakecomputing.com)
  • Gumloop Workspace - An active Gumloop workspace where you’ll add the credentials

​
Step 1: Create the Snowflake OAuth Integration

You’ll run SQL commands in Snowflake to create a custom OAuth integration for Gumloop.

​
1.1 Connect to Snowflake

  1. Log in to your Snowflake account
  2. Open a new SQL worksheet
  3. Ensure you’re using a role with sufficient privileges:
USE ROLE ACCOUNTADMIN;
If you don’t have the ACCOUNTADMIN role, ask your Snowflake administrator to either grant you this role temporarily or execute these commands on your behalf.

​
1.2 Create the OAuth Integration

Copy and execute the following SQL command to create the OAuth integration: 
CREATE OR REPLACE SECURITY INTEGRATION GUMLOOP
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://api.gumloop.com/auth/callback'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;
  • TYPE = OAUTH - Specifies this is an OAuth integration
  • ENABLED = TRUE - Activates the integration immediately
  • OAUTH_CLIENT = CUSTOM - Indicates this is a custom OAuth client (not a pre-built partner integration)
  • OAUTH_CLIENT_TYPE = ‘CONFIDENTIAL’ - Marks this as a confidential client that can securely store secrets
  • OAUTH_REDIRECT_URI - The Gumloop callback URL where users are redirected after authentication
  • OAUTH_ISSUE_REFRESH_TOKENS = TRUE - Enables automatic token refresh for persistent connections
  • OAUTH_REFRESH_TOKEN_VALIDITY = 7776000 - Sets refresh token validity to 90 days (7,776,000 seconds)
Important: Snowflake automatically adds certain administrative roles to the OAuth blocked roles list: ACCOUNTADMIN, ORGADMIN, SECURITYADMIN, and GLOBALORGADMIN. If you need to use these roles with OAuth, you must either:
  • Remove them from the blocked roles list (if your organization’s security policy allows), or
  • Switch to a different role that is not blocked
For more information, see the Blocking Specific Roles section below.
If you’re manually setting up an allowed scope list using OAUTH_ALLOWED_SCOPES, ensure you include refresh_token and any specific roles required. For example:
ALTER SECURITY INTEGRATION GUMLOOP 
  SET OAUTH_ALLOWED_SCOPES = ('refresh_token', 'session:role:YOUR_ROLE_NAME');
Refer to the Snowflake OAuth documentation for scope configuration details.

​
1.3 Verify the Integration

Confirm the integration was created successfully: 
SHOW SECURITY INTEGRATIONS LIKE 'GUMLOOP';
You should see GUMLOOP in the results.

​
1.4 View Integration Details

To see all configuration details: 
DESC SECURITY INTEGRATION GUMLOOP;
This displays all properties of your OAuth integration, including the OAuth endpoints.

​
Step 2: Retrieve OAuth Credentials

Now you need to get the Client ID and Client Secret that Gumloop will use to authenticate.

​
2.1 Get Client Credentials

Execute the following command: 
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('GUMLOOP');
This returns a JSON object containing your credentials. The output will look like: 
{
  "OAUTH_CLIENT_ID": "ABC123XYZ456...",
  "OAUTH_CLIENT_SECRET": "def789ghi012...",
  "OAUTH_CLIENT_SECRET_2": ""
}
Keep these credentials secure! Treat the Client ID and Client Secret like passwords. Do not share them publicly or commit them to version control.

​
2.2 Save the Credentials

Copy and save the following values from the JSON response:
  • OAUTH_CLIENT_ID - You’ll need this for Gumloop
  • OAUTH_CLIENT_SECRET - You’ll need this for Gumloop
Store these credentials in a secure password manager until you’re ready to add them to Gumloop.

​
Step 3: Configure Gumloop (Administrator Setup)

Now that you have your Snowflake OAuth credentials, you’ll add them to Gumloop as an administrator.

​
3.1 Add Snowflake OAuth Config to Gumloop

  1. Navigate to Gumloop Credentials Page
  2. Search for “Snowflake OAuth Config” in the credentials list
  3. Click Add Credential
  4. Enter the following information:
    • Client ID: The OAUTH_CLIENT_ID from Step 2.1
    • Client Secret: The OAUTH_CLIENT_SECRET from Step 2.1
  5. Save the configuration
This sets up the OAuth integration at the workspace level. Individual users will now be able to connect using this configuration.

​
Step 4: User Authentication

Once the administrator has completed Step 3, individual users can connect their Snowflake accounts.

​
4.1 Connect Your Snowflake Account

  1. Navigate to Gumloop Credentials Page
  2. Click Add Credential
  3. Select Snowflake from the list of integrations
  4. Choose OAuth as the authentication method
  5. Select Snowflake OAuth Config (the configuration added by your administrator)
  6. Enter the following information:
    • Workspace ID: Your Snowflake account identifier (e.g., myorg-account123)
    • Scopes: Space-separated list of OAuth scopes (see warning below)
Critical: Scopes ConfigurationIf you leave scopes empty or only include refresh_token, most Snowflake operations will fail. You must specify appropriate scopes for your use case.Minimum recommended scope:
refresh_token session:role:YOUR_ROLE_NAME
Replace YOUR_ROLE_NAME with your actual Snowflake role (e.g., PUBLIC, ANALYST, etc.). The role name is case-sensitive and must be in uppercase unless the role was created with quotes.Examples:
  • Basic access: refresh_token session:role:PUBLIC
  • Analyst role: refresh_token session:role:ANALYST
  • Custom role: refresh_token session:role:DATA_ENGINEER
For detailed scope configuration, refer to the Snowflake OAuth scope documentation.

​
4.2 Authorize the Connection

After entering your information:
  1. Click Connect or Authorize
  2. You’ll be redirected to Snowflake’s authorization page
  3. Log in with your Snowflake credentials
  4. Review the requested permissions and role
  5. Click Authorize to grant Gumloop access
  6. You’ll be redirected back to Gumloop with a successful connection

​
4.3 Verify Your Connection

To confirm your OAuth connection is working correctly:
  1. Go to Gumloop Credentials Page
  2. Search for Snowflake
  3. If the connection is successful, you should see your Snowflake username displayed instead of “Snowflake Account”
Snowflake OAuth verification showing username instead of account name
If you see your username listed (as shown in the image above), your OAuth connection is properly configured and ready to use!

​
Blocking Specific Roles

Snowflake automatically blocks certain administrative roles from being used with OAuth for security reasons. These blocked roles include:
  • ACCOUNTADMIN
  • ORGADMIN
  • SECURITYADMIN
  • GLOBALORGADMIN
These roles are blocked by default and cannot be removed from the block list without contacting Snowflake Support and obtaining approval from your security team.

​
Adding Additional Blocked Roles

To block additional custom roles from being used with OAuth: 
ALTER SECURITY INTEGRATION GUMLOOP 
  SET BLOCKED_ROLES_LIST = ('SYSADMIN', 'CUSTOM_ADMIN_ROLE');
If users need to access Snowflake with OAuth using a role that’s currently blocked, they have two options:
  1. Request removal from the blocked roles list (requires Snowflake Support approval)
  2. Switch to a different, non-blocked role that has the necessary permissions

​
Troubleshooting

​
”Invalid Client” Error

Problem: Getting an “invalid_client” error when connecting Solution:
  • Verify the Client ID and Client Secret are correct in the Snowflake OAuth Config
  • Check that the integration is enabled: DESC SECURITY INTEGRATION GUMLOOP;
  • Ensure the redirect URI matches exactly: https://api.gumloop.com/auth/callback

​
Most Operations Are Failing

Problem: Connected successfully but Snowflake operations return permission errors Solution: This usually means scopes are not configured correctly. Ensure you included both:
  • refresh_token scope for maintaining the connection
  • session:role:YOUR_ROLE_NAME scope for accessing Snowflake resources
Update your credential with proper scopes, for example: refresh_token session:role:PUBLIC

​
Role Access Issues

Problem: Users can’t access certain Snowflake resources or specific role Solution:
  • Verify the role name in your scope is spelled correctly and in uppercase
  • Check if the desired role is blocked: DESC SECURITY INTEGRATION GUMLOOP;
  • Ensure the user has been granted the role in Snowflake: SHOW GRANTS TO USER your_username;
  • If using an administrative role (ACCOUNTADMIN, SECURITYADMIN, etc.), these are blocked by default

​
Username Not Showing in Gumloop

Problem: Still seeing “Snowflake Account” instead of username in credentials page Solution:
  • The OAuth authorization may not have completed successfully
  • Try removing the credential and re-connecting
  • Verify scopes are configured correctly with both refresh_token and a valid role
  • Check Snowflake audit logs to confirm the OAuth authorization was successful

​
Tokens Expiring Too Quickly

Problem: Users need to re-authenticate frequently Solution: Increase the refresh token validity in Snowflake: 
ALTER SECURITY INTEGRATION GUMLOOP 
  SET OAUTH_REFRESH_TOKEN_VALIDITY = 15552000;  -- 180 days

​
Security Best Practices

Regular Credential Rotation

Periodically rotate your OAuth client secrets to maintain security

Principle of Least Privilege

Grant users only the minimum Snowflake roles needed for their work

Monitor OAuth Activity

Regularly review OAuth token usage in Snowflake audit logs

Network Policies

Configure Snowflake network policies to restrict OAuth access by IP
For comprehensive security guidance and advanced configuration options, refer to the official Snowflake OAuth documentation.

​
Additional Resources

​
Need Help?

If you encounter issues not covered in this guide:
  1. Check the Snowflake OAuth documentation for detailed technical information
  2. Contact your Snowflake administrator for account-specific issues
  3. Reach out to Gumloop Support for integration assistance