From a82a3ed406481e1640938bf6fbc2df25c2646152 Mon Sep 17 00:00:00 2001 From: Jans Rautenbach <14095706+J4NS-R@users.noreply.github.com> Date: Sat, 14 Mar 2026 09:49:46 +0000 Subject: [PATCH 1/4] Document Gitlab Pipelines OIDC client authentication Added Gitlab Pipelines section for OIDC client authentication with Pocket ID, including configuration values and an example job. --- docs/guides/oidc-client-authentication.md | 39 +++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/guides/oidc-client-authentication.md b/docs/guides/oidc-client-authentication.md index d665889..2ecdf91 100644 --- a/docs/guides/oidc-client-authentication.md +++ b/docs/guides/oidc-client-authentication.md @@ -114,3 +114,42 @@ 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. `.tail.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` - not enforced, but good practice to use the Pocket ID url 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**: Constant value `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: "https://pocketid.example.com" # must match the `Audience` configured in Pocket ID. + script: + - apk update + - apk add --no-cache curl jq + - responsefile=$(mktemp) + - | + curl -SsfX POST --url "https://pocketid.example.com/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 variable you need to define is `POCKET_ID_CLIENT_ID`, which is 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). From 2ef7de69c979dde2ec70a7f0f4ccf1c442db3d4b Mon Sep 17 00:00:00 2001 From: Jans Rautenbach <14095706+J4NS-R@users.noreply.github.com> Date: Sat, 14 Mar 2026 09:57:41 +0000 Subject: [PATCH 2/4] typo --- docs/guides/oidc-client-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/oidc-client-authentication.md b/docs/guides/oidc-client-authentication.md index 2ecdf91..a23ee66 100644 --- a/docs/guides/oidc-client-authentication.md +++ b/docs/guides/oidc-client-authentication.md @@ -124,7 +124,7 @@ Configuration values for Federated Client Credentials in Pocket ID: - **Issuer**: `https://gitlab.com` (or your self-hosted gitlab domain) - **Audience**: `https://pocketid.example.com` - not enforced, but good practice to use the Pocket ID url 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**: Constant value `https://gitlab.com/oauth/discovery/keys` - if self-hosting, replace `gitlab.com`. +- **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: From 4c371f5f804a11039e97d5f94be6185270a05f70 Mon Sep 17 00:00:00 2001 From: Jans Rautenbach <14095706+J4NS-R@users.noreply.github.com> Date: Sat, 14 Mar 2026 11:07:54 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Alessandro (Ale) Segala <43508+ItalyPaleAle@users.noreply.github.com> --- docs/guides/oidc-client-authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/oidc-client-authentication.md b/docs/guides/oidc-client-authentication.md index a23ee66..d467a44 100644 --- a/docs/guides/oidc-client-authentication.md +++ b/docs/guides/oidc-client-authentication.md @@ -121,8 +121,8 @@ When running jobs in Gitlab Pipelines, your job can authenticate as an OIDC clie Configuration values for Federated Client Credentials in Pocket ID: -- **Issuer**: `https://gitlab.com` (or your self-hosted gitlab domain) -- **Audience**: `https://pocketid.example.com` - not enforced, but good practice to use the Pocket ID url as the audience. +- **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`. From 1b2febdb8872c866f957cfb66e13e2734ebbc64b Mon Sep 17 00:00:00 2001 From: Jans Rautenbach <14095706+J4NS-R@users.noreply.github.com> Date: Sat, 14 Mar 2026 11:12:27 +0000 Subject: [PATCH 4/4] Review change: base url as variable --- docs/guides/oidc-client-authentication.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/guides/oidc-client-authentication.md b/docs/guides/oidc-client-authentication.md index d467a44..cce6947 100644 --- a/docs/guides/oidc-client-authentication.md +++ b/docs/guides/oidc-client-authentication.md @@ -134,13 +134,13 @@ example-job: image: alpine:3.23.3 id_tokens: GL_PIPELINE_TOKEN: - aud: "https://pocketid.example.com" # must match the `Audience` configured in Pocket ID. + 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 "https://pocketid.example.com/api/oidc/token" \ + 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" \ @@ -150,6 +150,8 @@ example-job: - echo "Successfully obtained token with subject: client-$POCKET_ID_CLIENT_ID" ``` -The only variable you need to define is `POCKET_ID_CLIENT_ID`, which is the client ID of the OIDC Client configured in Pocket 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).