diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index 04faa81fb..5ce9b91c5 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -169,9 +169,15 @@ Some notes on the fields of the JSON payload: - `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. +:::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`. +Please see [this note](../social-signin/oidc-pkce#forcing-pkce) if you want to enforce PKCE during OIDC for this connection. + +::: + #### 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..89a44b731 --- /dev/null +++ b/docs/kratos/social-signin/oidc-pkce.mdx @@ -0,0 +1,72 @@ +--- +id: oidc-pkce +title: PKCE for Social Sign-in +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. + +```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 +``` + +## 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`: + +```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 +``` + +:::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/#create-an-sso-connection) to use PKCE. + +::: + +## Disabling PKCE + +If for any reason you want to disable PKCE completely, set `pkce` to `never`. + +```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 +``` 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 6e753ca31..52517e38f 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -215,6 +215,7 @@ const guidesSidebar = { "kratos/social-signin/get-tokens", "identities/sign-in/social-sign-in/redirect-url", "kratos/social-signin/native-apps", + "kratos/social-signin/oidc-pkce", ], }, {