Fortanix Data Security Manager-Accelerator Webservice with Snowflake

1.0 Introduction

Welcome to the Fortanix Data Security Manager (DSM) - Accelerator Webservice with Snowflake Integration Guide. This article illustrates the procedures to integrate the Fortanix DSM-Accelerator Webservice with Snowflake.

2.0 Integration Steps

The data format for both input and output data regarding tokenization and detokenization is uniform. The data payload sent to the DSM-Accelerator Webservice for tokenization or detokenization must follow the following structure:

Data Format for Tokenization:

{
  // Comma-delimited list of Key Names
  "keys": String,
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

Data Format for Detokenization:

{
  // Comma-delimited list of Key IDs
  "keys": String,
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

Following the tokenization process, the output data will maintain a structure closely resembling that of the input, except for the keys field:

{
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

It is crucial to note that the order of the data rows remains unchanged.

2.2 Calling the API

To initiate the APIs, a POST HTTP request must be made to the respective endpoints:

  • For tokenization: <DSMA-WS-URL>/crypto/v1/snowflake_tokenize
  • For detokenization: <DSMA-WS-URL>/crypto/v1/snowflake_detokenize

For example, consider the following input provided to the tokenization endpoint:

{
    "keys": "keyname1, keyname2",
    "data": [ [ 1, "john@gmail.com", "374245455400126" ], [ 5, "harry@gmail.com", "378282246310005" ] ]
}

This input will reflect the following output:

{
    "data": [ [ 1, [ "uz87@lAUlp.KPg", "355347704783659" ] ], [ 5, [ "Ni0BE@w89JR.s9b", "186322926918719" ] ] ]
}

For example, consider the following input provided to the detokenization endpoint:

{
    "keys": "e9d51a2f-0d7a-42c0-9c51-24107f957464,822000bc-4f12-4007-b2d0-226726d78f55",
    "data": [ [ 1, [ "uz87@lAUlp.KPg", "355347704783659" ] ], [ 5, [ "Ni0BE@w89JR.s9b", "186322926918719" ] ] ]
}

This input will reflect the following output:

{
    "data": [ [ 1, "john@gmail.com", "374245455400126" ], [ 5, "harry@gmail.com", "378282246310005" ] ]
}

2.3 Create and Test AWS API Gateway

To integrate AWS API Gateway with Lambda which is deployed with DSM-Accelerator Webservice, create a REST API with public or private endpoints for /tokenize and /detokenize.

NOTE
POST method is required for both resources.

2.4 Integration Request Configuration

For each resource method, set up Integration Request with the following parameters:

  • Integration type: HTTP
  • Method type: POST
  • Endpoint URL: Point this to your DSM-Accelerator Function URL. For example, if DSM-Accelerator is deployed on AWS Lambda, then:
    • For tokenization: https://<url-id>.lambda-url.<region>.on.aws/crypto/v1/snowflake_tokenize
    • For detokenization: https://<url-id>.lambda-url.<region>.on.aws/crypto/v1/snowflake_detokenize
    To setup the Fortanix DSM-Accelerator on AWS Lambda, refer to the User’s Guide: Deploying Fortanix Data Security Manager – Accelerator Webservice on AWS Lambda.
  • Content handling: Passthrough
  • HTTP Headers: Add an “Authorization” header and leave the value empty as Snowflake sends it through an External Function custom header.
    image-20231110-094650.png Figure 1: Add Authorization

2.5 Mapping Template Configuration

2.5.1 Tokenization

Click Add mapping template and configure as follows:

  • Content-Type: application/json
  • Request body passthrough: Never
  • Template:
    #set($inputRoot = $input.path('$'))
    #set($apikey = "Basic $input.params('sf-custom-api-key')")
    #set($context.requestOverride.header.Authorization = $apikey)
    #set($context.requestOverride.header.sf-custom-api-key = "")
    #set($context.requestOverride.header.sf-custom-key-names = "")
    {
    "keys":"$input.params('sf-custom-key-names')",
    "data": $input.json('$.data')
    }
    
NOTE
Snowflake External Function sends FORTANIX_DSM_API_KEY in its custom header, mapped to a Basic Authentication header. Similarly, Fortanix DSM tokenization key names will be mapped from another Snowflake custom header to the integration request body.

2.5.2 Detokenization

Click "Add mapping template" and configure as follows:

  • Content-Type: application/json
  • Request body passthrough: Never
  • Template:
    #set($inputRoot = $input.path('$'))
    #set($apikey = "Basic $input.params('sf-custom-api-key')")
    #set($context.requestOverride.header.Authorization = $apikey)
    #set($context.requestOverride.header.sf-custom-api-key = "")
    #set($context.requestOverride.header.sf-custom-key-ids = "")
    {
    "keys":"$input.params('sf-custom-key-ids')",
    "data": $input.json('$.data')
    }
    
NOTE
Snowflake External Function sends FORTANIX_DSM_API_KEY in its custom header, mapped to a Basic Authentication header. Similarly, Fortanix DSM tokenization key IDs will be mapped from another Snowflake custom header to the integration request body.

2.6 Test AWS Gateway

Test the AWS API Gateway with the following input:

  • Resource: /tokenize
  • Query String: None or leave blank.
  • Headers:
    Accept: application/json
    sf-custom-api-key: <<FORTANIX_DSM_API_KEY>>
    sf-custom-key-names: <<KEY_NAME_1,KEY_NAME_2,KEY_NAME_3,KEY_NAME_X,,,>>
  • Request Body:
    {    "data": [
            [
                1,
                "174008549993007"
            ]
        ]}
    

    The highlighted box in the figure refers to the key name as “Credit_Card_Token” is used for tokenization.

    image (3).png
    Figure 2: Configure Test Method
  • Output:
    • In the Response Body, you can observe the tokenization output:
      Tokeniz_output_with_key_name.png
      Figure 3: Finalize the API Gateway Integration
      The highlighted box in the following figure refers to the key ID as for example, <ac00221c-8b04-4eed-8191-060bafcda40d> is used for detokenization.
      Detokenization_with_keyID.png
      Figure 4: Finalize the API Gateway Integration
    • In the Response Body, you can observe the detokenization output which matches the original data.
      Detokenization_output_with_Kid.png
      Figure 5: Finalize the API Gateway Integration

2.7 Finalize the API Gateway Integration

Perform the following steps to complete the API Gateway integration:

  1. Create an AWS IAM role that Snowflake will assume for execution.
  2. Deploy the proxy service on a demo stage and note the public or private URI:

To know the steps for setting up the Snowflake API integration and external functions, refer to Using Data Security Manager with Snowflake documentation.

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful