From 0f2f4abc66e98ca20fc4bcc938891496046886b4 Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Wed, 18 Nov 2026 11:40:59 -0700 Subject: [PATCH 1/2] chore: update login to mention OATs Signed-off-by: Maria Ines Parnisari --- cli/command/registry.go | 15 ++++++++------ cli/command/registry/login.go | 6 +++--- docs/reference/commandline/login.md | 32 ++++++++++++++++++++++++----- 3 files changed, 39 insertions(+), 14 deletions(-) diff --git a/cli/command/registry.go b/cli/command/registry.go index 2e767d5b72f3..60aaa8c5fcf7 100644 --- a/cli/command/registry.go +++ b/cli/command/registry.go @@ -24,9 +24,10 @@ import ( const ( registerSuggest = "Log in with your Docker ID or email address to push and pull images from Docker Hub. " + "If you don't have a Docker ID, head over to https://hub.docker.com/ to create one." - patSuggest = "You can log in with your password or a Personal Access " + - "Token (PAT). Using a limited-scope PAT grants better security and is required " + - "for organizations using SSO. Learn more at https://docs.docker.com/go/access-tokens/" + patOrOatSuggest = "You can log in with your password, a Personal Access " + + "Token (PAT), or an Organization Access Token (OAT). Using a limited-scope PAT " + + "or OAT grants better security, and a PAT is required for organizations using SSO. " + + "Learn more at https://docs.docker.com/go/access-tokens/" ) // authConfigKey is the key used to store credentials for Docker Hub. It is @@ -123,7 +124,7 @@ func PromptUserForCredentials(ctx context.Context, cli Streams, argUser, argPass // a token instead of a password. _, _ = fmt.Fprintln(cli.Out(), registerSuggest) if hints.Enabled() { - _, _ = fmt.Fprintln(cli.Out(), patSuggest) + _, _ = fmt.Fprintln(cli.Out(), patOrOatSuggest) _, _ = fmt.Fprintln(cli.Out()) } } @@ -167,8 +168,10 @@ func PromptUserForCredentials(ctx context.Context, cli Streams, argUser, argPass if serverAddress == authConfigKey { out := tui.NewOutput(cli.Err()) - out.PrintNote("A Personal Access Token (PAT) can be used instead.\n" + - "To create a PAT, visit " + aec.Underline.Apply("https://app.docker.com/settings") + "\n\n") + out.PrintNote("A Personal Access Token (PAT) or Organization Access Token (OAT) can be used instead.\n" + + "To create a PAT, visit " + aec.Underline.Apply("https://app.docker.com/settings") + "\n" + + "To create an OAT, visit " + aec.Underline.Apply("https://app.docker.com") + " and select your organization, then Identity & auth > Access tokens.\n" + + "When using an OAT, use your organization name as the username.\n\n") } argPassword, err = prompt.ReadInput(ctx, stdIn, cli.Out(), "Password: ") diff --git a/cli/command/registry/login.go b/cli/command/registry/login.go index 2b522910d800..6bd2af091a34 100644 --- a/cli/command/registry/login.go +++ b/cli/command/registry/login.go @@ -62,9 +62,9 @@ func newLoginCommand(dockerCLI command.Cli) *cobra.Command { flags := cmd.Flags() - flags.StringVarP(&opts.user, "username", "u", "", "Username") - flags.StringVarP(&opts.password, "password", "p", "", `Password or Personal Access Token (PAT), or "-" to read from stdin`) - flags.BoolVar(&opts.passwordStdin, "password-stdin", false, "Take the Password or Personal Access Token (PAT) from stdin") + flags.StringVarP(&opts.user, "username", "u", "", "Username, or organization name when using an Organization Access Token (OAT)") + flags.StringVarP(&opts.password, "password", "p", "", `Password, Personal Access Token (PAT), or Organization Access Token (OAT), or "-" to read from stdin`) + flags.BoolVar(&opts.passwordStdin, "password-stdin", false, "Take the Password, Personal Access Token (PAT), or Organization Access Token (OAT) from stdin") return cmd } diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md index 458edd7b91b0..37b4055a4d01 100644 --- a/docs/reference/commandline/login.md +++ b/docs/reference/commandline/login.md @@ -6,11 +6,11 @@ Defaults to Docker Hub if no server is specified. ### Options -| Name | Type | Default | Description | -|:---------------------------------------------|:---------|:--------|:-------------------------------------------------------------------| -| `-p`, `--password` | `string` | | Password or Personal Access Token (PAT), or `-` to read from stdin | -| [`--password-stdin`](#password-stdin) | `bool` | | Take the Password or Personal Access Token (PAT) from stdin | -| [`-u`](#username), [`--username`](#username) | `string` | | Username | +| Name | Type | Default | Description | +|:---------------------------------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------------| +| `-p`, `--password` | `string` | | Password, Personal Access Token (PAT), or Organization Access Token (OAT), or `-` to read from stdin | +| [`--password-stdin`](#password-stdin) | `bool` | | Take the Password, Personal Access Token (PAT), or Organization Access Token (OAT) from stdin | +| [`-u`](#username), [`--username`](#username) | `string` | | Username, or organization name when using an Organization Access Token (OAT) | @@ -229,6 +229,28 @@ with the username `moby`. The password is entered interactively. $ docker login -u moby ``` +### Authenticate with an organization access token (OAT) + +To authenticate to Docker Hub with an [organization access token +(OAT)](https://docs.docker.com/security/access-tokens/organization-access-tokens/), +use your organization name as the username, and the OAT in place of a +password. The following example authenticates with the organization `myorg`. +The OAT is entered interactively at the password prompt. + +```console +$ docker login --username myorg +``` + +To run the command non-interactively, provide the OAT through `STDIN`: + +```console +$ cat ~/my_oat.txt | docker login --username myorg --password-stdin +``` + +> [!NOTE] +> OATs don't work with Docker Desktop sign-in or Image Access Management. Use a +> personal access token (PAT) for those. + ### Provide a password using STDIN (--password-stdin) To run the `docker login` command non-interactively, you can set the From c2f7c16b272a2b595244093019523c0294619c22 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 20 Nov 2026 16:02:04 +0100 Subject: [PATCH 2/2] cli: simplify login credential help and documentation Shorten the login flag descriptions and hints for access tokens, and consolidate PAT and OAT authentication instructions in the CLI reference. Signed-off-by: Sebastiaan van Stijn --- cli/command/registry.go | 12 +++++----- cli/command/registry/login.go | 6 ++--- docs/reference/commandline/login.md | 34 ++++++++++++++--------------- 3 files changed, 24 insertions(+), 28 deletions(-) diff --git a/cli/command/registry.go b/cli/command/registry.go index 60aaa8c5fcf7..a949f8afed91 100644 --- a/cli/command/registry.go +++ b/cli/command/registry.go @@ -24,9 +24,9 @@ import ( const ( registerSuggest = "Log in with your Docker ID or email address to push and pull images from Docker Hub. " + "If you don't have a Docker ID, head over to https://hub.docker.com/ to create one." - patOrOatSuggest = "You can log in with your password, a Personal Access " + - "Token (PAT), or an Organization Access Token (OAT). Using a limited-scope PAT " + - "or OAT grants better security, and a PAT is required for organizations using SSO. " + + patOrOatSuggest = "You can use a personal access token (PAT) or organization access token (OAT) instead of a password. " + + "Scoped tokens improve security; a PAT is required for password-based login with SSO. " + + "When using an OAT, use your organization name as the username. " + "Learn more at https://docs.docker.com/go/access-tokens/" ) @@ -168,10 +168,8 @@ func PromptUserForCredentials(ctx context.Context, cli Streams, argUser, argPass if serverAddress == authConfigKey { out := tui.NewOutput(cli.Err()) - out.PrintNote("A Personal Access Token (PAT) or Organization Access Token (OAT) can be used instead.\n" + - "To create a PAT, visit " + aec.Underline.Apply("https://app.docker.com/settings") + "\n" + - "To create an OAT, visit " + aec.Underline.Apply("https://app.docker.com") + " and select your organization, then Identity & auth > Access tokens.\n" + - "When using an OAT, use your organization name as the username.\n\n") + out.PrintNote("You can use a personal access token (PAT) or organization access token (OAT) instead of a password.\n" + + "Learn more at " + aec.Underline.Apply("https://docs.docker.com/go/access-tokens/") + "\n\n") } argPassword, err = prompt.ReadInput(ctx, stdIn, cli.Out(), "Password: ") diff --git a/cli/command/registry/login.go b/cli/command/registry/login.go index 6bd2af091a34..ac2481835a31 100644 --- a/cli/command/registry/login.go +++ b/cli/command/registry/login.go @@ -62,9 +62,9 @@ func newLoginCommand(dockerCLI command.Cli) *cobra.Command { flags := cmd.Flags() - flags.StringVarP(&opts.user, "username", "u", "", "Username, or organization name when using an Organization Access Token (OAT)") - flags.StringVarP(&opts.password, "password", "p", "", `Password, Personal Access Token (PAT), or Organization Access Token (OAT), or "-" to read from stdin`) - flags.BoolVar(&opts.passwordStdin, "password-stdin", false, "Take the Password, Personal Access Token (PAT), or Organization Access Token (OAT) from stdin") + flags.StringVarP(&opts.user, "username", "u", "", "Username or organization name (for OATs)") + flags.StringVarP(&opts.password, "password", "p", "", `Password or access token. Use "-" to read from stdin`) + flags.BoolVar(&opts.passwordStdin, "password-stdin", false, "Read password or access token from stdin") return cmd } diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md index 37b4055a4d01..4603bb96d655 100644 --- a/docs/reference/commandline/login.md +++ b/docs/reference/commandline/login.md @@ -6,11 +6,11 @@ Defaults to Docker Hub if no server is specified. ### Options -| Name | Type | Default | Description | -|:---------------------------------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------------| -| `-p`, `--password` | `string` | | Password, Personal Access Token (PAT), or Organization Access Token (OAT), or `-` to read from stdin | -| [`--password-stdin`](#password-stdin) | `bool` | | Take the Password, Personal Access Token (PAT), or Organization Access Token (OAT) from stdin | -| [`-u`](#username), [`--username`](#username) | `string` | | Username, or organization name when using an Organization Access Token (OAT) | +| Name | Type | Default | Description | +|:---------------------------------------------|:---------|:--------|:-----------------------------------------------------| +| `-p`, `--password` | `string` | | Password or access token. Use `-` to read from stdin | +| [`--password-stdin`](#password-stdin) | `bool` | | Read password or access token from stdin | +| [`-u`](#username), [`--username`](#username) | `string` | | Username or organization name (for OATs) | @@ -229,27 +229,25 @@ with the username `moby`. The password is entered interactively. $ docker login -u moby ``` -### Authenticate with an organization access token (OAT) +### Authenticate with an access token -To authenticate to Docker Hub with an [organization access token -(OAT)](https://docs.docker.com/security/access-tokens/organization-access-tokens/), -use your organization name as the username, and the OAT in place of a -password. The following example authenticates with the organization `myorg`. -The OAT is entered interactively at the password prompt. +To authenticate to Docker Hub with a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/personal-access-tokens/) +or [organization access token (OAT)](https://docs.docker.com/security/access-tokens/organization-access-tokens/), +use the token in place of a password. + +For a PAT, use your Docker ID as the username. For an OAT, use your +organization name instead. The following example authenticates using +the organization `myorg`. The token is entered interactively. ```console $ docker login --username myorg ``` -To run the command non-interactively, provide the OAT through `STDIN`: - -```console -$ cat ~/my_oat.txt | docker login --username myorg --password-stdin -``` +To authenticate non-interactively, see [Provide a password using STDIN](#password-stdin). > [!NOTE] -> OATs don't work with Docker Desktop sign-in or Image Access Management. Use a -> personal access token (PAT) for those. +> OATs don't support Docker Desktop sign-in or Image Access Management. +> Use web-based sign-in or a PAT instead, where supported. ### Provide a password using STDIN (--password-stdin)