OIDC step-up authentication

This use case shows how to enforce step-up authentication using OpenID Connect (OIDC) with Airlock Microgateway. Step-up is a general authentication concept: it raises the required authentication strength for selected actions or paths. Airlock Microgateway currently supports interactive authentication via OIDC, so this article describes how to implement step-up requirements based on OIDC authentication results (e.g., required scopes and ACR values).

The configuration steps below show how to configure an access control policy that enforces OIDC authentication for an application path and adds step-up requirements for selected subpaths. The examples are based on a Microsoft Entra ID integration and must be adjusted to your setup.

 
Notice

Do not confuse this feature with OAuth 2.0 step-up as described in RFC 9470.

  • RFC 9470 defines step-up for OAuth 2.0, while this Microgateway implementation applies step-up requirements in the context of OIDC-based authentication (evaluating OIDC authentication results such as scopes and ACR values).

Prerequisites

  • A Gateway deployment.
  • Session handling must be configured.
  • An HTTPRoute routing the traffic to your application.
  • A working OIDC setup as described in the OIDC authentication use case (JWKS, OIDCProvider, OIDCRelyingParty, AccessControlPolicy with OIDC authentication).
  • An OIDC provider setup with issuer, client ID, client secret, and the required endpoints.
    Note: The OIDC provider configuration is not part of this article.

Configuration

This section shows how to configure Airlock Microgateway with an access control policy that first enforces OIDC authentication for an application path and then adds step-up requirements for selected subpaths.

Create a baseline AccessControlPolicy

Start with a simple policy that requires OIDC authentication for /app/ and denies all other requests.

 
Example
apiVersion: microgateway.airlock.com/v1alpha1
kind: AccessControlPolicy
metadata:
  name: my-webapplication
  namespace: project-a
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: my-webapplication
  policies:
    - requestConditions:
        path:
          matcher:
            prefix: /app/
      authorization:
        authentication:
          oidc:
            oidcRelyingPartyRef:
              name: my-webapplication
    - authorization:
        deny: {}

Add step-up requirements

  1. Extend the AccessControlPolicy with step-up requirements:
    • /app/confidential/ requires the scope confidential.
    • /app/confidential/admin/ additionally requires a stronger authentication level indicated by an allowed ACR value (example values: urn:your-company:acr:weak or urn:your-company:acr:strong).
  3. Configure step-up requirements in authorization.ensured.oidc:
    • ensured.oidc.scopes (required scopes)
    • ensured.oidc.acrInValues (allowed ACR values)
  5. Define policies from most restrictive to least restrictive, so that more specific paths are matched first.
  6.  
    Example
    apiVersion: microgateway.airlock.com/v1alpha1
kind: AccessControlPolicy
metadata:
  name: my-webapplication
  namespace: project-a
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: my-webapplication
  policies:
    - requestConditions:
        # policy with the most specific request conditions first
        path:
          matcher:
            prefix: /app/confidential/admin/
      authorization:
        ensured:
          oidc:
            scopes:
              - confidential
            acrInValues:
              - urn:your-company:acr:weak
              - urn:your-company:acr:strong
        authentication:
          oidc:
            oidcRelyingPartyRef:
              name: my-webapplication

    - requestConditions:
        path:
          matcher:
            prefix: /app/confidential/
      authorization:
        ensured:
          oidc:
            scopes:
              - confidential
        authentication:
          oidc:
            oidcRelyingPartyRef:
              name: my-webapplication

    - requestConditions:
        path:
          matcher:
            prefix: /app/
      authorization:
        authentication:
          oidc:
            oidcRelyingPartyRef:
              name: my-webapplication

    # All other requests are denied by default.
    - authorization:
        deny: {}

Validation

Validate step-up in the browser

Attempt to access endpoints behind the targeted HTTPRoute. If the configuration is correct, the following will be observed:

  • Accessing /app/ triggers OIDC authentication (if the user is not authenticated).
  • Accessing /app/confidential/ requires the scope confidential according to the policy.
  • Accessing /app/confidential/admin/ requires the scope confidential and one of the configured ACR values.
  • If authorization succeeds, the request is forwarded to the back-end.

Validate step-up in Grafana

The built-in Grafana dashboard Airlock Microgateway Access Control - Logs provides step-up relevant details per request.

  1. Look at the Details column. It contains an OIDC-related JSON structure; the field .oidc.step categorizes the request within the OIDC flow.
    For an OIDC flow with step-up, you typically observe the following .oidc.step values:
    • authentication-redirect
    • authorization-grant-exchange
    • application-access
    • step-up-redirect
    • authorization-grant-exchange
    • application-access
  3. Use this values to verify that:
    • the initial access triggers authentication and then application access, and
    • accessing a step-up protected area triggers an additional step-up-redirect followed by another token exchange and application access.