Skip to content

Commit

Permalink
Add docs for CircleCI OIDC tokens
Browse files Browse the repository at this point in the history
  • Loading branch information
jacobwgillespie committed Sep 5, 2023
1 parent 225b693 commit 47b7b75
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 7 deletions.
18 changes: 16 additions & 2 deletions content/cli/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ To generate a project token, you can go through the following steps:

## OIDC trust relationships

If you use GitHub Actions or Buildkite as your CI provider, we can directly integrate with [GitHub's OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) or [Buildkite OIDC](https://buildkite.com/docs/agent/v3/cli-oidc) via trust relationships. This token exchange is a great way to plug Depot into your existing Actions workflows or Buildkite pipelines, as it requires no static secrets, and credentials are short-lived.
If you use GitHub Actions, CircleCI, or Buildkite as your CI provider, we can directly integrate with [GitHub Actions OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect), [CircleCI OIDC](https://circleci.com/docs/openid-connect-tokens/), or [Buildkite OIDC](https://buildkite.com/docs/agent/v3/cli-oidc) via trust relationships. This token exchange is a great way to plug Depot into your existing Actions workflows, CircleCI jobs, or Buildkite pipelines, as it requires no static secrets, and credentials are short-lived.

You configure a trust relationship in Depot that allows your GitHub Actions workflows or Buildkite pipelines to access your project via a token exchange. The CI job requests an access token from Depot, and we check the request details to see if they match a configured trust relationship for your project. If everything matches, we generate a temporary access token and return it to the job. This temporary access token is only valid for the duration of the job that requested it.
You configure a trust relationship in Depot that allows your GitHub Actions workflows, CircleCI jobs, or Buildkite pipelines to access your project via a token exchange. The CI job requests an access token from Depot, and we check the request details to see if they match a configured trust relationship for your project. If everything matches, we generate a temporary access token and return it to the job. This temporary access token is only valid for the duration of the job that requested it.

### Adding a trust relationship for GitHub Actions

Expand All @@ -46,6 +46,20 @@ To add a trust relationship for GitHub Actions, you can go through the following
6. Enter the name of the GitHub repository that will build images via Depot (Note: this is the repository name, not the full URL and it must match the repository name exactly)
7. Click Add trust relationship

### Adding a trust relationship for CircleCI

To add a trust relationship for CircleCI, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Click the Add trust relationship button
4. Select CircleCI as the provider
5. Enter your CircleCI organization UUID (this is found in your CircleCI organization settings)
6. Enter your CircleCI project UUID (this is found in your CircleCI project settings)
7. Click Add trust relationship

**Note:** CircleCI requires entering your organization and project UUID, _not_ the friendly name of your organization or project.

### Adding a trust relationship for Buildkite

To add a trust relationship for Buildkite, you can go through the following steps:
Expand Down
10 changes: 6 additions & 4 deletions content/integrations/circleci.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,19 @@ description: Get faster container builds with persistent caching and zero emulat

## Authentication

For CircleCI, you can use project or user access tokens for authenticating your build with Depot. We recommend using project tokens as they are scoped to the specific project and are owned by the organization.
For CircleCI, you can use, OIDC, project, or user access tokens for authenticating your build with Depot. We recommend OIDC tokens for the best experience, as they work automatically without provisioning a static access token.

**Note:** The CLI looks for the `DEPOT_TOKEN` environment variable by default. For both token options, you should configure this variable for your build environment via a [project environment variable](https://circleci.com/docs/set-environment-variable/#set-an-environment-variable-in-a-project).
### [OIDC token](/docs/cli/authentication#oidc-trust-relationships)

The easiest option is to use a [CircleCI OIDC token](https://circleci.com/docs/openid-connect-tokens/) as authentication for `depot build`. Our CLI supports authentication via OIDC by default in CircleCI when you have a trust relationship configured for your project.

### [Project token](/docs/cli/authentication#project-tokens)

You can inject a project access token into your CircleCI workflow for `depot` CLI authentication. Project tokens are tied to a specific project in your organization and not a user.
You can set the `DEPOT_TOKEN` environment variable to a project access token in your [CircleCI environment variable settings](https://circleci.com/docs/set-environment-variable/#set-an-environment-variable-in-a-project). Project tokens are tied to a specific project in your organization and not a user.

### [User access token](/docs/cli/authentication#user-access-tokens)

You can also inject a user access token into your CircleCI workflow for `depot` CLI authentication. User tokens are tied to a specific user and not a project. Therefore, it can be used to build all projects across all organizations that the user has access.
You can also set the `DEPOT_TOKEN` environment variable to a user access token in your [CircleCI environment variable settings](https://circleci.com/docs/set-environment-variable/#set-an-environment-variable-in-a-project). User tokens are tied to a specific user and not a project. Therefore, it can be used to build all projects across all organizations that the user has access.

## Configuration

Expand Down
2 changes: 1 addition & 1 deletion content/overview/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Today, Depot operates cloud infrastructure in regions that are geographically lo
Depot supports API-token-based authentication for various aspects of the application:

- **User access tokens** are used by the Depot CLI to authenticate with Depot's internal API, access resources that the user is allowed to access based on their organization memberships and roles, and can be used to initiate a build request.
- **OIDC tokens** issued by authorized third-party services can be exchanged for temporary API tokens if the Depot project has configured a trust relationship with that third party. The ephemeral API token can only access the project(s) to which the OIDC entity was granted access. Today, Depot supports creating trust relationships with GitHub Actions.
- **OIDC tokens** issued by authorized third-party services can be exchanged for temporary API tokens if the Depot project has configured a trust relationship with that third party. The ephemeral API token can only access the project(s) to which the OIDC entity was granted access. Today, Depot supports creating trust relationships with GitHub Actions, CircleCI, and Buildkite.
- **Build mTLS certificates** are used by the Depot CLI to authenticate with the builder VM — these certificates are issued for a single build in response to a successful build request and live only for the lifetime of the build.

### Software Dependencies
Expand Down

0 comments on commit 47b7b75

Please sign in to comment.