Plugin - Users mirroring

This plugin can be used to migrate your user base.

Example usage

Please see Passive users migration.

Configuring Gate

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=mirroring
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_HEADER_WITH_TOKEN=<Header 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>

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

HCL

gate = {
    plugins = [
        // ...
        {
            type          = "mirroring"
            parameters = {
                header_with_token       = "<Header with token>"
                map_token_endpoint      = "<Map token endpoint>"
                slashid_org_id          = "<SlashID Org ID>"
                slashid_api_key         = "<SlashID API key>"
            }
        }
        // ...
    ]
}

JSON

{
  "gate": {
    "plugins": [
      // ...
      {
        "type": "mirroring",
        "parameters": {
          "header_with_token": "<Header with token>",
          "map_token_endpoint": "<Map token endpoint>",
          "slashid_org_id": "<SlashID Org ID>",
          "slashid_api_key": "<SlashID API key>"
        }
      }
      // ...
    ]
  }
}

TOML

[[gate.plugins]]
type = "mirroring"
parameters.header_with_token = "<Header with token>"
parameters.map_token_endpoint = "<Map token endpoint>"
parameters.slashid_org_id = "<SlashID Org ID>"
parameters.slashid_api_key = "<SlashID API key>"

YAML

gate:
  plugins:
    // ...
    - type: mirroring
      parameters:
        header_with_token: <Header with token>
        map_token_endpoint: <Map token endpoint>
        slashid_org_id: <SlashID Org ID>
        slashid_api_key: <SlashID API key>
    // ...

where:

• <Header with token> is header sent to the token mapping endpoint. For example: Authorization.
• <Map token endpoint> 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

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

info

The order of the plugins in the configuration determines their execution order.

Defining custom person create endpoint

By default, Gate directly calls SlashID to create a new person. If you want to override this option, please use:

Environment variables

GATE_PLUGINS_<PLUGIN NUMBER>_TYPE=mirroring
GATE_PLUGINS_<PLUGIN NUMBER>_PARAMETERS_PERSONS_CREATE_ENDPOINT=http://slashid:8080/persons

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

HCL

gate = {
    plugins = [
        // ...
        {
            type          = "mirroring"
            parameters = {
                persons_create_endpoint = "http://slashid:8080/persons"
            }
        }
        // ...
    ]
}

JSON

{
  "gate": {
    "plugins": [
      // ...
      {
        "type": "mirroring",
        "parameters": {
          "persons_create_endpoint": "http://slashid:8080/persons"
        }
      }
      // ...
    ]
  }
}

TOML

[[gate.plugins]]
type = "mirroring"
parameters.persons_create_endpoint = "http://slashid:8080/persons"

YAML

gate:
  plugins:
    // ...
    - type: mirroring
      parameters:
        persons_create_endpoint: http://slashid:8080/persons
    // ...

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 tokens to SlashID users. Your endpoint will receive requests in the format:

{
  "token": "Token from the configured header"
}

Your endpoint should return the user that Gate should create in SlashID. Gate will pass the responded body directly to PUT /persons endpoint..

caution

The PUT /persons endpoint accepts a list of persons to create, however Gate expects your endpoint to return just a single person.

Example response from your endpoint:

{
  "attributes": {
    "attribute_1": "value"
  },
  "handles": [
    {
      "type": "email_address",
      "value": "[email protected]"
    }
  ],
  "region": "us-iowa",
  "roles": ["admin"],
  "groups": ["admins"]
}

Under the hood, Gate will call PUT /persons endpoint. with that payload. This operation is idempotent. If a user with the provided handles already exists, Gate will not create a new user. If user already exists, Gate will update the user with the provided attributes, roles, and groups.

caution

Region of person can't be changed if person already exists. Gate will not update the user's region.

If region is not defined, the region that is closest to Gate instance will be used.

Detailed body structure can be found in PUT /persons API documentation.

Caching tokens

Gate caches endpoint mapping in-memory by default.

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

Propagating created person

The person ID of the newly created user will be added to the request and passed to your backend services via the SlashID-PersonID header. SlashID-Person-Created is true if Gate created a person.