From ede3e33ca57133537388d067eff68808208de70f Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Thu, 13 Aug 2026 17:51:57 +0300 Subject: [PATCH] procedures: add Device Auth Tokens documentation Documents the Device Auth Tokens tab in User Preferences introduced in eclipse-che/che-dashboard#1633. New article (connecting-to-github-using-device-authorization.adoc): - Connect to GitHub using the device authorization flow (RFC 8628) - Reconnect to replace a revoked or expired token in-place - Delete a single token or multiple tokens in bulk - Troubleshooting for expired one-time codes Updated admin procedure (proc_setting-up-the-github-oauth-app.adoc): - Optional steps to enable Device Flow on the GitHub OAuth App - Step to create the device-auth-config ConfigMap that enables the Connect to GitHub button in the Dashboard Updated assembly (configuring-oauth-2-for-github.adoc): - NOTE for admins who already configured the OAuth App and want to enable Device Auth Tokens without repeating the full setup Navigation: added the new article under Using credentials and configurations in workspaces > Mounting secrets. Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../pages/configuring-oauth-2-for-github.adoc | 5 ++ .../proc_setting-up-the-github-oauth-app.adoc | 17 ++++ modules/end-user-guide/nav.adoc | 1 + ...-to-github-using-device-authorization.adoc | 88 +++++++++++++++++++ 4 files changed, 111 insertions(+) create mode 100644 modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc index ed1587a8fb..e1d1dafccb 100644 --- a/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc +++ b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc @@ -12,6 +12,11 @@ To enable users to work with a remote Git repository that is hosted on GitHub: . Set up a link:https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#about-github-apps[GitHub App] or a link:https://docs.github.com/en/apps/oauth-apps/using-oauth-apps[OAuth App]. . Apply the GitHub App or OAuth App Secret. +[NOTE] +==== +If you previously configured a GitHub OAuth App and want to enable Device Auth Tokens for users, also enable Device Flow as described in <>. +==== + include::partial$proc_setting-up-the-github-oauth-app.adoc[leveloffset=+1] include::partial$proc_setting-up-the-github-app.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc index 9c5bd0204b..f561754bbe 100644 --- a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc +++ b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc @@ -32,6 +32,23 @@ Set up a GitHub OAuth App using OAuth 2.0. . Copy and save the *GitHub OAuth Client Secret* for use when applying the GitHub OAuth App Secret. +. *(Optional)* Scroll to the *Device flow* section and select the *Enable Device Flow* checkbox. ++ +NOTE: Enable this option to allow users to connect their GitHub accounts from the {prod-short} Dashboard using *User Preferences > Device Auth Tokens*. See xref:end-user-guide:connecting-to-github-using-device-authorization.adoc[]. + +. If you selected *Enable Device Flow*, click *Update application*. + +. If you enabled Device Flow, apply the `device-auth-config` ConfigMap in the {prod-short} namespace to expose the OAuth App client ID to the Dashboard: ++ +[source,terminal,subs="+quotes,+attributes"] +---- +$ {orch-cli} create configmap device-auth-config \ + --from-literal=github_client_id=____ \ + -n {prod-namespace} +---- ++ +NOTE: When this ConfigMap is present, the *Connect to GitHub* button appears in *User Preferences > Device Auth Tokens*. Delete the ConfigMap to hide the button. + .Additional resources * link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App] diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 28bc8bf1b6..168ab7cd1f 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -40,6 +40,7 @@ ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] *** xref:get-started-user:using-a-git-provider-access-token.adoc[] +*** xref:connecting-to-github-using-device-authorization.adoc[] ** xref:mounting-configmaps.adoc[] *** xref:mounting-git-configuration.adoc[] *** xref:mounting-ssh-configuration.adoc[] diff --git a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc new file mode 100644 index 0000000000..2c4d06323a --- /dev/null +++ b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc @@ -0,0 +1,88 @@ +:_content-type: PROCEDURE +:description: Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. +:keywords: user-guide, github, device-authorization, device-auth, token, oauth +:navtitle: Connecting to GitHub using device authorization + +[id="connecting-to-github-using-device-authorization"] += Connecting to GitHub using device authorization + +[role="_abstract"] +Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. Device Auth Tokens are GitHub OAuth tokens stored as {kubernetes} Secrets. They enable Git operations in your workspaces without requiring a personal access token. + +.Prerequisites + +* Your administrator has configured a GitHub OAuth App with Device Flow enabled as described in xref:administration-guide:configuring-oauth-2-for-github.adoc[Configuring OAuth 2.0 for GitHub]. ++ +NOTE: This feature requires the GitHub OAuth App configuration. It is not available when GitHub authentication is configured using a GitHub App. + +.Procedure + +. In the {prod-short} dashboard, go to *User Preferences > Device Auth Tokens*. + +. Click *Connect to GitHub*. ++ +A modal opens displaying a one-time code. + +. Click the copy button next to the code to copy it to your clipboard. + +. Click link:https://github.com/login/device[github.com/login/device] to open the GitHub device activation page. ++ +NOTE: For GitHub Enterprise Server, replace `github.com` with your instance hostname. + +. Paste the one-time code on the GitHub page and click *Continue*. + +. Authorize the application when prompted by GitHub. ++ +NOTE: The permissions granted are determined by the OAuth App configuration set by your administrator. ++ +After successful authorization, the modal closes and the new token appears in the *Device Auth Tokens* table. + +.Verification + +* Verify that the new token is listed in the *Device Auth Tokens* table with a valid status. + +[id="reconnecting-to-github"] +== Reconnecting to GitHub + +Use *Reconnect* when a token has been revoked or has expired on the GitHub side. Reconnecting starts a new device authorization flow and replaces the existing token in-place, preserving any labels on the {kubernetes} Secret. + +.Procedure + +. In the {prod-short} dashboard, go to *User Preferences > Device Auth Tokens*. +. Click the actions menu (*⋮*) on the token row and click *Reconnect*. +. Complete the device authorization steps in the *Procedure* section above, starting from step 2. + +.Verification + +* Verify that the token card shows a valid status after reconnecting. + +[id="deleting-device-auth-tokens"] +== Deleting device auth tokens + +Deleting a device auth token removes the {kubernetes} Secret and revokes the GitHub authorization. Device Auth Tokens do not expire automatically. To disconnect your GitHub account, delete the token from this page or revoke access from your GitHub account settings. + +.Procedure + +. To delete a single token: +.. Click the actions menu (*⋮*) on the token row. +.. Click *Delete*. +.. Select the confirmation checkbox and click *Delete*. + +. To delete multiple tokens: +.. Select the checkboxes next to the tokens you want to delete. +.. Click *Delete* in the toolbar. +.. Select the confirmation checkbox and click *Delete*. + +.Verification + +* Verify that the deleted token no longer appears in the *Device Auth Tokens* table. + +[id="troubleshooting-device-auth-tokens"] +== Troubleshooting + +If the one-time code expires before you complete the authorization on GitHub (codes expire after approximately 15 minutes), close the modal and click *Connect to GitHub* again to start a new device authorization flow. + +.Additional resources + +* xref:administration-guide:configuring-oauth-2-for-github.adoc[] +* For an alternative Git authentication method, see xref:get-started-user:using-a-git-provider-access-token.adoc[].