OAuth 2.0 Device Authorization Flow is opt-in

Author: guntrip

assets/images/oauth-apps/enable-device-flow.png

@@ -52,7 +52,9 @@ topics:
 1. By default, to improve your app's security, your app will use expiring user authorization tokens. To opt-out of using expiring user tokens, you must deselect "Expire user authorization tokens". To learn more about setting up a refresh token flow and the benefits of expiring user tokens, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)."
   ![Option to opt-in to expiring user tokens during GitHub Apps setup](/assets/images/github-apps/expire-user-tokens-selection.png)
 1. If your app authorizes users using the OAuth flow, you can select **Request user authorization (OAuth) during installation** to allow people to authorize the app when they install it, saving a step. If you select this option, the "Setup URL" becomes unavailable and users will be redirected to your "User authorization callback URL" after installing the app. See "[Authorizing users during installation](/apps/installing-github-apps/#authorizing-users-during-installation)" for more information.
-![Request user authorization during installation](/assets/images/github-apps/github_apps_request_auth_upon_install.png)
+![Request user authorization during installation](/assets/images/github-apps/github_apps_request_auth_upon_install.png){% if device-flow-is-opt-in %}
+1. If your GitHub App will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
+  ![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
 1. If additional setup is required after installation, add a "Setup URL" to redirect users to after they install your app.
 ![Field for the setup URL of your GitHub App ](/assets/images/github-apps/github_apps_setup_url.png)
 

content/developers/apps/building-github-apps/creating-a-github-app.md

@@ -124,9 +124,9 @@ curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre
 
 {% endnote %}
 
-The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.
+The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager. 
 
-For more information about authorizing users using the device flow, see "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps#device-flow)".
+{% if device-flow-is-opt-in %}Before you can use the device flow to identify and authorize users, you must first enable it in your app's settings. For more information on enabling device flow, see "[Modifying a GitHub App](/developers/apps/managing-github-apps/modifying-a-github-app)." {% endif %}For more information about authorizing users using the device flow, see "[Authorizing OAuth Apps](/developers/apps/authorizing-oauth-apps#device-flow)."
 
 ## Check which installation's resources a user can access
 

content/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps.md

@@ -125,6 +125,12 @@ curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre
 
 The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.
 
+{% if device-flow-is-opt-in %}
+
+Before you can use the device flow to authorize and identify users, you must first enable it in your app's settings. For more information about enabling the device flow in your app, see "[Modifying an OAuth App](/developers/apps/managing-oauth-apps/modifying-an-oauth-app)" for OAuth Apps and "[Modifying a GitHub App](/developers/apps/managing-github-apps/modifying-a-github-app)" for GitHub Apps.
+
+{% endif %}
+
 ### Overview of the device flow
 
 1. Your app requests device and user verification codes and gets the authorization URL where the user will enter the user verification code.
@@ -254,10 +260,12 @@ If you make more than one access token request (`POST {% data variables.product.
 | `unsupported_grant_type` | The grant type must be `urn:ietf:params:oauth:grant-type:device_code` and included as an input parameter when you poll the OAuth token request `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`.
 | `incorrect_client_credentials` | For the device flow, you must pass your app's client ID, which you can find on your app settings page. The `client_secret` is not needed for the device flow.
 | `incorrect_device_code` | The device_code provided is not valid.
-| `access_denied` | When a user clicks cancel during the authorization process, you'll receive a `access_denied` error and the user won't be able to use the verification code again.
+| `access_denied` | When a user clicks cancel during the authorization process, you'll receive a `access_denied` error and the user won't be able to use the verification code again.{% if device-flow-is-opt-in %}
+| `device_flow_disabled` | Device flow has not been enabled in the app's settings. For more information, see "[Device flow](#device-flow)."{% endif %}
 
 For more information, see the "[OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628#section-3.5)."
 
+
 ## Non-Web application flow
 
 Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.

content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md

@@ -53,6 +53,8 @@ topics:
    **Note:** OAuth Apps cannot have multiple callback URLs, unlike {% data variables.product.prodname_github_apps %}.
 
    {% endnote %}
-{% endif %}
-10. Click **Register application**.
+{% endif %}{% if device-flow-is-opt-in %}
+1. If your OAuth App will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
+  ![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
+2.  Click **Register application**.
 ![Button to register an application](/assets/images/oauth-apps/oauth_apps_register_application.png)

content/developers/apps/building-oauth-apps/creating-an-oauth-app.md

@@ -18,6 +18,8 @@ topics:
 {% data reusables.user-settings.github_apps %}
 {% data reusables.user-settings.modify_github_app %}
 5. In "Basic information", modify the GitHub App information that you'd like to change.
-![Basic information section for your GitHub App](/assets/images/github-apps/github_apps_basic_information.png)
+![Basic information section for your GitHub App](/assets/images/github-apps/github_apps_basic_information.png){% if device-flow-is-opt-in %}
+1. If your GitHub App will use the device flow to identify and authorize users, click **Enable device flow**. For more information about the device flow, see "[Authorizing OAuth Apps](/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
+  ![Screenshot showing field for enabling device flow](/assets/images/oauth-apps/enable-device-flow.png){% endif %}
 6. Click **Save changes**.
 ![Button to save changes for your GitHub App](/assets/images/github-apps/github_apps_save_changes.png)

content/developers/apps/managing-github-apps/modifying-a-github-app.md

@@ -0,0 +1,5 @@
+# docs-content 6307. OAuth device auth flow is opt in.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghae: 'issue-6307'