OpenID Connect signing
This document explains how identity-based, or "keyless" signing works in Sigstore.
To learn more about OIDC, please review OIDC Usage in Fulcio.
Keyless signing associates identities, rather than keys, with an artifact signature. Fulcio issues short-lived certificates binding an ephemeral key to an OpenID Connect identity. Signing events are logged in Rekor, a signature transparency log, providing an auditable record of when a signature was created.
See the Fulcio repository and Rekor repository for more information.
Root of Trust
Sigstore's root of trust, which includes Fulcio's root CA certificate and Rekor's public key, are distributed by The Update Framework (TUF). TUF is a framework to provide secure software and file updates. TUF defines a set of protocols to protect against various types of attacks. For more information about how Sigstore uses TUF, see How Sigstore uses TUF.
Cosign supports two OAuth flows today: the standard flow and the device flow.
When there is no terminal attached (non-interactive mode), Cosign will automatically use the device flow where a link is printed to stdout. This link must be opened in a browser to complete the flow.
In automated environments, Cosign also supports directly using OIDC Identity Tokens from specific issuers. These can be supplied on the command line with the
--identity-token flag. The
audiences claim in the token must contain
Logging in to identity issuers
To log in and set up your OIDC Identity, follow these steps:
- Follow the link that Cosign provides to the Issuer login page.
- Log in to one of the supported systems that is shown:
3. Go back to your terminal or other application. Redirection back to Cosign is seamless.
Currently, Sigstore supports Microsoft, Google, and GitHub. As an alternative, you can also use the environment variable
SIGSTORE_ID_TOKEN to identify yourself by setting its value to that of the identity token. Cosign also has support for detecting some of these automated environments and producing an identity token. Currently this supports Google and GitHub, in addition to other environments. See Cosign's providers for a complete list.
On Google Cloud Platform
From a Google Cloud Engine (GCE) virtual machine, you can use the VM's service account identity to sign an image:
$ cosign sign --identity-token=$( gcloud auth print-identity-token \ --audiences=sigstore) \ gcr.io/user-vmtest2/demo
From outside a GCE VM, you can impersonate a GCP IAM service account to sign an image:
$ cosign sign --identity-token=$( gcloud auth print-identity-token \ --audiences=sigstore \ --include-email \ --impersonate-service-account email@example.com) \ gcr.io/user-vmtest2/demo
In order to impersonate an IAM service account, your account must have the
Note: On Google Cloud Build, standard identity tokens are not supported through the GCE metadata server. Cosign has a special flow for this case, where you can instruct the Cloud Build service account to impersonate another service account. To configure this flow:
- Create a service account to use for signatures (the email address will be present in the certificate subject).
- Grant the Cloud Build service account the
roles/iam.serviceAccountTokenCreatorrole for this target account.
- Set the
GOOGLE_SERVICE_ACCOUNT_NAMEenvironment variable to the name of the target account in your cloudbuild.yaml
- Sign images in GCB, without keys!
If you're running your own sigtore services flags are available to set your own endpoint's, e.g
cosign sign --oidc-issuer "https://oauth2.example.com/auth" \ --fulcio-url "https://fulcio.example.com" \ --rekor-url "https://rekor.example.com" \ ghcr.io/jdoe/somerepo/testcosign
Custom roots of trust
For information on custom roots of trust, see Configuring Cosign with Custom Components.