Authentication¶

AntFlow supports GitLab and Keycloak as OIDC providers.

Register the UI's URL as a redirect URI. Installation with Helm uses http://localhost:8080/ for local port-forwarding. For public access, register your HTTPS UI URL, such as https://antflow.example.com/, instead.

The UI uses the authorization-code flow with PKCE and sends the resulting access token, not the ID token or refresh token, to AntFlow's API. For the token roles and repository-credential distinction, see Access, ID, and refresh tokens.

GitLab¶

Set configs.oidc.provider: gitlab, configs.oidc.issuer to the GitLab instance URL, and configs.oidc.clientId to the application's ID in your Helm values. The user's OIDC access token is also used for GitLab API requests.

Create an OAuth application under User Settings > Applications:

• Application name: a display name of your choice.
• Confidential: off.
• Redirect URI: the UI URL.
• Scopes: openid, profile, email, read_api.

These four scopes match the current UI's authorization request:

The server identifies GitLab users through GET /api/v4/user; it does not require profile or email OIDC claims for that operation. Those scopes are requested by the UI's OIDC client, not by the server's REST calls. Keep all four enabled for the current UI configuration. A personal access token used by a script or stored in a Keycloak profile does not need OIDC scopes; see Create a personal access token.

GitLab documents the distinction in its OAuth scope definitions and OIDC provider configuration.

The issuer is the GitLab instance URL.

Keycloak¶

Use your Keycloak base URL, realm, and registered client ID in the following Helm template. Replace auth.example.com with that Keycloak service and use your UI origin for the redirect and web-origin settings below:

configs:
    oidc:
        provider: keycloak
        issuer: https://auth.example.com
        realm: my-realm
        clientId: antflow
        token_attribute: git_token
        secret_attribute: antflow_secrets
        groups_pathlike: true

The chart derives the realm's signing-key, userinfo, and account endpoints from the issuer and realm. Ensure these endpoints are reachable from the server.

Create a public client in your realm:

• Valid redirect URIs: https://antflow.example.com/*.
• Web origins: https://antflow.example.com.
• Default scopes: basic, openid, profile, email.

For local access, substitute http://localhost:8080 for the public origin.

Access-token claims and userinfo¶

The server builds the Keycloak user's identity from the access-token claims, not from the ID token. Ensure that access tokens include iss, sub, name, preferred_username, email, and email_verified. Configure groups as described below when using group-restricted access. Profile claims available only in the ID token or userinfo response do not replace the required access-token claims.

The server uses the access token again when calling userinfo. It reads the encrypted repository-token and user-secret attributes from that response; configure those attribute mappers with Add to userinfo enabled, as below. There is no need to put those sensitive attributes in access tokens or ID tokens. Refresh tokens belong to the client's renewal flow and are not sent to AntFlow's API.

Personal GitLab tokens¶

Under Realm settings > User profile, create the git_token attribute and allow users to view and edit their own value. In the client's dedicated scope, add a User Attribute mapper to expose it in userinfo:

If you choose another attribute name, set configs.oidc.token_attribute to match. The server expects the token value in AntFlow's serialized secret format, not a raw token string. Provision it through the AntFlow-compatible user-secret flow.

For repository credential selection and fallback rules, see Token selection. For Helm configuration, see Server GitLab token.

The realm issuer is https://auth.example.com/realms/my-realm. The client ID and realm must match the client registered in Keycloak.

Group claims¶

For group-restricted projects and shared launchers, add a Group Membership mapper to the client's dedicated scope:

AntFlow reads groups only from the access token, as a list of strings; it does not use group claims from userinfo or the ID token. Use full paths such as /processing when configuring project and launcher groups. configs.oidc.groups_pathlike: true normalizes launcher group names such as processing to /processing; it does not add missing group claims to tokens.

User secrets¶

To let AntFlow retrieve encrypted user secrets, create a user-profile attribute named antflow_secrets with these settings:

For the AntFlow-compatible Keycloak secret editor, configure these attribute annotations:

Use the externally reachable API URL, including its path prefix. The URL and inline JWK are alternatives; neither should contain the private key. The custom editor must be available in your Keycloak deployment: declaring an annotation does not install it.

Use Access the API to identify the base URL. Enter the full literal certificate URL in Keycloak, not a shell variable, and use the key from the same instance users sign in to.

In the client's dedicated scope, add a User Attribute mapper:

AntFlow reads these secrets from userinfo, not from token claims. Match any custom attribute name with configs.oidc.secret_attribute.

Each attribute value is a serialized AntFlow secret with an encrypted value and RSA public-key metadata. The server decrypts it with the private JWK described below. Do not substitute plaintext credentials for these records.

To let matching user secrets override GitLab project CI/CD variables:

configs:
    secret_management:
        override_gitlab_ci_var: true

The default is false. When enabled, the server replaces a project variable with the decoded user secret whose name matches the variable name, also allowing the configured configs.gitlab.env_var_prefix (CWL__ by default) on the secret name. This setting controls user-secret precedence, not project access or token selection.

Encryption keys¶

The server uses configs.crypto for encrypting stored job data and configs.secret_management for the RSA JWK pair used to encrypt and decrypt Keycloak user secrets. The chart can generate these keys; for externally managed keys, reference existing Secrets:

configs:
    crypto:
        existingSecret: antflow-crypto
        existingSecretSecretTokenKey: crypto_secret_token
        existingSecretInitVectorKey: crypto_init_vector
    secret_management:
        existingSecret: antflow-user-secrets
        existingSecretPrivateJwkKeyKey: private_jwk_key
        existingSecretPublicJwkKeyKey: public_jwk_key

For manually provisioned crypto values, use hexadecimal strings representing 32 random bytes for the AES-256 secret and 16 random bytes for the initialization vector. The user-secret pair must be RSA JWK JSON values compatible with RSA-OAEP-256 (for example, a 2048-bit key pair). Keep private key material out of version-controlled values files.

Preserve the crypto secret and initialization vector across upgrades so
existing encrypted data remains readable. Keep the RSA private key confidential
and preserve the JWK pair when restoring the application. Include these Secrets
in your backup and recovery plan.

For Helm values, existing Secret references, and automatic key generation, see the chart README.

What's next¶

• For a new deployment, install AntFlow using the OIDC client you registered.
• For workflow repository access, review GitLab token selection and published project access.
• To restrict shared execution infrastructure to authentication groups, configure shared launchers and groups.