Vault Authentication and Secret Management in GitFlic CI

Available in Enterprise version

Introduction

Vault is a secrets management system that provides encrypted storage with authentication and authorization controls for secure, auditable access to secrets (tokens, API keys, passwords, etc.).

Prerequisites

GitFlic account
Access to a running Vault server (v1.14-1.18) for:
Authentication setup
Role/policy creation

JWT Authentication

JWT Authentication Required

Only JWT token authentication is supported for Vault integration.

JSON Web Tokens (JWTs) enable OIDC authentication with third-party services. When a task includes JWTs, they automatically authenticate with Vault.

JWT Parameters

Parameter	Required	Description
`iss`	Mandatory	GitFlic service domain
`project_visibility`	Mandatory	Project privacy level
`ref_name`	Mandatory	Branch name
`commit_sha`	Mandatory	Commit hash
`project_path`	Mandatory	Project path
`project_name`	Mandatory	Project alias
`project_title`	Mandatory	Project title
`pipeline_source`	Mandatory	Pipeline source
`pipeline_id`	Mandatory	Pipeline ID
`sub`	Mandatory	Task ID
`user_login`	Mandatory	Task initiator username
`default_branch`	Mandatory	Default project branch
`iat`	Mandatory	Issued at timestamp
`exp`	Mandatory	Expiration timestamp
`aud`	Optional	Vault address

Example JWT:

{
  "iss": "gitflic.ru/vault",
  "project_visibility": "private",
  "ref_name": "master",
  "commit_sha": "812194e1724d03aaaaaaaaaaaa9adec3ec71f7c2",
  "project_path": "mygroup/myproject",
  "project_name": "myproject",
  "project_title": "myproject",
  "pipeline_source": "web",
  "pipeline_id": "1212",
  "sub": "1546",
  "user_login": "myuser",
  "default_branch": "master",
  "iat": 1585710286,
  "exp": 1585713886,
  "aud": "https://gitflic.ru/vault"
}

Encoded with RS256 using a rotating private key
Default 5-minute expiration (configurable per-task)

Configuration Example

1. Store Secrets in Vault

# Staging DB password
vault kv put secret/myproject/staging/db password=password

# Production DB password  
vault kv put secret/myproject/production/db password=real-password

2. Enable JWT Auth in Vault

vault auth enable jwt

3. Create Access Policies

# Staging policy
vault policy write myproject-staging - <<EOF
path "secret/data/myproject/staging/*" {
  capabilities = ["read"]
}
EOF

# Production policy  
vault policy write myproject-production - <<EOF
path "secret/data/myproject/production/*" {
  capabilities = ["read"]
}
EOF

4. Configure JWT Roles

# Staging role
vault write auth/jwt/role/myproject-staging - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-staging"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_login",
  "bound_audiences": ["http://vault.example.com:8200"],
  "bound_claims": {"user_login": "adminuser"}
}
EOF

# Production role
vault write auth/jwt/role/myproject-production - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-production"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_login",
  "bound_audiences": ["http://vault.example.com:8200"],
  "bound_claims_type": "glob",
  "bound_claims": {"user_login": "adminuser"}
}
EOF

5. Set JWT Auth Configuration

vault write auth/jwt/config \
    oidc_discovery_url="http://localhost:8080/vault" \
    bound_issuer="http://localhost:8080"

GitFlic CI/CD Integration

Required Variables

VAULT_SERVER_URL: Vault server address (e.g., https://vault.example.com:8200)
VAULT_AUTH_ROLE: Authentication role (optional)
VAULT_AUTH_PATH: Auth method mount path (default: jwt)
VAULT_NAMESPACE: Vault Enterprise namespace (optional)

Pipeline Example

job_with_secrets:
  id_tokens:
    VAULT_ID_TOKEN:
      aud: http://vault.example.com:8200
  secrets:
    STAGING_DB_PASSWORD:
      vault: secret/myproject/staging/db/password@secrets
  script:
    - access-staging-db.sh --token $STAGING_DB_PASSWORD

Access Control Methods

Vault bound_claims with group_claim
User-specific restrictions via user_login/user_email
TTL limitations with token_explicit_max_ttl
Combined JWT and branch protection rules

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies