Add PKCE documentation (#56506)

Co-authored-by: Sunbrye Ly <[email protected]>

Author: hpsin

content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md

@@ -42,6 +42,8 @@ If your app runs in the browser, you should use the web application flow to gene
    `client_id` | `string` | Required | The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).
    `redirect_uri` | `string` | Strongly recommended |  The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters.
    `state` | `string` | Strongly recommended |  When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data.
+{% ifversion pkce_support %}   `code_challenge` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge_method` is included. Must be a 43 character SHA-256 hash of a random string generated by the client. See the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636) for more details about this security extension.
+   `code_challenge_method` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge` is included. Must be `S256` - the `plain` code challenge method is not supported.{% endif %}
    `login` | `string` | Optional | When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app.
    `allow_signup` | `boolean` | Optional |  Whether unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
 {% ifversion oauth_account_picker %}   `prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. {% endif %}

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

@@ -64,12 +64,16 @@ This endpoint takes the following input parameters.
 | `login` | `string` | Optional| Suggests a specific account to use for signing in and authorizing the app. |
 | `scope`|`string` |Context dependent| A space-delimited list of [scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope. |
 | `state` | `string` |Strongly recommended| {% data reusables.apps.state_description %} |
+|  {% ifversion pkce_support %} |
+| `code_challenge` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge_method` is included. Must be a 43 character SHA-256 hash of a random string generated by the client. See the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636) for more details about this security extension.
+| `code_challenge_method` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge` is included. Must be `S256` - the `plain` code challenge method is not supported.
+|  {% endif %} |
 | `allow_signup`|`string` | Optional | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups. |
 |  {% ifversion oauth_account_picker %} |
 | `prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. |
 |  {% endif %} |
 
-The PKCE (Proof Key for Code Exchange) parameters `code_challenge` and `code_challenge_method` are not supported at this time. CORS pre-flight requests (OPTIONS) are not supported at this time.
+{% ifversion not pkce_support %}The PKCE (Proof Key for Code Exchange) parameters `code_challenge` and `code_challenge_method` are not supported at this time. {% endif %}CORS pre-flight requests (OPTIONS) are not supported at this time.
 
 ### 2. Users are redirected back to your site by GitHub
 
@@ -87,6 +91,9 @@ Parameter name | Type | Required?| Description
 `client_secret` | `string` | Required | The client secret you received from {% data variables.product.github %} for your {% data variables.product.prodname_oauth_app %}.
 `code` | `string` | Required | The code you received as a response to Step 1.
 `redirect_uri` | `string` | Strongly recommended | The URL in your application where users are sent after authorization. We can use this to match against the URI originally provided when the `code` was issued, to prevent attacks against your service.
+|  {% ifversion pkce_support %} |
+`code_verifier` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge` was sent during the user authorization. Must be the original value used to generate the `code_challenge` in the authorization request. This can be stored in a cookie alongside the `state` parameter or in a session variable during authentication, depending on your application architecture.
+|  {% endif %} |
 
 By default, the response takes the following form:
 

data/features/pkce_support.yml

@@ -0,0 +1,5 @@
+# Reference: github/docs-content#18773
+# Support for PKCE in GitHub Apps and OAuth apps
+versions:
+  fpt: '*'
+  ghec: '*'

data/reusables/apps/web-app-flow-exchange-code.md

@@ -6,4 +6,5 @@
    `client_secret` | `string` | **Required.** The client secret for your {% data variables.product.prodname_github_app %}. You can generate a client secret on the settings page for your app.
    `code` | `string` | **Required.** The code you received in the previous step.
    `redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" when setting up your {% data variables.product.prodname_github_app %} and can't contain any additional parameters.
+{% ifversion pkce_support %}   `code_verifier` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge` was sent during the user authorization. Must be the original value used to generate the `code_challenge` in the authorization request. This can be stored in a cookie alongside the `state` parameter or in a session variable during authentication, depending on your application architecture.{% endif %}
    `repository_id` | `string` | The ID of a single repository that the user access token can access. If the {% data variables.product.prodname_github_app %} or user cannot access the repository, this will be ignored. Use this parameter to restrict the access of the user access token further.