feat: document PKCE during social sign-in (#1881)

* feat: document PKCE during social sign-in

docs/kratos/organizations/organizations.mdx

@@ -154,6 +154,7 @@ curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \
                "mapper_url": "base64://ZnVuY3Rpb24oY3R4KSBjdHg=",
                "organization_id": "6bb1c7d1-3b3e-4995-9e09-35649dc45a2b",
                "provider": "generic",
+               "pkce": "auto", # or "force", "never", see note on redirect URL below
                "scope": ["openid", "offline_access", "email"]
              }
            }
@@ -170,10 +171,21 @@ Some notes on the fields of the JSON payload:
   `$ORGANIZATION_ID` below.
 - `mapper_url` is the URL to a JSONnet file that maps the OIDC provider's claims to Ory's identity schema. You can use the
   `base64` scheme to embed the JSONnet file directly in the JSON payload.
+- `pkce` determines whether Ory Identities will use PKCE during the OIDC flow. See the note below and the
+  [PKCE documentation](../social-signin/oidc-pkce.mdx) for details.
+
+:::tip
 
 The redirect URL to be set in the external OIDC provider's configuration is
 `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/organization/$ORGANIZATION_ID/callback/$PROVIDER_ID`.
 
+If you set `pkce: force`, you must whitelist a different redirect URL with the OIDC provider:
+`https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback`.
+
+See the [PKCE documentation](../social-signin/oidc-pkce.mdx) for details.
+
+:::
+
 #### List SSO connections
 
 ```shell

docs/kratos/social-signin/oidc-pkce.mdx

@@ -0,0 +1,119 @@
+---
+id: oidc-pkce
+title: PKCE for Social Sign-in and B2B SSO
+sidebar_label: PKCE
+---
+
+Ory Identities supports the [PKCE (Proof Key for Code Exchange)](https://tools.ietf.org/html/rfc7636) extension to the OpenID
+Connect / OAuth 2.0 protocol during social sign-in flows.
+
+In most cases, you don't have to do anything to enable PKCE. If the social sign-in provider advertises support for PKCE, Ory
+Identities will automatically configure itself to use it.
+
+In the case of the [generic OIDC provider](./05_generic.mdx), simply specify an Issuer URL in the configuration as usual to
+perform automatic configuration.
+
+Retrieve the current configuration:
+
+```shell
+ory get identity-config --project $PROJECT_ID --format yaml > identity-config.yaml
+```
+
+Find the OIDC section in the `identity-config.yaml` file and add the `pkce` option:
+
+```yaml
+# ...
+selfservice:
+  methods:
+    oidc:
+      enabled: true
+      config:
+        providers:
+          - id: generic
+            provider: generic # or another provider
+            issuer_url: https://accounts.google.com # must be set to enable automatic configuration
+            pkce: auto # default: perform PKCE if the provider advertises support for it
+            # ... other configuration options
+# ...
+```
+
+Save the file, and apply the configuration:
+
+```shell
+ory update identity-config --project $PROJECT_ID --file identity-config.yaml
+```
+
+## Forcing PKCE
+
+There may be OIDC providers which support PKCE but don't advertise it. If you want to force Ory Identities to use PKCE anyway,
+configure the provider with the `pkce` option set to `force`:
+
+Retrieve the current configuration:
+
+```shell
+ory get identity-config --project $PROJECT_ID --format yaml > identity-config.yaml
+```
+
+Find the OIDC section in the `identity-config.yaml` file and add the `pkce` option:
+
+```yaml
+# ...
+selfservice:
+  methods:
+    oidc:
+      enabled: true
+      config:
+        providers:
+          - id: generic
+            provider: generic # or another provider
+            pkce: force # forces PKCE support, skips automatic configuration
+            # ... other configuration options
+```
+
+Save the file, and apply the configuration:
+
+```shell
+ory update identity-config --project $PROJECT_ID --file identity-config.yaml
+```
+
+:::warning
+
+If you set `pkce: force`, you must whitelist a different redirect URL with the OIDC provider: Instead of
+`https://<slug>.projects.oryapis.com/self-service/methods/oidc/callback/<provider-id>`, use
+`https://<slug>.projects.oryapis.com/self-service/methods/oidc/callback`. Note the missing provider ID and no trailing slash. Use
+this second URL also if you force a [B2B SSO provider](../organizations/organizations.mdx) to use PKCE.
+
+:::
+
+## Disabling PKCE
+
+If for any reason you want to disable PKCE completely, set `pkce` to `never`.
+
+Retrieve the current configuration:
+
+```shell
+ory get identity-config --project $PROJECT_ID --format yaml > identity-config.yaml
+```
+
+Find the OIDC section in the `identity-config.yaml` file and add the `pkce` option:
+
+```yaml
+# ...
+selfservice:
+  methods:
+    oidc:
+      enabled: true
+      config:
+        providers:
+          - id: generic
+            provider: generic # or another provider
+            pkce: never # do not perform PKCE even if the provider advertises support for it.
+            # ... other configuration options
+# ...
+```
+
+Save the file, and apply the configuration:
+
+```shell
+ory update identity-config --project $PROJECT_ID --file identity-config.yaml
+```

src/sidebar.js

@@ -94,6 +94,7 @@ module.exports = {
                 "kratos/social-signin/data-mapping",
                 "kratos/social-signin/account-linking",
                 "kratos/social-signin/native-apps",
+                "kratos/social-signin/oidc-pkce",
               ],
             },
             "identities/sign-in/saml",

src/sidebar.ts

@@ -221,6 +221,7 @@ const guidesSidebar = (flat: boolean): ExtendSidebar => {
                 "kratos/social-signin/get-tokens",
                 "identities/sign-in/social-sign-in/redirect-url",
                 "kratos/social-signin/native-apps",
+                "kratos/social-signin/oidc-pkce",
               ],
             },
             {