OAuth 2.0 Token Introspection Authentication

The OAuth2 Token Introspection protocol (defined in the RFC 7662) allows Traefik Hub API Gateway to retrieve metadata about an access token from an OAuth 2.0 server with the Token Introspection extension.

Every application brings its AccessToken to Hub API Gateway using one of the following sources:

• A header (and a scheme if the AccessToken is provided using the Authorizationheader),
• A query parameter,
• A cookie.

Then, Hub API Gateway calls the Identity Provider providing the AccessToken. In return, the Identity Provider sends a JSON document representing the meta information surrounding the token, including whether this token is currently active.

Metadata Usage

The meta information surrounding the token can be used for advanced use-cases such as adding an Authorization layer using the claims.

More information in the dedicated section.

Configuration Example

To allow the OAuth2 Token Introspection to get the AccessToken from the Authorization Header provided by the requests, apply the following configuration:

Middleware OAuth2 Token Introspection

---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth2-token-introspection
  namespace: apps
spec:
  plugin:
    oAuthIntrospection:
      tokenSource:
        header: Authorization
        headerAuthScheme: Bearer
      clientConfig:
        url: "https://YOUR-KEYCLOAK-ADDRESS/realms/YOUR-REALM/protocol/openid-connect/token/introspect"
        headers:
          Authorization: Basic ZXhhbXBsZTpleGFtcGxl # echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: oauth2-token-introspection

Service & Deployment

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

How to recover the AccessToken?

The Identity Providers expose a dedicated endpoint that allow the applications to generate their AccessToken before reaching Hub API Gateway.

The example below decribes the commands to run in order to get an AccessToken from a Keycloak server:

# Initialize the required information
CLIENT_ID="xxxxx"
CLIENT_SECRET="xxxxx"
GRANT_TYPE="client_credentials"
# Replace YOUR-KEYCLOAK-ADDRESS with your Keycloak server address and YOUR-REALM with your realm name
KEYCLOAK_URL="https://YOUR-KEYCLOAK-ADDRESS/realms/YOUR-REALM"
# Your App URL
MY_APP_URL="xxxxx"
# Get the token using curl and jq commands
TOKEN=$(curl -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET" -d "grant_type=$GRANT_TYPE" "$KEYCLOAK_URL/protocol/openid-connect/token" | jq .access_token | cut -d '"' -f2)

# Test the Token against the middleware
curl -s -H "Authorization: Bearer $TOKEN" --request GET --url "$MY_APP_URL/my-app"

Advanced Configuration

Advanced options are described in the reference page.

For example, the metadata recovered from the Identity Provider can be used to restrict the access to the applications. To do so, you can use the claims option, more information in the dedicated section.

---

Related Content

• See the full options in the dedicated section.
• See how to secure your API using OAuth2 Client Credentials.
• See how to secure your API access using OIDC.