Authentication and Reading Secrets in StarVault via GitFlic CI

Feature available in Enterprise version

Prerequisites

To work with StarVault, you need: - A GitFlic account - Access to a running StarVault server (version 1.4.0) for configuring authentication, as well as for creating roles and policies

Enabling JWT Authorization in StarVault

First, enable the JWT authentication method in StarVault. On the server where it is deployed, run:

# Enable JWT auth method (mounted at /auth/jwt by default)
starvault auth enable jwt

Configuring the Authentication Method

Now configure the authentication method so that StarVault trusts your GitFlic domain. Run the following commands:

starvault write auth/jwt/config \
  jwks_url="https://<your-gitflic-domain>/vault/oauth/discovery/keys" \
  bound_issuer="https://<your-gitflic-domain>"

Configuring Access Policies

Prepare access policies for your secrets. These policies determine which secrets you can access from GitFlic.

First, create a policy configuration file:

# myproj.hcl
path "kv/my/super/duper/secret/*" {
  capabilities = ["read", "list"]
}

Now apply the policy in StarVault:

starvault policy write myproj myproj.hcl

Alternatively, you can skip creating a separate file and use a heredoc instead.

Configuring a Role Linked to the Policy

A role links the JWT token to the secret access policy:

starvault write auth/jwt/role/myproject - <<EOF
{
   "role_type": "jwt",
   "user_claim": "user_login",
   "token_policies": "myproj",
   "bound_audiences": ["https://<your-starvault-domain>"],
   "bound_claims": {
     "project_name": ["gitflic", "devops"]
   },
   "bound_claims_type": "glob"
}
EOF

Here we define which projects will be able to access the secrets defined in the policy.

Preparing the Project in GitFlic

In GitFlic, create CI/CD variables to connect to StarVault. To do this, open the following tabs in the web interface: Project → Settings → CI/CD Settings

And create the following variables: | Variable | Description | |----------|-------------| | VAULT_AUTH_ROLE | Role used for authentication | | VAULT_SERVER_URL | Address of the StarVault server |

Alternatively, these can be specified directly in the CI/CD pipeline file.

Using Secrets from StarVault in GitFlic CI

Accessing StarVault to retrieve secrets from a GitFlic pipeline looks like this:

job_with_secrets:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: <your-starvault-domain>
  secrets:
    USERNAME:
      vault: kv/my/super/duper/secret/super_duper_login@kv
    PASSWORD:
      vault: kv/my/super/duper/secret/super_duper_pass@kv
  script:
    - echo "$USERNAME $PASSWORD" # Don't do this in production, example only!

⚠️ Security Note: Never log or echo sensitive values like passwords in pipeline scripts. Use them directly in commands that require authentication.