Plugin - Token translation: internal to SlashID

This plugin can upgrade received token to SlashID JWT.

Example usage

Please see Translate legacy tokens to SlashID tokens.

Configuring Gate

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=token-translation-upgrade
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_HEADER_WITH_TOKEN=<Header with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_COOKIE_WITH_TOKEN=<Cookie with token>
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_MAP_TOKEN_ENDPOINT=<Map token 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-upgrade"
            parameters = {
                header_with_token  = "<Header with token>"
                cookie_with_token  = "<Cookie with token>"
                map_token_endpoint = "<Map token 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-upgrade",
        "parameters": {
          "header_with_token": "<Header with token>",
          "cookie_with_token": "<Cookie with token>",
          "map_token_endpoint": "<Map token 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-upgrade"
parameters.header_with_token = "<Header with token>"
parameters.cookie_with_token = "<Cookie with token>"
parameters.map_token_endpoint = "<Map token 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-upgrade
      parameters:
        header_with_token: <Header with token>
        cookie_with_token: <Cookie with token>
        map_token_endpoint: <Map token endpoint>
        slashid_org_id: <SlashID Org ID>
        slashid_api_key: <SlashID API key>
        slashid_base_url: <SlashID base URL>
    // ...

where:

• <Header with token> is the request header containing the token sent to the token mapping endpoint. This option and cookie_with_token are mutually exclusive.
• <Cookie with token> is the request cookie containing the token sent to the token mapping endpoint. This option and header_with_token are mutually exclusive.
• <Map token endpoint> the URL of the endpoint that maps received token to user handles.
• <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.

If neither <Header with token> nor <Cookie with token> are set, the plugin attempts to get a bearer token from the Authorization header, and strips the Bearer prefix from it.

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 mapping endpoint

Gate needs to know how to map the token received to a SlashID token. To do that, you need to implement a token mapping endpoint. Gate POST to the endpoint requests with the following format:

{
  "token": "Token from the original request header"
}

Your token mapping endpoint should return the SlashID person ID or person handles corresponding to the input token.

Optionally, you can also return a list of custom claims that should be added to the SlashID token minted through Gate. Certain claims are reserved, you can find a detailed list of reserved claims and the format to specify custom claims in the mint token API docs. Custom claims are optional.

The examples below are valid responses sent from a token mapping endpoint.

Response with user handles

{
  "handles": [
    {
      "type": "email_address",
      "value": "[email protected]"
    }
  ],
  "custom_claims": {
    "custom_attribute_1": 42,
    "custom_attribute_2": {
      "sub_attr": 24
    }
  }
}

All valid handles types can be found in the API documentation.

Caching tokens

Gate caches the endpoint mapping in the in-memory cache by default.

To increase the token cache hit-ratio, we recommend configuring sticky sessions in your load balancer.