Skip to main content

Authentication

warning

If you are trying to authenticate as a user, please refer to this guide instead.

This guide will go through the authentication mechanisms for service principal accounts.

Snowflake Authentication​

tip

Applicable if you are using the direct Snowflake connection.

If you are using the Snowflake SDKs, the SDKs will implement the authentication mechanism - follow the documentation of the respective SDKs' API.

However, if you are using the Snowflake REST API, you can follow Snowflake's documentation.

DataHive Keypair Authentication​

tip

Applicable if you are using DataHive Web API.

Authenticate your Service Principal Account by generating a JWT (JSON Web Token) signed with your account's private key.

info

We have a sample script here which implements the steps to generate the JWT token.

In the Python script, the method for generating JWT token can be found in api_service.py, in _generate_keypair_token method.

Alternatively, you can implement your own JWT generator by following the steps below:

  1. Generate the public_key_fingerprint, a SHA-256 hash, of the public key for the service princiapl account. Prefix the fingerprint with SHA256:.

    • For example: SHA256:<hash>

  2. Generate a JSON Web Token (JWT) with the following fields in the payload:

FieldDescriptionExample
iss
Issuer of the JWT. Set it to the following value:
GOVTECH-DATAHIVE-STG.<user_id_in_uppercase>.SHA256:<public_key_fingerprint>
where:
  1. user_id_in_uppercase is the ID of the service principal account in uppercase.
  2. public_key_fingerprint is the fingerprint that you generated in the step 1. Ensure that the fingerprint is used as is, based on what is generated.
The User ID can be found here: User ID		GOVTECH-DATAHIVE-STG.65180D27-22B5-4635-B461-51D7E3017832.SHA256:<public_key_fingerprint>
sub
Subject for the JWT. Set it to the following value:
GOVTECH-DATAHIVE-STG.<user_id_in_uppercase>
where:
  1. user_id_in_uppercase is the ID of the service principal account in uppercase.
GOVTECH-DATAHIVE-STG.65180D27-22B5-4635-B461-51D7E3017832
iatIssue time for the JWT in UTC. Set the value to the current time value as seconds.1615370644
expExpiration time for the JWT in UTC (typically +60 min of iat). You can specify the value as seconds.1615374184

  1. Sign the claims with the Service Principal's private key, which will produce the JWT token required for authentication.

  2. In each API request that you send, set the following headers:

    • Authorization: Bearer <JWT>

DataHive Gateway Key​

tip

Applicable if you are using DataHive Synchronous API (Enhanced).

This is required in addition to the keypair authentication described above.

When a Synchronous API (Enhanced) is provisioned to your Service Principal Account, you will be provided with the Gateway key required to access the Synchronous API.

To authenticate successfully, include the following headers:

  • Authorization: Bearer <JWT>
  • DATAHIVE-GATEWAY-KEY: <Gateway Key>