diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index 8df48b82a..a8b994750 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/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 diff --git a/docs/kratos/social-signin/oidc-pkce.mdx b/docs/kratos/social-signin/oidc-pkce.mdx new file mode 100644 index 000000000..a0c6501a6 --- /dev/null +++ b/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://.projects.oryapis.com/self-service/methods/oidc/callback/`, use +`https://.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 +``` diff --git a/src/sidebar.js b/src/sidebar.js index 790f43e21..b02dd6902 100644 --- a/src/sidebar.js +++ b/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", diff --git a/src/sidebar.ts b/src/sidebar.ts index dc7780e14..395f047ff 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -215,6 +215,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", ], }, {