Purpose

This guide explains the one-time setup required to enable this integration. It explains how to set up Entra Authentication, create a Database and Table within Snowflake, create a Security Integration for the Entra Authentication in Snowflake, create a User and assign that User a Role and Grant to the Security Integration so the Authenticx Snowflake API Connector can:

Authenticate to Snowflake with OAuth credentials
Insert or update a row per conversation on a scoped table within Snowflake as conversations are processed within Authenticx

This is a server to server integration. It does not use an interactive browser login.

Prerequisites

You will need:

Azure admin access (if you choose to provision your own credentials)
Snowflake admin access
Field mapping corresponding to the data you expect to receive from Authenticx

AZURE

Based on your company's security requirements or preference, Authenticx can either provision Azure Entra credentials for this project OR use credentials provisioned by you. In either scenario, your team retains the ability to disable access at any time and control what tables and levels of access Authenticx has within Snowflake.

Step 1: Create an Entra App Registration for the Snowflake Client and second Entra App Registration for the Client Id / Client Secret Creation

Step 2: Credential Verification

--If the above Entra Application Registration was successful, a token should be able be fetched using the curl request below : 

curl -X POST "https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<OAUTH_CLIENT_ID>" \
  -d "client_secret=<OAUTH_CLIENT_SECRET>" \
  -d "scope=<SNOWFLAKE_APPLICATION_ID_URI>/.default"

SNOWFLAKE

Step 1: Create or Identify the Targeted Database, Schema, and Table

In Snowflake, create or confirm the targeted Database, Schema, and Table that will hold the data Authenticx pushes to Snowflake. The list of data you expect to receive from Authenticx should inform the columns on the Table generation.

Recommended columns:

Authenticx Conversation Id
Client Call Id

Example Script:

-- Create a database for the data to be persisted to
CREATE DATABASE drugco_testing;

-- Create a table within this database with appropriate columns based on the field mapping 
CREATE TABLE IF NOT EXISTS AUTHENTICX_OUTPUTS (
    ACX_CONVERSATION_ID    STRING,    
    CLIENT_CALL_ID         STRING NOT NULL
    CALL_TIMESTAMP         TIMESTAMP_NTZ,
    CALL_AGENT_NAME        STRING,
    METADATA_ABC           VARIANT,

    CLASSIFIER_123         VARIANT,
    EDDY_EFFECT            VARIANT,
    SENTIMENT              VARIANT,
    CALL_DRIVERS           STRING,
    CALL_THEME             VARIANT,
    OVERALL_QUALITY_SCORE  VARIANT,

    CREATED_AT          TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),
    UPDATED_AT          TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP()
);

-- Optional Verification - can a row can be added to this table ?
INSERT INTO AUTHENTICX_OUTPUTS ("CLIENT_CALL_ID") VALUES ('test-snowflake-call-id');

-- Optional Verification - can I see the row that was added to this table?
select * from "AUTHENTICX_OUTPUTS"

Step 2: Create or Confirm the Security Integration

In Snowflake, create the security integration that will be pinned to the Azure Entra credentials created in the Azure section. If Authenticx provisioned the Entra credentials, we will provide the Tenant and Snowflake Application Id URI to you.

Example Script:

-- Check what security integrations exist
SHOW SECURITY INTEGRATIONS;

-- Create security integration, pinned to azure entra id implementation created above
CREATE OR REPLACE SECURITY INTEGRATION external_oauth_azure
  TYPE = external_oauth
  ENABLED = true
  EXTERNAL_OAUTH_TYPE = azure
  EXTERNAL_OAUTH_ISSUER = 'https://sts.windows.net/<tenant>/'
  EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys'
  EXTERNAL_OAUTH_AUDIENCE_LIST = ('<SNOWFLAKE_APPLICATION_ID_URI>')
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name'
  EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';

-- Optional Verification - ensure security integration exists
SHOW SECURITY INTEGRATIONS

-- Optional Verification - ensure security integration created appropriately
DESCRIBE SECURITY INTEGRATION external_oauth_azure;

-- Verification - Run the CURL command above in the AZURE section and paste the generated token into this command. If the Entra credentials are pined properly to the security integration, this command should Pass
SELECT SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN('eyJ...');

Step 3: Create the Integration User

In Snowflake, create the 'user' that the Authenticx connector will authenticate as. Please note this is a server to server integration and does not use an interactive browser login.

Example Script:

-- Create user using the same GUID as the above Security Integration
CREATE USER svc_azure_oauth LOGIN_NAME = 'GUID’;

-- Optional Verification - ensure user exists 
SHOW USERS;

Step 4: Create the Integration Role and assign it to the User

In Snowflake, create a role to assign to the user. This role should have usage access to the warehouse the table is within.

Example Script:

-- Create role
CREATE ROLE app_readwrite;
GRANT USAGE ON WAREHOUSE TESTING_WH_DRUGCO TO ROLE app_readwrite;

-- Grant newly created role permissions to the User
GRANT ROLE app_readwrite TO USER svc_azure_oauth;
ALTER USER svc_azure_oauth SET DEFAULT_ROLE = app_readwrite;

-- Verification - check user has appropriate grants to the app_readwrite role
SHOW GRANTS TO USER svc_azure_oauth;

-- Grant read-level structural access
GRANT USAGE ON DATABASE DRUGCO_TESTING TO ROLE app_readwrite;
GRANT USAGE ON SCHEMA DRUGCO_TESTING.public TO ROLE app_readwrite;

Step 5: Grant Read-Level Structural Access to the Integration Role

In Snowflake, create a role to assign to the user. This role should have usage access to the warehouse the table is within.

Example Script:


-- Grant read-level structural access
GRANT USAGE ON DATABASE DRUGCO_TESTING TO ROLE app_readwrite;
GRANT USAGE ON SCHEMA DRUGCO_TESTING.public TO ROLE app_readwrite;

-- The next steps are OPTIONAL or can be modified depending on the use case

-- Grant read-write on ALL EXISTING tables in the schema
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA DRUGCO_TESTING.public TO ROLE app_readwrite;

-- Grant read-write on ALL FUTURE tables created in the schema 
GRANT SELECT, INSERT, UPDATE, DELETE ON FUTURE TABLES IN SCHEMA DRUGCO_TESTING.public TO ROLE app_readwrite;

Customer Handoff Checklist

Before go live, provide the following to your Authenticx onboarding team:

Azure Entra Client Id (If provisioning your own)
Azure Entra Client Secret (If provisioning your own)
Azure Directory (tenant) Id (If provisioning your own)
Azure Application Id URI (If provisioning your own)
Snowflake role name
Snowflake UserId
Snowflake Account Identifier
Snowflake Warehouse, Database, Schema, and Table Name
All column names in the targeted table
Whether intended behavior is INSERT only or INSERT / MERGE