Skip to content

docs: Gitlab Pipelines federated OIDC client authentication #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
J4NS-R wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Gitlab Pipelines federated OIDC client authentication #239

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a82a3ed
Document Gitlab Pipelines OIDC client authentication
J4NS-R Mar 14, 2026
2ef7de6
typo
J4NS-R Mar 14, 2026
4c371f5
Apply suggestions from code review
J4NS-R Mar 14, 2026
1b2febd
Review change: base url as variable
J4NS-R Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/guides/oidc-client-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,3 +114,44 @@ Configuration values for Federated Client Credentials in Pocket ID:
- **Audience**: The value of the resource used when requesting a token from tsiam; recommended to use the endpoint of Pocket ID (e.g. `https://pocketid.example.com`)
- **Subject**: The full name of the node in the tailnet, e.g. `<node-name>.tail<tailnet-id>.ts.net`
- **JWKS URL**: Leave empty to use the default value

### Gitlab Pipelines

When running jobs in Gitlab Pipelines, your job can authenticate as an OIDC client with Pocket ID using [Gitlab ID tokens](https://docs.gitlab.com/ci/secrets/id_token_authentication/).

Configuration values for Federated Client Credentials in Pocket ID:

- **Issuer**: `https://gitlab.com` (or your self-hosted Gitlab domain)
- **Audience**: `https://pocketid.example.com` - recommended to use the Pocket ID endpoint as the audience.
- **Subject**: `project_path:my-group/my-project:ref_type:branch:ref:main` - replace `my-group/my-project` with the project you will be running the pipeline on. If working on a branch, change `main` to your branch name. Currently, wildcards are not supported, so if you need to authenticate from pipelines running on different branches, you will need to create a Federated Client Credential for each branch.
- **JWKS URL**: `https://gitlab.com/oauth/discovery/keys` - if self-hosting, replace `gitlab.com`.

Here's an example Gitlab job that authenticates as an OIDC client:

```yaml
# .gitlab-ci.yml
example-job:
image: alpine:3.23.3
id_tokens:
GL_PIPELINE_TOKEN:
aud: "$POCKET_ID_URL" # must match the `Audience` configured in Pocket ID.
script:
- apk update
- apk add --no-cache curl jq
- responsefile=$(mktemp)
- |
curl -SsfX POST --url "$POCKET_ID_URL/api/oidc/token" \
-F "grant_type=client_credentials" \
-F "client_id=$POCKET_ID_CLIENT_ID" \
-F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-F "client_assertion=$GL_PIPELINE_TOKEN" \
-o "$responsefile"
- access_token=$(jq '.access_token' -r < "$responsefile")
- echo "Successfully obtained token with subject: client-$POCKET_ID_CLIENT_ID"
```

The only variables you need to define are:
- `POCKET_ID_URL`: The base URL of your pocket ID instance, such as `https://pocketid.example.com`. In the job above this URL is also used as the Audience of the Federated Client Credential.
- `POCKET_ID_CLIENT_ID`: the client ID of the OIDC Client configured in Pocket ID.

In the job above the `client_credentials` grant type is used, which means that the final token will have a subject of the form `client-[client_id]` (as opposed to a uuid identifying a user).