Authentication and project access¶

AntFlow uses the sign-in provider configured for your instance: GitLab or Keycloak. Signing in identifies you to AntFlow; repository access determines which GitLab projects and workflows you can use.

Sign in¶

Open your instance and sign in using its configured provider. With GitLab, your login supplies repository access through your GitLab account. With Keycloak, the identity used to sign in and the credential used to access GitLab are separate.

If you do not have an account or cannot complete sign-in, contact your platform administrator. Workflow publication does not enable anonymous access.

GitLab access with Keycloak¶

Signing in with Keycloak does not automatically give AntFlow access to your GitLab account. To use repositories through your own GitLab permissions, create a personal access token and save it in your AntFlow profile as described below.

You do not need your own GitLab token to use projects published in AntFlow. Without a personal token, AntFlow uses the server's GitLab token. You must still sign in and, if publication is restricted to groups, belong to at least one of those groups.

1. Create a personal access token¶

1. Open the GitLab instance used by your platform.
2. In your user settings, open Personal access tokens.
3. Create a token with a descriptive name, an appropriate expiration date, and the read_api scope.
4. Keep the token in your approved credential store; GitLab will not display it again.

The token gives AntFlow the access its owner already has in GitLab; it does not grant additional project permissions.

2. Update your profile¶

1. Sign in to AntFlow with Keycloak.
2. Open the user menu and select Profile.
3. Update the GitLab token field using the editor provided by your deployment.
4. Save the profile, sign out of AntFlow, and sign in again.

A password-style editor may encrypt the token automatically. If the field expects an encrypted JSON string, do not paste a raw token into it. Ask your administrator for the supported encryption procedure and attribute name, normally git_token. The server's encryption helper is also described in Manage workflow secrets, but a repository token belongs in the separate GitLab token field, not the workflow-secret list.

Which projects you can access¶

Token selection¶

AntFlow uses one GitLab credential to discover projects and submit jobs. The credential depends on how you sign in:

Discovery filters also determine which accessible projects appear in AntFlow. Submitting a job requires valid inputs and an accessible, eligible launcher.

Published project access¶

Publication with no groups makes a project discoverable to all authenticated users using the server token. Specifying groups limits discovery to users who belong to at least one of those authentication groups.

When you use published projects through the server token, GitLab permissions apply to that token, not to your own GitLab membership. You still need to sign in to AntFlow and satisfy the publication-group and launcher-access rules.

Project permissions¶

GitLab project membership and token scope are separate requirements. A token does not grant its owner additional project permissions. Roles can be inherited from a parent group; GitLab uses the user's effective project permissions.

The following table describes access through your own GitLab account or token to a private workflow repository, using the cumulative GitLab roles below. Public and internal repositories can allow reads without the same membership requirement; AntFlow still requires sign-in.

Discovery also requires the project to match the instance's discovery filters. Repository reads must cover the selected reference and any private repository dependencies. Submission requires valid inputs and an accessible, eligible launcher. Submit jobs does not imply access to project CI/CD variables; see the warning below. Push workflow source applies to unprotected branches; protected branches have their own rules.

Use project variables in jobs means reading existing GitLab project CI/CD variables during submission and supplying their values as environment variables during job execution. It does not mean creating or editing variables in GitLab.

Publishing a project in AntFlow is a separate capability: the caller must be an AntFlow administrator, and the configured server token must access the project. GitLab Maintainer or Owner membership alone does not grant this right.

Reporter is the usual read-only choice for a private workflow repository, not an unconditional role threshold enforced by AntFlow. GitLab 18.7 and later also allow the Planner role to view private repository content; custom roles can grant repository reads to Guests. Project visibility, feature settings, GitLab version, and custom permissions can therefore change the minimum role. GitLab authorizes the actual repository API calls, not just the displayed role name.

These requirements apply to the selected GitLab credential; see Token selection.

GitLab documents the underlying rules in repository permissions, access token scopes, and the project-level variables API.

Troubleshooting¶

After changing a profile token, sign out and back in. Renewing a Keycloak API token does not fix a missing or expired repository token, and replacing a repository token does not renew a Keycloak access token.

Technical details¶

Access, ID, and refresh tokens¶

The UI signs in through OIDC with PKCE. Only the access token is sent to AntFlow's API; ID and refresh tokens belong to the client session.

GitLab sign-in¶

flowchart TB
    ui["UI signed in with GitLab"] -->|GitLab access token| api["AntFlow API"]
    api -->|Same access token| gitlab["GitLab API: identity and repositories"]

The server identifies the user through GitLab's GET /api/v4/user, not by decoding an ID token. Scripts can use a personal access token instead of an OAuth login; see Create a personal access token. For the UI's OIDC scopes, see GitLab client configuration.

Keycloak sign-in¶

flowchart TB
    ui["UI signed in with Keycloak"] -->|Keycloak access token| api["AntFlow API: identity and groups from JWT"]
    api -->|Same access token| userinfo["Keycloak userinfo"]
    userinfo -->|Encrypted profile attributes| attributes["Personal GitLab token and workflow secrets"]

The server uses the realm's signing keys to decode the JWT. Identity and groups must be in the access token; encrypted GitLab-token and user-secret attributes are retrieved separately from userinfo and decrypted by the server. They do not need to be in the access token or ID token.

Operators configure the claims and mappers under Keycloak configuration.

Repository credential selection flow¶

For Keycloak sign-in, the following diagram shows how the token-selection rules apply to discovery and submission:

flowchart TB
    user["Authenticated Keycloak user"] --> personal{"Valid personal GitLab token?"}
    personal -->|Yes| personalToken["Use personal GitLab token"]
    personal -->|Absent or invalid| server{"Server GitLab token configured?"}
    server -->|No| rejected["Reject GitLab-backed requests"]
    server -->|Yes| serverToken["Use server GitLab token"]
    personalToken --> personalProjects["Search projects readable by the personal token"]
    serverToken --> publishedProjects["Search published projects allowed by user groups"]
    personalProjects --> filters["Apply project discovery filters"]
    publishedProjects --> filters
    filters --> processes["Discover processes and read their descriptions"]
    processes --> submit["Submit job with valid inputs and an eligible launcher"]

Token use after submission¶

The selected GitLab token is stored encrypted with the job. When a launcher requests the workflow package, the server first uses that job token. If a GitLab API error prevents retrieval, the server retries with its configured token, if available. This separate package-retrieval fallback does not extend the user's project discovery or submission permissions.

The server token must remain able to read the repositories required by queued jobs. Project CI/CD variables are read during submission, using the credential selected at that stage; see Project permissions.

For Helm configuration, see Server GitLab token.

API credentials¶

Use the credential for the instance's configured provider:

Do not substitute an OIDC ID token or a refresh token for these credentials; see Access, ID, and refresh tokens.

A GitLab token stored in a Keycloak profile supplies repository access; it does not authenticate an API request to a Keycloak-backed instance.

Send the credential as Authorization: Bearer <token>, or use the supported X-Auth-Token header. Use one header, not both. Your administrator can provide the API base URL and the supported OAuth client and flow; do not assume that password grants are enabled.

Follow Access the API to configure the base URL, load the credential without writing it into shell history, and check the authenticated identity before running the reference examples.

OAuth access tokens expire according to the provider's token response. Clients should track expires_in, keep valid tokens in memory, and renew them using the configured flow. A GitLab personal token has its GitLab expiration date; an OAuth refresh operation does not renew it.