Flow Access

Integration-level management tasks are only available to users with the correct permissions. See the Users documentation for more details.

Create a Service Account

You must authenticate the requests to flow endpoints. Authentication credentials are created as service accounts in Utilihive Heartbeat.

To create a service account:

  1. Navigate to your GridOS Connect Console.

  2. Select Service accounts from the left navigation menu.

  3. Select Create in the top-right corner.

  4. Input a Service account name, select the Credential type, and then Create.

The form to create a service account includes fields for the account name and credential type.

You have created a service account in Connect. You can view the newly created service account from the Service accounts tab in your Connect Console.

Credential Types

When you create a service account, the credential type can be one of the following:

Type Description

API key

A single, auto-generated string. Set as the value of the HTTP header named apiKey. For example: header name — apiKey, header value — HzjQL6Z9VyszduJOPbE8.

Basic authentication

A username/password pair, where the username is the account name and the password is auto-generated. Used in an HTTP authorization header as a Base64-encoded string. For example: header name — Authorization, header value — Basic dXNlcm5hbWU6cGFzc3dvcmQK.

mTLS

Certificate-based authentication. Server authenticates the client using the certificates provided by the client during the TLS handshake. See mTLS for more information.

OIDC

JSONiq claims match script authentication. See OIDC for more information.

Poller user

No credentials, because authentication is handled by the server. Used for flows that don’t have a public API endpoint. For example: file pollers.

For basic authentication and API keys, you will only have access to the auto-generated string once. Make sure you copy it somewhere, or select the save button ( ) to download the string as a text file.

If you misplace a service account’s credentials, you can generate new ones. Select the edit button ( ) from the service account list, and then select Reset Credential.

After you select the Create button, the service account is created immediately.

OpenID Connect (OIDC) Flow Access

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.

Grant Access to Flows

During the service account creation process, you will be asked which flows this account can access. If you don’t choose any flows at this time, you can still add flows later by selecting the edit button ( ).

Alternatively, you can navigate to an individual flow and select the Flow Access tab to review the accounts for that flow and add new accounts. The following image demonstrates what this page looks like:

The Flow Access tab displays a list of service accounts with an Add Flow Access button underneath.

After a service account has been added to a flow, you can make HTTP requests with the account’s credentials or add the credentials to the flow’s Documentation page to test endpoints in the browser.

Troubleshooting Flow Access

mTLS

When using mTLS authentication, the server returns a 4xx HTTP response without a detailed error message in the response body if the request is misconfigured. Common misconfigurations include missing required fields, an unexpected organization value, or a service account that lacks access to the requested flow. The response also includes an X-Auth-Event-Id header, which provides an event identifier. Use this identifier to find the specific failure reason in Kibana, under the logs* data view.

For example, if the organization does not match the expected value for the flow, a log entry similar to the following can be found in Kibana by querying for the event ID "be2db02c-32c5-489c-9206-da972570c9be":

Unexpected organizational unit: 'wrong_org',
event id: 'be2db02c-32c5-489c-9206-da972570c9be',
organization: 'expected_org',
subject: 'O=gridos,CN=ca128c3f-0cbd-420d-8aa4-0685d64d4bc6',
client: 10.116.250.52,
server: _,
request: "POST /connect/flows/rs/verification-rest-api-generic HTTP/1.1",
host: "gridos.mtls.env-connect-mvp-ingress.local"

OIDC

When you create an OIDC service account, you might run into issues when validating the JSONiq script. Use the following list to understand and troubleshoot the most common error types:

  • Validation errors: Occur when the JSONiq script is successfully parsed, but fails during execution. These errors also occur when JSONiq script runs but does not return a boolean value (true or false).

  • Syntax errors: Occur when the JSONiq code contains invalid syntax, such as missing characters or malformed expressions.

  • Parsing errors: Occur when the payload contains malformed JSON or script that cannot be parsed.