Passthrough :: tilegroxy Docs

This authentication method can associate a user ID and tenant ID to the request, but does not support authorization options (allowed layers or bounding box).

Description

This allows you to reuse authentication your ecosystem already has without tilegroxy needing to understand the credentials.

The outgoing is made using the client configuration. You can override the client piecemeal (like you can with a layer). Only values (header, cookie, or query params) you configure are forwarded from the original request. Redirects are not followed.

See How to: Serve Multiple Tenants for more information on using a tenant ID.

Example

YAML
JSON

authentication:
  name: passthrough
  url: https://accounts.example.com/api/me
  headers: (1)
    - X-Api-Key
  userId: /user/id (2)
  tenantId: /user/org/id (3)
  cacheSize: 1000 (4)
  cacheTTL: 60 (5)
  client:
    timeout: 2
    statusCodes: (6)
      - 200
      - 204
    contentTypes: (7)
      - application/json

1	Forwarded from the incoming request. Cookies and query parameters can be forwarded too, and at least one of the three is required.
2	An XPath expression evaluated against a JSON or XML response. For JSON, each object key becomes an element, so this would match `{"user": {"id": "alice"}}`. Array items are elements without a name, selected with ``, such as `/users/[1]/id`. @/"userId"/
3	Works the same as `userId`. If nothing (valid) matches, a warning is logged and authentication fails.
4	Keeps results in memory to decrease load on the endpoint. Rejections are cached too, but outright errors such as an inability to connect are not. Use with caution since a revoked token can keep working until the entry expires.
5	How long a result is cached.
6	Responses with any other status are rejected.
7	The response body is only read when `userId` or `tenantId` is set, and only then do the client’s `contentTypes`, `maxLength`, and `unknownLength` apply. Override `contentTypes` with the type you expect.

{
  "authentication": {
    "name": "passthrough",
    "url": "https://accounts.example.com/api/me",
    "headers": [ (1)
      "X-Api-Key"
    ],
    "userId": "/user/id", (2)
    "tenantId": "/user/org/id", (3)
    "cacheSize": 1000, (4)
    "cacheTTL": 60, (5)
    "client": {
      "timeout": 2,
      "statusCodes": [ (6)
        200,
        204
      ],
      "contentTypes": [ (7)
        "application/json"
      ]
    }
  }
}

1	Forwarded from the incoming request. Cookies and query parameters can be forwarded too, and at least one of the three is required.
2	An XPath expression evaluated against a JSON or XML response. For JSON, each object key becomes an element, so this would match `{"user": {"id": "alice"}}`. Array items are elements without a name, selected with ``, such as `/users/[1]/id`.
3	Works the same as `userId`. If nothing (valid) matches, a warning is logged and authentication fails.
4	Keeps results in memory to decrease load on the endpoint. Rejections are cached too, but outright errors such as an inability to connect are not. Use with caution since a revoked token can keep working until the entry expires.
5	How long a result is cached.
6	Responses with any other status are rejected.
7	The response body is only read when `userId` or `tenantId` is set, and only then do the client’s `contentTypes`, `maxLength`, and `unknownLength` apply. Override `contentTypes` with the type you expect.

Configuration

At least one of Headers, Cookies, or QueryParams must be supplied.

Configuration options
Parameter	Description	Type	Required	Default
`URL`	The URL of the endpoint to call. Forwarded query parameters are added to any query string already in the URL.	string	Yes	None
`Method`	The HTTP method to use when calling the endpoint. One of GET, HEAD, or POST. POST requests are sent without a body	string	No	GET
`Headers`	The headers to forward from the incoming request. Names are case-insensitive	string[]	No	None
`Cookies`	The names of cookies to forward from the incoming request	string[]	No	None
`QueryParams`	The query parameters to forward from the incoming request	string[]	No	None
`UserId`	An XPath expression for the user identifier within the response body. Not allowed when `Method` is HEAD.	string	No	None
`TenantId`	An XPath expression for the tenant identifier within the response body. Not allowed when `Method` is HEAD	string	No	None
`CacheSize`	How many results to keep in memory. Set to -1 to disable.	int	No	-1
`CacheTTL`	How many seconds a result is reused before the endpoint is called again	uint32	No	600
`Client`	Overrides the top-level Client when calling the endpoint	Client	No	None