Connections

_vale/config/vocabularies/Docker/accept.txt

@@ -319,6 +319,7 @@ Zsh
 README
 [Rr]eal-time
 [Rr]egex(es)?
+[Rr]uleset(s)?
 [Rr]untimes?
 [Ss]andbox(ed)?
 [Ss]eccomp

content/manuals/enterprise/security/_index.md

@@ -32,6 +32,10 @@ grid_admins:
     description: Configure sign-in for members of your teams and organizations.
     link: /enterprise/security/enforce-sign-in/
     icon: finger-print
+  - title: OIDC connections
+    description: Configure OpenID Connect connections for automated workload authentication.
+    link: /enterprise/security/oidc-connections/
+    icon: link
   - title: Domain management
     description: Identify uncaptured users in your organization.
     link: /enterprise/security/domain-management/

content/manuals/enterprise/security/oidc-connections/_index.md

@@ -0,0 +1,42 @@
+---
+title: OIDC connections overview
+linkTitle: OIDC connections
+description: Learn how OIDC connections let organizations authenticate workloads and control access with OpenID Connect
+keywords: oidc connections, openid connect, subject claims, rulesets, enterprise security, authentication, admin
+tags: [admin]
+weight: 35
+params:
+  sidebar:
+    badge:
+      color: blue
+      text: Beta
+---
+
+{{< summary-bar feature_name="OIDC connections" >}}
+
+OIDC connections create a trust relationship between Docker and a trusted third-party so you don't have to maintain long-lived credentials. When you create an OIDC connection, Docker exchanges short-lived tokens with another vendor that can grant fine-grained access to your Docker resources.
+
+## How OIDC connections work
+
+OIDC connections mirror implementations of the OIDC standard. Establishing a trust relationship involves creating the connection, configuring a workflow, and testing. For example, a trust relationship between Docker and GitHub follows these steps:
+
+- GitHub issues a JWT ID token for the workflow run.
+- During the authentication process, Docker then:
+  - Verifies the token against GitHub's public key registry
+  - Matches subject claims against specified rulesets created in the Admin Console.
+- Docker returns an access token, allowing the GitHub Action login to Docker to access resources.
+
+All tokens created and exchanged during an OIDC workflow are short-lived and issued on a per-workflow basis.
+
+## OIDC connections and OATs
+
+Organization access tokens (OATs) programmatically extend organization-level access to your Docker resources for all members. When membership changes in your organization, OATs ensure that access is granted or revoked without manual administrative oversight.
+
+OIDC connections don't replace OATs. Rather, OIDC connections authenticate a workflow process as if it were a user, then extend authorization after authentication.
+
+While OATs govern access to your Docker resources through organization membership, OIDC connections authenticate GitHub Actions workflows when they request a change to your Docker resources.
+
+## What's next
+
+- [Create an OIDC connection](/manuals/enterprise/security/oidc-connections/create-manage.md)
+- [OIDC connections rulesets](/manuals/enterprise/security/oidc-connections/rulesets-claims.md)

content/manuals/enterprise/security/oidc-connections/create-manage.md

@@ -0,0 +1,114 @@
+---
+title: Create and manage OIDC connections
+linkTitle: Create and manage connections
+description: Create, update, and delete OIDC connections for your organization
+keywords: oidc connections, create oidc connection, manage oidc connection, openid connect, identity provider, enterprise security, admin
+tags: [admin]
+weight: 10
+---
+
+{{< summary-bar feature_name="OIDC connections" >}}
+
+Organization owners and editors can create new OIDC connections or manage existing ones from the Admin Console in Docker Home. Establishing an OIDC connection occurs in two phases. First, you create the OIDC connection in the Admin Console, then you configure your GitHub Actions workflow YAML file.
+
+> [!NOTE]
+> GitHub is the only supported trusted third party at this time.
+
+## Connect OIDC connections to GitHub Actions
+
+### Step 1: Create the OIDC connection
+
+1. Sign in to [Docker Home](https://app.docker.com/), select your organization, then go to the **Admin Console**.
+1. In **Security**, select **OIDC connections**.
+1. Select **Create OIDC connection** to go to the creation page. Fill in the OIDC connection form.
+   - You must provide rulesets and subject claims. Other values are optional.
+   - To learn about rulesets, subject claims, and resources, see [OIDC connections rulesets and subject claims](/manuals/enterprise/security/oidc-connections/rulesets-claims.md).
+1. Select **Create connection**.
+1. Copy your OIDC connection ID.
+
+### Step 2: Define GitHub Actions workflow
+
+1. Add a top-level `permissions` key that requests a GitHub OIDC ID token:
+
+   ```yaml
+   permissions:
+     id-token: write
+   ```
+
+1. Define a job that triggers the OIDC exchange. Update `connection_id` with the connection ID you copied from Docker:
+
+   ```yaml
+   jobs:
+     login:
+       runs-on: ubuntu-latest
+       steps:
+         - name: OIDC connections
+           id: docker_oidc
+           uses: docker/oidc-action@v0
+           with:
+             connection_id: <YOUR_CONNECTION_ID>
+   ```
+
+1. Add a step that signs into Docker with an access token once ID token passes authentication:
+
+   ```yaml
+   - name: Login to Docker Hub
+     uses: docker/login-action@{{% param "login_action_version" %}}
+     with:
+       username: <DOCKER_ORGANIZATION_NAME>
+       password: ${{ steps.docker_oidc.outputs.token }}
+   ```
+
+   The `username` value must be an organization name. Personal accounts are not supported.
+
+Your updated workflow YAML should look like this:
+
+```yaml
+permissions:
+  id-token: write
+
+jobs:
+  login:
+    runs-on: ubuntu-latest
+    steps:
+      - name: OIDC connections
+        id: docker_oidc
+        uses: docker/oidc-action@v0
+        with:
+          connection_id: <YOUR_CONNECTION_ID>
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@{{% param "login_action_version" %}}
+        with:
+          username: <YOUR_ORGANIZATION_NAME>
+          password: ${{ steps.docker_oidc.outputs.token }}
+```
+
+### Step 3 (optional): Test
+
+After both phases, open the workflow run in GitHub Actions and select **Stage** to test the job.
+
+## Manage OIDC connections
+
+You can view, edit, deactivate, or delete your connections from the **OIDC connection** page.
+
+1. From the **Admin Console**, go to **OIDC connections**.
+1. From the **OIDC connections** page, find the row with your target connection ID.
+1. Select the action menu icon for your options.
+   - **Edit** opens the **Edit OIDC connection** page where you can copy your connection ID, update rulesets, or view the **Failures** table.
+   - **Deactivate** temporarily disables access to your GitHub workflow.
+   - **Activate** restores access to your GitHub workflow.
+   - **Delete** permanently deletes a connection.
+
+## Deactivation and deletion
+
+You can deactivate an OIDC connection to pause GitHub workflow access to your Docker resources without deleting the connection. While a connection is deactivated:
+
+- It cannot issue Docker access tokens.
+- Without Docker access tokens, the `docker/oidc-action` step references will fail at the token-exchange step until you activate the connection.
+
+Unlike deactivation, deleting an OIDC connection is permanent. Any workflow whose `docker/oidc-action` step still references the deleted `connection_id` will fail at the token-exchange step, so update that input with a replacement connection's id in every affected workflow before it runs again.
+
+## What's next
+
+- For reference documentation about OIDC connections rulesets and behaviors, see [OIDC connections rulesets and subject claims](/manuals/enterprise/security/oidc-connections/rulesets-claims.md)

content/manuals/enterprise/security/oidc-connections/rulesets-claims.md

@@ -0,0 +1,72 @@
+---
+title: OIDC connections rulesets and subject claims
+linkTitle: Rulesets and subject claims
+description: Configure rulesets and subject claims to control access for OIDC connections
+keywords: oidc connections, rulesets, subject claims, openid connect, token claims, access control, enterprise security, admin
+tags: [admin]
+weight: 20
+---
+
+{{< summary-bar feature_name="OIDC connections" >}}
+
+Rulesets and subject claims define what actions your GitHub workflows can take with your Docker resources. This page explains how to configure rulesets and set subject claims to authorize GitHub Workflow behaviors.
+
+## Rulesets
+
+A ruleset is a set of conditions that Docker evaluates against an incoming GitHub ID token. When a workflow triggers an OIDC exchange, Docker checks the token against every ruleset defined in your connection. If a ruleset's conditions are satisfied, Docker grants access based on the parameters set by that ruleset.
+
+Each ruleset contains the following fields:
+
+- **Label**: A name for the ruleset.
+- **Rules**: One or more conditions based on OIDC token claims, such as the repository name, branch, or workflow path.
+  - These are expressed as subject claim strings.
+  - See [Subject claims](#subject-claims).
+- **Resources**: The Docker resources a workflow can access when the ruleset matches. See [Resources](#resources).
+- **Scopes**: The permissions granted on those resources, such as read or write access.
+
+You can define between 1 and 5 rulesets per connection. Use multiple rulesets to apply different access levels across different workflows or branches.
+
+> [!TIP]
+> If more than one ruleset matches an incoming token,
+> Docker merges the resources from all matching rulesets
+> and grants access to the combined set.
+
+## Subject claims
+
+A subject claim is the `sub` field in a GitHub-issued JWT ID token. It encodes details of a workflow into a single string, identifying the workflow by organization, repository, branch, environment, and so on.
+
+Docker uses the subject claim as the primary condition when evaluating your ruleset rules. The default subject claim format is:
+
+```text
+repo:<org>/<repo>:ref:refs/heads/<branch>
+```
+
+For example:
+
+```text
+repo:octo-org/octo-repo:ref:refs/heads/main
+```
+
+The exact format varies and depends on what triggered the workflow.
+
+- A branch push, pull request, tag, or environment deployment each produces a different `sub` value.
+- Refer to [GitHub's OpenID Connect Reference](https://docs.github.com/en/actions/reference/security/oidc) for the full list of formats.
+
+You can use wildcards to match across repositories or branches:
+
+| Pattern                                        | Matches                                         |
+| :--------------------------------------------- | :---------------------------------------------- |
+| `repo:my-org/my-repo:ref:refs/heads/main`      | Only the `main` branch of a specific repository |
+| `repo:my-org/*`                                | All repos in the organization                   |
+| `repo:my-org/my-repo:ref:refs/heads/release-*` | All branches starting with `release-`           |
+
+## Resources
+
+Resources define the Docker resources a workflow can access when a ruleset matches. You specify resources per ruleset, alongside the scopes that determine the level of access granted.
+
+Docker Hub repositories and Docker Cloud are supported resources.
+
+## What's next
+
+- Learn about [OIDC connections](/manuals/enterprise/security/oidc-connections/_index.md)
+- [Create or manage OIDC connections](/manuals/enterprise/security/oidc-connections/create-manage.md)

data/summary.yaml

@@ -201,6 +201,10 @@ Docker Scout health scores:
   availability: Beta
 Docker Scout Mount Permissions:
   requires: Docker Desktop [4.34.0](/manuals/desktop/release-notes.md#4340) and later
+OIDC connections:
+  subscription: [Team, Business]
+  availability: Beta
+  for: Administrators
 Domain management:
   subscription: [Business]
   for: Administrators