From 1c23f4252d81658261c5ab1984818787221c21f3 Mon Sep 17 00:00:00 2001 From: Sam White Date: Fri, 18 Aug 2023 14:01:38 -0600 Subject: [PATCH] Add support for GitLab to docs Signed-off-by: Sam White Co-authored-by: Alishan Ladhani <8869764+aladh@users.noreply.github.com> Resolves: #215 --- content/en/about/security.md | 2 +- .../certificate_authority/oidc-in-fulcio.md | 39 +++++++++++++++++++ content/en/system_config/installation.md | 9 +++++ content/en/verifying/verify.md | 2 +- 4 files changed, 50 insertions(+), 2 deletions(-) diff --git a/content/en/about/security.md b/content/en/about/security.md index dee3d7cd..809449b6 100644 --- a/content/en/about/security.md +++ b/content/en/about/security.md @@ -10,7 +10,7 @@ The Sigstore security model has a few key components, each aimed at establishing ## Proving Identity in Sigstore -Sigstore relies on the widely used OpenID Connect (OIDC) protocol to prove identity. When running something like `cosign sign`, users will complete an OIDC flow and authenticate via an identity provider (GitHub, Google, etc.) to prove they are the owner of their account. Similarly, automated systems (like GitHub Actions) can use Workload Identity or [SPIFFE](https://spiffe.io/) Verifiable Identity Documents (SVIDs) to authenticate themselves via OIDC. The identity and issuer associated with the OIDC token is embedded in the short-lived certificate issued by Sigstore’s Certificate Authority, Fulcio. +Sigstore relies on the widely used OpenID Connect (OIDC) protocol to prove identity. When running something like `cosign sign`, users will complete an OIDC flow and authenticate via an identity provider (GitHub, GitLab, Google, etc.) to prove they are the owner of their account. Similarly, automated systems (like GitHub Actions) can use Workload Identity or [SPIFFE](https://spiffe.io/) Verifiable Identity Documents (SVIDs) to authenticate themselves via OIDC. The identity and issuer associated with the OIDC token is embedded in the short-lived certificate issued by Sigstore’s Certificate Authority, Fulcio. ## Sigstore’s Trust Model diff --git a/content/en/certificate_authority/oidc-in-fulcio.md b/content/en/certificate_authority/oidc-in-fulcio.md index fbaf8bce..317ee6a4 100644 --- a/content/en/certificate_authority/oidc-in-fulcio.md +++ b/content/en/certificate_authority/oidc-in-fulcio.md @@ -30,6 +30,18 @@ GitHub supports OIDC tokens for its workflows initiated from GitHub Actions. Thi * GitHub Actions (`token.actions.githubusercontent.com`) +GitLab supports OIDC tokens for its workflows initiated from GitLab CI/CD pipelines. This removes the need for persisting authentication credentials. OIDC tokens include information about the workflow and source repository. + +In GitLab, you can generate the necessary tokens by simply adding the following to your CI/CD job: + +```yaml +id_tokens: + SIGSTORE_ID_TOKEN: + aud: sigstore +``` + +See the [GitLab documentation](https://docs.gitlab.com/ee/ci/yaml/signing_examples.html) for full examples on signing through GitLab. + ### SPIFFE SPIFFE-based OIDC providers use a SPIFFE ID as the URI subject alternative name of the certificate, scoped to a domain. @@ -100,6 +112,33 @@ The token must include the following claims: All other required claims are extracted and included in custom OID fields, as documented in [OID Information](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md). +### GitLab + +The token must include the following claims: + +```json +{ + "namespace_id": "72", + "namespace_path": "my-group", + "project_id": "20", + "project_path": "my-group/my-project", + "pipeline_id": "574", + "pipeline_source": "push", + "job_id": "302", + "ref": "main", + "ref_type": "branch", + "runner_id": 1, + "runner_environment": "gitlab-hosted", + "sha": "714a629c0b401fdce83e847fc9589983fc6f46bc", + "project_visibility": "public", + "ci_config_ref_uri": "gitlab.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main" +} +``` + +`ci_config_ref_uri` is included as a SAN URI: `https://{ci_config_ref_uri}` + +All other required claims are extracted and included in custom OID fields, as documented in [OID Information](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#mapping-oidc-token-claims-to-fulcio-oids). + ### SPIFFE The token must include the following claims: diff --git a/content/en/system_config/installation.md b/content/en/system_config/installation.md index 2dbfe81b..d83f0b49 100644 --- a/content/en/system_config/installation.md +++ b/content/en/system_config/installation.md @@ -93,6 +93,15 @@ with: cosign-release: "v2.0.2" # optional ``` +## GitLab + +Cosign can be installed in your CI/CD pipeline by using a before script in your job: + +```yaml +before_script: + - apk add --update cosign +``` + ## Container Images Signed release images are available at [`gcr.io/projectsigstore/cosign`](http://gcr.io/projectsigstore/cosign). diff --git a/content/en/verifying/verify.md b/content/en/verifying/verify.md index 9b555dfc..390901ad 100644 --- a/content/en/verifying/verify.md +++ b/content/en/verifying/verify.md @@ -24,7 +24,7 @@ $ cosign verify --certificate-identity=name@example.com ``` -The oidc-issuer for Google is https://accounts.google.com, Microsoft is https://login.microsoftonline.com, and GitHub is https://github.com/login/oauth. +The oidc-issuer for Google is https://accounts.google.com, Microsoft is https://login.microsoftonline.com, GitHub is https://github.com/login/oauth, and GitLab is https://gitlab.com. The following example verifies the signature on file.txt from user name@example.com issued by accounts@example.com. It uses a provided bundle cosign.bundle that contains the certificate and signature.