GitLab OIDC Provider
You set up a gitlab oidc provider to let external apps and cloud roles trust GitLab logins. GitLab issues a signed web token that proves who the user or job is. Teams often use this flow to replace static passwords in build pipelines and internal tools. They map a GitLab group or project to a target role in the cloud. Still, teams often grant broad permissions to that role so builds do not break. Once a job or developer logs in, that broad role allows too many actions. How a gitlab oidc provi
GitLab CI Security + K8s OIDC Authentication: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up a gitlab oidc provider to let external apps and cloud roles trust GitLab logins. GitLab issues a signed web token that proves who the user or job is.
Teams often use this flow to replace static passwords in build pipelines and internal tools. They map a GitLab group or project to a target role in the cloud. Still, teams often grant broad permissions to that role so builds do not break. Once a job or developer logs in, that broad role allows too many actions.
How a gitlab oidc provider works
OpenID Connect is an identity layer built on top of the OAuth protocol. When you use GitLab as the identity source, it acts as the central trust authority. External apps and cloud platforms ask GitLab to verify a user or a pipeline job.
The process starts when a user or job tries to log in to a target service. The target service redirects the request to GitLab, or the job requests a token directly. GitLab checks the identity of the user or the context of the running build job.
Next, GitLab creates a JSON Web Token and signs it with a private cryptographic key. This token contains claims, which are facts about the user, group, project, or git branch. The target service fetches the public keys from GitLab to check that signature.
If the signature matches and the claims meet the rules, the service grants a session. For user logins, you register the external app inside GitLab to get a client ID. For pipeline jobs, you set up the target cloud role to trust the GitLab issuer URL.
Scoping claims for users and build jobs
A signature check alone is not enough to keep your systems safe. Any project on the same GitLab instance shares the same public signing keys. If your target service only checks the issuer URL, any project could assume your role.
You must configure the target service to check the subject and audience claims inside the token. The audience claim shows which app or cloud service the token was made for. The subject claim identifies the exact project path, branch, or user account making the request.
GitLab CI Security + K8s OIDC Authentication: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Good claim rules restrict high-trust roles to protected branches in a single project. Lower-trust roles can allow feature branches to run basic tests in a sandbox account. For human logins, you can check group membership claims before granting an admin role.
What native identity setup solves and what it misses
Using GitLab for OpenID Connect removes the need to store long-lived secrets in pipeline variables. You no longer need to rotate static cloud keys or share passwords across developer teams. It gives you a clean way to verify who is asking to log in.
Still, an identity check only controls the front door at the start of a session. Once the target service accepts the token, the user or job holds a full role. The OpenID Connect flow cannot see or control what happens inside that active session.
A pipeline job with database permissions could run a bad script that drops a table. An engineer who logs in through GitLab could query customer tables and export sensitive records. Native identity claims cannot inspect individual SQL queries, terminal commands, or API calls in flight.
Standard login logs only show that a user or job traded a token for a role. They do not record which specific commands ran or which rows came back. Also, native role mappings cannot rewrite sensitive fields like emails or card numbers in query results.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.
First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
What is the difference between OIDC for users and OIDC for pipelines?
User login uses a browser redirect so a person can sign in to an external app. Pipeline OIDC issues a signed job token directly to a runner to assume cloud roles.
Why must I filter the subject claim in my cloud role trust rule?
All projects on a GitLab instance share the same token issuer address. Filtering the subject claim ensures only your specific project and branch can assume that cloud role.
Does a gitlab oidc provider control which database queries a user can run?
No, it only verifies identity at login time and hands off to the target system. It does not inspect commands, block dangerous queries, or rewrite emails and phone numbers in results.