Flow Access using OpenID Connect (OIDC)

OpenID Connect (OIDC) is an authentication protocol that adds an identity layer on top of OAuth2.0. In Connect, the authentication for OIDC is by JSONiq claims match script.

JSONiq query language is the data mapping language used in Connect. For more information, see Data Mapping.

When authorizing flow access using OIDC, Connect requires a valid JWT token. The JSONiq claims-matching script authenticates the Service Account. It specifies the claims an external OIDC identity must have to be recognized as the OIDC Service Account.

Flow access authorization works the same way as for other service accounts by explicitly adding flow access to the OIDC Service Account.

The OIDC flow access authorization process is as follows:

  1. If the token is invalid (for example, unsigned or expired), the request is rejected with a 401 authentication error.

  2. If the token is valid, Connect checks for OIDC Service Accounts whose JSONiq claims-matching script returns true.

    1. If no matching Service Accounts are found, the request is rejected with a 401 authentication error.

    2. If matching Service Accounts are found, Connect checks whether any of them have access to the requested flow.

      1. If none of the matching Service Accounts has flow access, the request is rejected with a 403 authorization error.

      2. If a single Service Account is authorized to access the flow, the request is accepted.

      3. If multiple Service Accounts are authorized to access the flow, Connect selects one at random as the identity to perform the request.

OIDC Integration Limitations: GridOS Connect supports OpenID Connect (OIDC) service provider: Zitadel, as configured in {foundation-docs-base-url}/foundation-base-user-guide/zitadel/overview.html[Foundation]. Tokens issued by any other OIDC service provider are not supported and will be rejected by Connect.

OIDC Service Account

To create a Service Account of type OIDC, you must provide an additional field: a JSONiq script. This field is required.

When you create a service account, enter the Service account name and select OIDC as the Credential type. Then provide a JSONiq script for claim matching and select Create.

You have now created a Service Account of type OIDC in Connect.

JWT Claims Matching

The JSONiq claims match script for a Service Account determines which attributes an incoming JWT must have to be recognized as that Service Account. Connect evaluates the script against the JWT.

  1. If the script returns true, the JWT can be used to identify the Service Account.

  2. If the script returns false, the JWT cannot be used to identify the Service Account.

For more information, see {foundation-docs-base-url}/foundation-base-user-guide/zitadel/overview.html#_authentication[Foundation authentication].

A simple use case for claims matching script is subject matching.

#input.sub = "321856323064955050"

To get a sample claims object for testing, paste your JWT token into JWT and Copy the DECODED PAYLOAD.

To test and validate a JSONiq claims-match script, use the editor, which is preloaded with an example that shows a script matching a specific permission provided to the user through Foundation permission mapping.

You can replace the payload with a relevant claims object and test the script you intend to use for the Service Account.

some #p in #input.sws_permissions[] satisfies #p = "fooapp.panel.read.readAll"
{
  "sub": "321856323064955050",
  "sws_groups": "systemadmin",
  "sws_permissions": [
    "roleManager.userGroups.read.readAll",
    "fooapp.panel.read.readAll",
    "sessionManager.gatewaySessions.read.readAll"
  ],
  "user_name": "test-user"
}

For a more complex JSONiq script example, try the following:

 (some #a in #input.aud[] satisfies #a = "278664006883868833")
 and (some #p in #input.sws_permissions[] satisfies #p = "connect.testOrg.admin")
 and (#input.user_name = "testUser")
{
  "aud": [
    "278664008578433185@foundation",
    "278664007051706529@foundation",
    "278664006883868833"
  ],
  "exp": 33358698556,
  "iat": 1712655694,
  "iss": "http://localhost:9997",
  "jti": "281128088358617477",
  "nbf": 1712655694,
  "sub": "244560291684155510",
  "sws_groups": [
    "systemadmin"
  ],
  "sws_permissions": [
    "connect.testOrg.admin",
    "connect.customer-a1.agent",
    "connect.ownerOrgShortName.agent",
    "usergroupmanager.userGroups.read.readAll",
    "usergroupmanager.userGroups.write.write"
  ],
  "user_name": "testUser"
}

Manage an OIDC Service Account

When you create a service account, you must provide a unique, user-defined name. You can also edit or delete the JSONiq script associated with a service account.

After a service account is created, you can update it at any time by modifying the JSONiq script. When you save the changes, the script is validated as described in JWT claims matching section.

To troubleshoot flow access issues related to OIDC, see Troubleshooting.