Step-up auth: Add include condition for ID token claims

🛠️ with ❤️ at Siemens

Motivation

The OIDC standard intends the ID token claim acr to be used for implementing step-up authentcation. However, some commonly used identity providers offer different mechanisms for implementing step-up authentication.

For example, Microsoft Entra ID (MS Entra ID) allows implementing step-up authentcation scenarios with conditional access and authentication context. MS Entra ID exposes the ID token claim acrs as JSON string array instead of the official single string ID token claim acr, see the following example.

Official OIDC standard	MS Entra ID
"acr": "c20"	"acrs": ["c20", "c21", "c25"]
Note: The OIDC standard ID token claim acr is a single string value.	Note: The acrs claim is a JSON string array and includes the authentication context IDs that have been satisfied by the user in the last authentication attempt.

The current step-up auth implementation in GitLab allows to check if the ID token claim acr matches (exactly) a certain value, see documentation. But, this current "exact match" mechanism cannot be applied to the JSON string array in the acrs claim because the acrs ID token claim can include different the authentication context IDs in different order.

For example, the MS Entra ID of an organization has defined the authentication context ID "c20" that the represents authentication by MFA and trusted device. When we want an admin user to authenticate with the authentication context ID c20 it is not sufficient to define the step-up auth condition as id_token: { required: { acrs: ["c20"] } }. Why? Because the acrs ID token claim can include multiple authentication context IDs, e.g. "acrs": ["c20", "c21"] or "acrs": ["c20", "c21", "c25"], etc.

As a solution, the step-up implementation could also accept "include" matchers, see the section Proposal.

Proposal

We propose enhancing the step-up authentication for Admin Mode with additional matching criteria for ID token claims. Specifically, we need to add support for verifying that a specific value is included in an array-based claim.

This is necessary for working with Microsoft Entra ID's authentication context implementation, see problem description above.

step_up_auth: {
  admin_mode: {
    id_token: {
      # Existing matchers remain unchanged
      required: {
        acr: 'gold'  # Exact match for standard OIDC providers
      },
      # New matcher for array-based claims
      include: {
        acrs: 'c20'  # For Microsoft Entra ID - checks if 'c20' is in the acrs array
      }
    }
  }
}

This enhancement would make GitLab's step-up authentication more flexible and compatible with Microsoft Entra ID and other identity providers that use array-based claims for authentication contexts.