Plugin - Token translation: SlashID to internal

This plugin can map SlashID token to your internal token format.

Example usage

Please see Translate SlashID to legacy tokens.

Configuring Gate

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=token-translation-downgrade
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_MINT_TOKEN_ENDPOINT=<Token minting endpoint>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_RETRIEVE_HANDLES=<Send handles to minting endpoint>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_ORG_ID=<SlashID Org ID>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_API_KEY=<SlashID API key>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_SLASHID_BASE_URL=<SlashID base URL>

In Environment variables configuration, <PLUGIN NUMBER> defined plugin execution order.

HCL

gate = {
    plugins = [
        // ...
        {
            type          = "token-translation-downgrade"
            parameters = {
                mint_token_endpoint = "<Token minting endpoint>"
                retrieve_handles    = <Send handles to minting endpoint>
                slashid_org_id      = "<SlashID Org ID>"
                slashid_api_key     = "<SlashID API key>"
                slashid_base_url    = "<SlashID base URL>"
            }
        }
        // ...
    ]
}

JSON

{
  "gate": {
    "plugins": [
      // ...
      {
        "type": "token-translation-downgrade",
        "parameters": {
          "mint_token_endpoint": "<Token minting endpoint>",
          "retrieve_handles": <Send handles to minting endpoint>,
          "slashid_org_id": "<SlashID Org ID>",
          "slashid_api_key": "<SlashID API key>",
          "slashid_base_url": "<SlashID base URL>"
        }
      }
      // ...
    ]
  }
}

TOML

[[gate.plugins]]
type = "token-translation-downgrade"
parameters.mint_token_endpoint = "<Token minting endpoint>"
parameters.retrieve_handles = <Send handles to minting endpoint>
parameters.slashid_org_id = "<SlashID Org ID>"
parameters.slashid_api_key = "<SlashID API key>"
parameters.slashid_base_url = "<SlashID base URL>"

YAML

gate:
  plugins:
    // ...
    - type: token-translation-downgrade
      parameters:
        mint_token_endpoint: <Token minting endpoint>
        retrieve_handles: <Send handles to minting endpoint>
        slashid_org_id: <SlashID Org ID>
        slashid_api_key: <SlashID API key>
        slashid_base_url: <SlashID base URL>
    // ...

where:

• <Token minting endpoint> URL of the endpoint that generates the internal token
• <Send handles to minting endpoint> a boolean indicating whether to fetch handles for the SlashID user and include them in the request to the token minting endpoint
• <SlashID Org ID> your SlashID organisation ID
• <SlashID API key> your SlashID API key
• <SlashID base URL> base URL of SlashID servers. By default, https://api.slashid.com.

To learn more about configuring Gate, please visit configuration page and plugins section.

info

Order of plugins in configuration determines their execution order.

Disabling plugin for specific URLs

You can enable or disable this plugin for specific URLs by using the enabled option in the URLs configuration.

Environment variables

GATE_URLS_0_PATTERN=svc-example.com/*
GATE_URLS_0_TARGET=http://example:8080

GATE_URLS_1_PATTERN=svc-another-example.com/
GATE_URLS_1_TARGET=https://another-example:8080

HCL

gate = {
  urls = [
    {
      pattern = "svc-example.com/*"
      target  = "http://example:8080"
    },
    {
      pattern = "svc-another-example.com/"
      target  = "https://another-example:8080"
    }
  ]

  // ...
}

JSON

{
  "gate": {
    "urls": [
      {
        "pattern": "svc-example.com/*",
        "target": "http://example:8080",
      },
      {
        "pattern": "svc-another-example.com/",
        "target": "https://another-example:8080"
      }
    ],
    // ...

URL are matched in the order they are defined in the configuration file.

TOML

[[gate.urls]]
pattern = "svc-example.com/*"
target = "http://example:8080"

[[gate.urls]]
pattern = "svc-another-example.com/"
target = "https://another-example:8080"

URL are matched in the order they are defined in the configuration file.

YAML

gate:
  urls:
    - pattern: svc-example.com/*
      target: http://example:8080
    - pattern: svc-another-example.com/
      target: https://another-example:8080

URL are matched in the order they are defined in the configuration file.

Token generate endpoint

Gate needs to obtain an existing token based on the SlashID person id or handles. Gate sends a POST request to your endpoint with a payload like the example below:

{
  "slashid_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ik..."
  "person_id": "cc006198-ef43-42ac-9b5a-b52713569d0f",
  "handles": [
    {
      "type": "email_address",
      "value": "[email protected]"
    },
    {
      "type": "phone_number",
      "value": "+447975777666"
    }
  ]
}

Please note the plugin includes handles in the request to the token minting endpoint only if the retrieve_handles parameter is set to true.

Example of a valid response from your endpoint:

{
  "headers_to_set": {
    "Authorization": "Basic YWxhZGRpbjpvcGVuc2VzYW1l",
    "IsLegacyHeader": "true"
  },
  "cookies_to_add": {
    "X-Internal-Auth": "9xUromfTraIwHpmC6R9NDwJwItE"
  }
}

Gate will remove the SlashID token in the Authorization header, will override the original request headers with the headers returned from headers_to_set, and will add all cookies from cookies_to_add to the ones already present in the request.

note

The plugin doesn't do anything if a SlashID token is not provided.