Skip to content

Downstream Authentication

API Key in Query Parameter

Authentication using an API key query parameter can be easily configured using the Authentication with Header or Query Parameter or Header configuration.

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
info:
  title: API Key in Query Parameter
openapi: 3.0.3
paths:
  /test:
    get:
      parameters:
        - in: query
          name: my-api-key
          schema:
            type: string
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  security:
    auth:
      downstream:
        clients:
          testUser:
            - 9a618248b64db62d15b300a07b00580b
        name: my-api-key
        type: query
  url: http://localhost:8080/api-key-in-query

HURL Examples

POST http://localhost:{{port}}/api/upload/api-key-in-query?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,api-key-in-query.yaml;
HTTP 200

# no api key provided
GET http://localhost:8080/api-key-in-query/test
HTTP 403
[Asserts]
body contains "RBAC: access denied"

GET http://localhost:8080/api-key-in-query/test?my-api-key=supersecret
HTTP 200

GET http://localhost:8080/api-key-in-query/test?my-api-key=wrongsecret
HTTP 403
[Asserts]
body contains "RBAC: access denied"

API Key in Request Header

Authentication using an API key request header can be easily configured using the Authentication with Header or Query Parameter or Header configuration.

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
info:
  title: API Key in Request Header
openapi: 3.0.3
paths:
  /test:
    get:
      parameters:
        - in: header
          name: my-api-key
          schema:
            type: string
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  security:
    auth:
      downstream:
        clients:
          testUser:
            - 9a618248b64db62d15b300a07b00580b
        name: my-api-key
        type: header
  url: http://localhost:8080/api-key

HURL Examples

POST http://localhost:{{port}}/api/upload/api-key?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,api-key.yaml;
HTTP 200

# no api key provided
GET http://localhost:8080/api-key/test
HTTP 403
[Asserts]
body contains "RBAC: access denied"

GET http://localhost:8080/api-key/test
my-api-key: supersecret
HTTP 200

GET http://localhost:8080/api-key/test
my-api-key: wrongsecret
HTTP 403
[Asserts]
body contains "RBAC: access denied"

Basic Authentication

Authentication using HTTP Basic Authentication can be easily configured using the Basic Authentication configuration.

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
info:
  title: Basic Authentication
openapi: 3.0.3
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  security:
    auth:
      downstream:
        clients:
          myUser:
            - 25be91d02dbbf17aff80e21323cd0dc5
        type: basic
  url: http://localhost:8080/basic-auth

HURL Examples

POST http://localhost:{{port}}/api/upload/basic-auth?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,basic-auth.yaml;
HTTP 200

# no basic auth credentials provided
GET http://localhost:8080/basic-auth/test
HTTP 403
[Asserts]
body contains "RBAC: access denied"

GET http://localhost:8080/basic-auth/test
[BasicAuth]
myuser: mysecret
HTTP 200

GET http://localhost:8080/basic-auth/test
[BasicAuth]
myuser: wrongsecret
HTTP 403
[Asserts]
body contains "RBAC: access denied"


GET http://localhost:8080/basic-auth/test
[BasicAuth]
wronguser: mysecret
HTTP 403
[Asserts]
body contains "RBAC: access denied"

Disabled

Opting out of downstream authentication by setting the Disabled Flag.

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
info:
  title: Disabled
openapi: 3.0.3
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  security:
    auth:
      downstream: disabled
  url: http://localhost:8080/disabled

HURL Examples

# see routing-misc.hurl for more examples that use "disabled" auth
POST http://localhost:{{port}}/api/upload/disabled?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,disabled.yaml;
HTTP 200

GET http://localhost:8080/disabled/test
HTTP 200

JSON Web Tokens (JWT)

Authentication using JWT can be easily configured using the Authentication with JWT configuration.

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
info:
  title: JSON Web Tokens (JWT)
openapi: 3.0.3
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  security:
    auth:
      downstream:
        provider-config:
          audiences:
            - demo
          issuer: proxyconf
          remote_jwks:
            cache_duration:
              seconds: 300
            http_uri:
              timeout: 1s
              uri: http://127.0.0.1:/api/jwks.json
        type: jwt
  url: http://localhost:8080/jwt

HURL Examples

POST http://localhost:{{port}}/api/upload/jwt?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,jwt.yaml;
HTTP 200

# no JWT is provided
GET http://localhost:8080/jwt/test
HTTP 401
[Asserts]
body contains "Jwt is missing"

# fetch invalid token (missing correct audience claim)
POST http://localhost:{{port}}/api/access-token
[QueryStringParams]
client_id: {{oauth-client-id-other}}
client_secret: {{oauth-client-secret-other}}
grant_type: client_credentials
HTTP 200
[Captures]
invalid_access_token: jsonpath "$['access_token']"

# Invalid JWT is provided
GET http://localhost:8080/jwt/test
Authorization: Bearer {{invalid_access_token}}
HTTP 403
[Asserts]
body contains "Audiences in Jwt are not allowed"

# fetch valid token (including audience specified in downstream auth config)
POST http://localhost:{{port}}/api/access-token
[QueryStringParams]
client_id: {{oauth-client-id}}
client_secret: {{oauth-client-secret}}
grant_type: client_credentials
HTTP 200
[Captures]
valid_access_token: jsonpath "$['access_token']"

# Valid JWT is provided
GET http://localhost:8080/jwt/test
Authorization: Bearer {{valid_access_token}}
HTTP 200

Mutual TLS (mTLS)

Authenticate using TLS client certificates (mTLS).

OpenAPI Specification
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
info:
  title: Mutual TLS (mTLS)
openapi: 3.0.3
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
servers:
  - url: http://127.0.0.1:/api/echo
x-proxyconf:
  cluster: demo
  listener:
    address: 127.0.0.1
    port: 44444
  security:
    auth:
      downstream:
        clients:
          test_client:
            - exunit-good
        trusted-ca: /tmp/proxyconf/ca-cert.pem
        type: mtls
  url: https://localhost:44444/mtls

HURL Examples

POST http://localhost:{{port}}/api/upload/mtls?api-port={{port}}&envoy-cluster={{envoy-cluster}}
Content-Type: application/yaml
Authorization: Bearer {{admin-access-token}}
file,mtls.yaml;
HTTP 200

# HTTP Request with an invalid client certificate
GET https://localhost:44444/mtls/test
[Options]
cert: /tmp/proxyconf/exunit-bad.crt
key: /tmp/proxyconf/exunit-bad.key
HTTP 403
[Asserts]
body contains "RBAC: access denied"

# HTTP Request with a valid client certificate
GET https://localhost:44444/mtls/test
[Options]
cert: /tmp/proxyconf/exunit-good.crt
key: /tmp/proxyconf/exunit-good.key
HTTP 200