Endpoints

OIDC-Guard contains the following endpoints:

Auth

Returns OK or Unauthorized

Parameters

The /auth endpoint supports configurable parameters in the format of {claim}={value}. In the case the same claim is called more than once, the traffic will have to match only one.

For example, using the following query string /auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&aud=33333333-3333-3333-3333-333333333333

Along with validating the JWT token, the token must have a claim tid=11111111-1111-1111-1111-111111111111 and one of aud=22222222-2222-2222-2222-222222222222 or aud=33333333-3333-3333-3333-333333333333

How to query arrays

The /auth endpoint is able to query arrays. We'll use the following JWT token in the example.

{
  "email": "[email protected]",
  "groups": ["admin", "developers"],
}

Using the following query string we can limit this endpoint to only tokens with an admin group /auth?
groups=admin

Inject claims as headers

The /auth endpoint supports a custom parameter called "inject-claim". The value is the name of claim which will be added to the response headers.

For example, using the following query string /auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&inject-claim=email

The /auth response will contain header email=[email protected]

Inject claims as headers with custom name

The value should be in the following format, "{claim name},{header name}".

For example, using the following query string /auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&inject-claim=email,mail

The /auth response will contain header mail=[email protected]

Example Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
  annotations:
    nginx.ingress.kubernetes.io/auth-url: https://oidc-guard.company.com/auth?aud=11111111-11111-1111111111&inject-claim=groups,JWT-Claim-Groups&inject-claim=scope,JWT-Claim-Scope
    nginx.ingress.kubernetes.io/auth-signin: https://oidc-guard.company.com/signin
    nginx.ingress.kubernetes.io/auth-response-headers: JWT-Claim-Groups, JWT-Claim-Scope

Inject JSON claims

The /auth endpoint supports a custom parameter called "inject-json-claim". This parameter allows parsing JSON Claims and extracting values using JSON Path.

For example, assume we have the following JWT token

{
  "aud": "/projects/project_number/apps/my_project_id",
  "gcip": '{
    "auth_time": 1553219869,
    "email": "[email protected]",
    "email_verified": true,
    "firebase": {
      "identities": {
        "email": [
          "[email protected]"
        ],
        "saml.myProvider": [
          "[email protected]"
        ]
      },
      "sign_in_attributes": {
        "firstname": "John",
        "group": "test group",
        "role": "admin",
        "lastname": "Doe"
      },
      "sign_in_provider": "saml.myProvider",
      "tenant": "my_tenant_id"
    },
    "sub": "gZG0yELPypZElTmAT9I55prjHg63"
  }',
  "email": "securetoken.google.com/my_project_id/my_tenant_id:[email protected]",
  "exp": 1553220470,
  "iat": 1553219870,
  "iss": "https://cloud.google.com/iap",
  "sub": "securetoken.google.com/my_project_id/my_tenant_id:gZG0yELPypZElTmAT9I55prjHg63"
}

We can extract the role into a custom header by using the following: /auth?
inject-json-claim=role,gcip,%24.firebase.sign_in_attributes.role

The /auth response will contain header role=admin

Skip Auth

The /auth endpoint supports custom parameters called "skip-auth" and "skip-auth-ne".

These parameters support the following formats:

• HTTP_METHOD,REGEX
  • the first part is the HTTP Method, ie GET, POST etc
  • the second part is a Regex rule
• REGEX
  • regex the path needs to match

For example, the following query string will skip authentication for GETs to the /favicon.ico
/auth?skip-auth=GET,/favicon.ico$

For example, the following query string will skip authentication for all METHODS which have /api/ in the path
/auth?skip-auth=/api/

For example, the following query string will skip authentication for all METHODS which do not have /api/ in the path
/auth?skip-auth-ne=/api/

Signin

Signs-In the using the OIDC flow and saves the claims into a encrypted cookie

Parameters

"rd" which is the url that the sign in process will redirect the user to

Signout

Signs-Out the current user and removes the authentication cookie

Parameters

"rd" which is the url that the sign out process will redirect the user to

UserInfo

Displays a Dictionary of claims

{
  "aud": "7c9368e5-08df-4d44-8e9f-4e293bc56ceb",
  "idp": "https://sts.windows.net/9188040d-6c67-4c5b-b112-36a304b66dad/",
  "name": "Ivan J",
  "oid": "a6a18c2f-066d-43df-b1ba-ff8bfe5918b1",
  "preferred_username": "[email protected]",
  "tid": "72740055-b0b0-4c36-8ff7-0811f93a0a3f",
  "uti": "UyqzI9UJhEeDOGrxvJY0AA"
}

Metrics

Metrics are exposed on :8080/metrics

Metric Name	Description
oidc_guard_authorized	Number of Authorized operations ongoing
oidc_guard_unauthorized	Number of Unauthorized operations ongoing
oidc_guard_signin	Number of Sign-in operations ongoing
oidc_guard_signout	Number of Sign-out operations ongoing