Authentication development guidelines | GitLab Docs
/ Authentication development guidelines The Authentication team owns two feature categories: System Access and User Profile . This guide covers the key topics under these categories with where to look and what to watch out for. For in-depth security knowledge about authentication and authorization at GitLab, see the Authentication & Authorization Security Knowledge Base (internal). Request flow overview All authentication flows converge on current_user : HTTP Request │ ▼ Rack Middleware (Labkit → Rack::Attack → Warden → CSRF) │ ├── Web Request ──► SessionsController / OmniauthCallbacks ──► Warden Strategies │ └── API Request ──► API::APIGuard ──► AuthFinders (token lookup) │ ▼ current_user For API requests, AuthFinders ( lib/gitlab/auth/auth_finders.rb ) checks authentication sources in this order: Deploy token Bearer token (job token, PAT, or OAuth) Job token (header or parameter) Session fallback (for web-initiated API calls) Guardrails: Do not change the token resolution order in AuthFinders .
Deploy tokens, bearer tokens, job tokens, and sessions are checked in a specific priority. Reordering can cause one token type to shadow another. Token prefixes Use token prefixes to identify token types during debugging and code review. Prefix Token type Storage glpat- Personal, project, or group access token SHA-256 digest gldt- Deploy token AES-256-GCM encrypted glcbt- CI job token AES-256-GCM encrypted gloas- OAuth application secret SHA-512 digest For a complete list of token types and storage strategies, see the Authentication & Authorization Security Knowledge Base (internal).
Sign-in and sessions Web sign-in uses Devise and Warden. Configuration is in config/initializers/8_devise.rb (the 8_ prefix controls load ordering). Where to look Purpose app/controllers/sessions_controller.rb Web login and logout. config/initializers/warden.rb Warden callbacks, session setup. app/models/active_session.rb Session tracking in Redis. app/controllers/admin/sessions_controller.rb Admin mode authentication.
Guardrails: Do not create parallel session stores. Use Devise combined with ActiveSession . Use Rack::Attack ( config/initializers/rack_attack.rb ) for login throttling. Use Gitlab::ApplicationRateLimiter for feature-level rate limits (for example, token creation, password resets). For more information, see application rate limiter . Any endpoint that validates a credential (password, token, 2FA code, recovery code) must be rate-limited.
Rate-limit keying must include the credential subject (login or user) when feasible, not only the source IP. Per-IP-only throttles that reset on success are bypassable via credential stuffing. Regenerate the session ID on any privilege change: sign-in, 2FA pass, password change, admin-mode entry. Defends against session fixation. For more information about session-based authentication, see the Authentication & Authorization Security Knowledge Base (internal).
Access tokens Personal access tokens (PATs), group access tokens, project access tokens, and service account PATs are all stored in the personal_access_tokens table and share the same authentication flow. They differ in how they are created, which user type owns them, and what authorization checks apply after authentication. Personal access tokens Where to look Purpose app/models/personal_access_token.rb PAT model, scopes, expiration validation. lib/api/personal_access_tokens.rb PAT REST API (list, revoke, rotate). app/controllers/user_settings/personal_access_tokens_controller.rb PAT UI. app/services/personal_access_tokens/ Create, revoke, rotate services.
Group and project access tokens Where to look Purpose lib/api/resource_access_tokens.rb REST API for group/project tokens. app/services/resource_access_tokens/create_service.rb Token creation with bot user provisioning. app/controllers/groups/settings/access_tokens_controller.rb Group token UI. app/controllers/projects/settings/access_tokens_controller.rb Project token UI. Service accounts Service accounts ( user_type: :service_account ) are dedicated users for external integrations and automations.
They can be provisioned at instance, group, or project level. Only instance admins can create instance-level service accounts ( app/services/users/service_accounts/create_service.rb ). Only group owners can create group-level service accounts ( app/services/namespaces/service_accounts/group_create_service.rb ). Project maintainers and above can create project-level service accounts ( app/services/namespaces/service_accounts/project_create_service.rb ).
Service accounts with composite_identity_enforced: true are excluded from seat counting. Where to look Purpose lib/api/service_accounts.rb Instance SA REST API. lib/api/group_service_accounts.rb Group SA REST API. lib/api/project_service_accounts.rb Project SA REST API. Access token guardrails Do not create ad-hoc token columns or manual hashing. Use the TokenAuthenticatable concern with add_authentication_token_field .
For more information, see Using the TokenAuthenticatable concern . Do not add new token types with insecure: true storage strategy. Use digest: true for SHA-256 digest storage or encrypted: :required for AES-256-GCM encryption at rest. For more information, see the Authentication & Authorization Security Knowledge Base (internal). MAX_PERSONAL_ACCESS_TOKEN_LIFETIME_IN_DAYS (365) is the default expiration applied when no date is provided.
It is not enforced as a cap when require_personal_access_token_expiry is disabled. Do not change token expiration logic during rotation. Token rotation must preserve the original expiration policy. Past incidents: rotating a PAT altered service account expiration dates and group membership expiration. When blocking a user, verify all active tokens are invalidated across all subsystems. Past incident: blocked user PATs continued to mint valid container registry JWTs.
Default to expiration on new token types. Do not allow token creation without an expiration unless explicitly required. Do not accept tokens via URL query parameters in new endpoints. Use PRIVATE-TOKEN header for PATs or Authorization: Bearer for OAuth. For more information about access token authentication, see the Authentication & Authorization Security Knowledge Base (internal). CI job tokens CI job tokens authenticate pipeline jobs to the GitLab API.
Where to look Purpose lib/ci/job_token/jwt.rb JWT generation and signing. lib/gitlab/auth/auth_finders.rb Job token extraction and lookup. app/models/ci/build.rb Build model, token storage (encrypted). ee/app/models/concerns/ee/ci/job_token/jwt.rb EE extensions (composite identity). Guardrails: CI job tokens are JWTs signed with RSA. Do not store them in plaintext or compare them with string equality. Job tokens are scoped to a specific pipeline job and expire with the job.
Do not extend their lifetime beyond the job duration. For more information, see the Authentication & Authorization Security Knowledge Base (internal). OAuth and OpenID Connect GitLab acts as both an OAuth provider and client. GitLab also acts as an OpenID Connect (OIDC) provider through doorkeeper-openid_connect . GitLab as OAuth and OIDC provider External applications authenticate users through GitLab using Doorkeeper.
OIDC adds an identity layer on top of OAuth, issuing ID tokens alongside access tokens. Where to look Purpose app/controllers/oauth/authorizations_controller.rb Authorization prompt and code generation. app/controllers/oauth/tokens_controller.rb Token exchange endpoint. app/models/authn/oauth_application.rb OAuth application registration. app/models/oauth_access_token.rb Access token storage (Sha512Hash). config/initializers/doorkeeper.rb Doorkeeper configuration, scopes, grant flows. config/initializers/doorkeeper_openid_connect.rb OIDC provider configuration, claims, signing keys. app/controllers/oauth/discovery_controller.rb OIDC discovery endpoint ( /.well-known/openid-confi
The rest of this page is on the live site.