GitLab identity provider

PolicyArc uses GitLab as a pass-through identity provider: when a user signs in, PolicyArc redirects them to GitLab's standard OAuth flow and accepts the resulting OIDC identity.

When used with the GitLab connector in idp_passthrough mode, PolicyArc also captures the user's GitLab OAuth token and forwards it to the GitLab API. This means GitLab sees and audits the actual user making each API call, not a shared service account.

To wire this up, you'll create an OAuth application in GitLab, then hand its application ID and secret to PolicyArc.

You'll need

• Access to a GitLab instance (gitlab.com or self-hosted)
• Permission to create OAuth applications
• The PolicyArc admin portal open in another tab

Connector integration

If you plan to use the GitLab connector in per-user mode, make sure to include the api scope when creating the OAuth app. This enables PolicyArc to forward the user's token to GitLab for API calls.

---

Step 1 — Open the Add a sign-in provider form

In the Admin Portal, under Configure, select Users & Identity. On the IdPs tab, select Create.

Pick GitLab from the provider list.

Keep this tab open — you'll come back to it after you create the OAuth application in GitLab.

---

Step 2 — Create an OAuth application in GitLab

Open your GitLab instance and navigate to create an OAuth application:

• For personal use: Go to User Settings → Applications
• For group use: Go to your group → Settings → Applications
• For instance-wide (admin): Go to Admin Area → Applications

Click Add new application.

---

Step 3 — Configure the OAuth application

Fill in the application details:

1. Name: Give your application a descriptive name (e.g., PolicyArc MR-75 or PolicyArc Production)

2. Redirect URI: Copy this from the PolicyArc tab you left open in Step 1. It will look like:

   https://your-environment.example/oauth2/callback

   Exact match required

   The redirect URI must match exactly what PolicyArc shows, including the protocol (https://) and path (/oauth2/callback).

3. Confidential: Check this box — PolicyArc requires confidential clients

4. Scopes: Select the following scopes:

   • openid — Required for OIDC
   • profile — To get the user's name
   • email — To get the user's email
   • api — Required if using the GitLab connector in per-user mode
   Why the api scope?

   The api scope is only needed if you plan to use the GitLab connector with per-user authentication. It allows PolicyArc to forward the user's token to GitLab API calls. If you're only using GitLab for login, you can skip this scope.

5. Click Save application

---

Step 4 — Copy the credentials

After saving, GitLab shows you the Application ID and Secret. Copy both values — you'll need them for PolicyArc.

Save the secret now

GitLab only shows the secret once. If you lose it, you'll need to regenerate it.

---

Step 5 — Configure PolicyArc

Return to the PolicyArc tab from Step 1. Fill in the form:

1. Issuer URL: Your GitLab instance URL

   • For gitlab.com: https://gitlab.com
   • For self-hosted: https://git.yourcompany.com

2. Client ID: Paste the Application ID from GitLab

3. Client secret: Paste the Secret from GitLab

4. Scopes: The preset fills in openid email profile. Add api if you use the GitLab connector.

5. Click Add identity provider

---

What's next?

With GitLab identity configured:

• Users sign in with GitLab when policy routes them there. PolicyArc has no login page or provider chooser. pbac.operator.controls.idp_selection picks the provider for each authorization request, and the first enabled provider you add becomes default_idp. See Trust and identity.
• Install the GitLab connector — If you included the api scope, install the GitLab connector in per-user mode
• Write policies — Create rules on the user's sub and on the claims the server captures from GitLab's ID token. GitLab's OpenID Connect claims table puts groups in the userinfo response only, and puts groups_direct (direct memberships) in the ID token. With the default settings a GitLab user therefore has no input.subject.groups, and a rule that denies by group never matches them. To use GitLab groups, add groups_direct to the captured claims and write the rule on input.subject.groups_direct. Ask an outside service during a decision lists the defaults and the setting that changes them.

---

Troubleshooting

Problem	Solution
"Redirect URI mismatch" error	Ensure the URI in GitLab exactly matches what PolicyArc shows, including https:// and /oauth2/callback
"Invalid client" error	Check that you marked the application as Confidential in GitLab
Users can log in but connector gets 401	The OAuth app needs the api scope — edit it in GitLab and re-authorize
"OIDC discovery failed"	Verify the issuer URL is correct and your GitLab instance is accessible from PolicyArc

For self-hosted GitLab behind a firewall, ensure PolicyArc can reach:

• /.well-known/openid-configuration
• /oauth/authorize
• /oauth/token
• /oauth/userinfo
• /oauth/discovery/keys