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..ef7d28423c 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,12 @@ 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*. + .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..6cbd6b4f98 --- /dev/null +++ b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc @@ -0,0 +1,73 @@ +:_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="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[].