diff --git a/agent-identity/skyfire/README.md b/agent-identity/skyfire/README.md index 4d25809..67896b8 100644 --- a/agent-identity/skyfire/README.md +++ b/agent-identity/skyfire/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Community contributors -[Skyfire](https://skyfire.xyz) is an AI-agent identity and payment platform — "Know Your Agent" (KYA) verification for autonomous agents. Integrate with Ory Hydra (OAuth2 issuance) and Ory Kratos (identity records) so AI agents authenticate to your APIs with verifiable identity and per-agent spend controls. +[Skyfire](https://skyfire.xyz) is an AI-agent identity and payment platform — "Know Your Agent" (KYA) verification for autonomous agents. Integrate with Ory Hydra (OAuth2 token issuance) so AI agents authenticate to your APIs with verifiable identity and per-agent spend controls. **Type:** config (OAuth2 client + identity-mapping pattern — no first-party handler) **Docs page:** [ory.com/docs/integrates-with/agent-identity/skyfire](https://www.ory.com/docs/integrates-with/agent-identity/skyfire) @@ -10,9 +10,9 @@ ## How it works 1. Skyfire issues each AI agent a verifiable credential + a Skyfire-managed identity. -2. Your application accepts Skyfire-issued credentials, then provisions a corresponding identity in Ory Kratos (one per agent) with `metadata_public.skyfire = { agent_id, kya_status }`. -3. Ory Hydra issues OAuth2 access tokens to the agent identity using standard `client_credentials` flow; the access token's `sub` is the Kratos identity id. -4. Backend APIs validate the access token at the gateway (see [`api-gateways/*`](../../api-gateways/)) and read the agent id from `metadata_public.skyfire.agent_id` if access control needs it. +2. Your application accepts Skyfire-issued credentials, then registers a corresponding OAuth2 client in Ory Hydra (one per agent) and stores the Skyfire details in the client's `metadata`, for example `{ "skyfire": { "agent_id": "...", "kya_status": "..." } }`. +3. The agent gets access tokens with the `client_credentials` grant. In these tokens, `sub` is the OAuth2 client ID, not an identity ID. +4. Backend APIs validate the access token at the gateway (see [`api-gateways/*`](../../api-gateways/)) and map `sub` to the Skyfire agent, for example by reading the client's `metadata` with `GET /admin/clients/{id}`. To put the agent ID into the token instead, add it as a claim with an [OAuth2 token webhook](https://www.ory.com/docs/hydra/guides/claims-at-refresh). 5. Payment / spend controls stay on the Skyfire side. ## Setup outline @@ -20,15 +20,14 @@ 1. Sign up at Skyfire; create an agent and obtain its credentials. 2. Build a small provisioning service that: - Accepts Skyfire credentials from the agent. - - Creates / looks up a Kratos identity keyed by Skyfire's agent ID. - - Creates an Ory Hydra OAuth2 client (or reuses one) scoped to the agent's permissions. -3. The agent uses standard OAuth2 client-credentials flow against Hydra to obtain access tokens for API calls. + - Creates (or looks up) the agent's Ory Hydra OAuth2 client, scoped to the agent's permissions, with the Skyfire agent ID in the client `metadata`. +3. The agent uses the standard OAuth2 client-credentials flow against Hydra to obtain access tokens for API calls. ## Notable - Agent-identity is an emerging space — patterns are still firming up; this integration is a reference architecture more than a turnkey product. -- Treat each agent as a distinct Kratos identity (not as a "user with multiple agents") so audit trails and revocation work cleanly. -- KYA verification status should be re-checked periodically — Skyfire can revoke agents and your code should respect that on token issuance. +- Treat each agent as a distinct OAuth2 client (not as a "user with multiple agents") so audit trails and revocation work cleanly. +- KYA verification status should be re-checked periodically — Skyfire can revoke agents and your code should respect that on token issuance. The OAuth2 token webhook runs on every token request and can deny it with a `403` response. ## Status diff --git a/agent-identity/skyfire/registry.entry.yaml b/agent-identity/skyfire/registry.entry.yaml index 1752696..1588587 100644 --- a/agent-identity/skyfire/registry.entry.yaml +++ b/agent-identity/skyfire/registry.entry.yaml @@ -10,17 +10,17 @@ maintainedBy: Community contributors description: >- Pair Skyfire's "Know Your Agent" (KYA) verification with Ory for AI-agent identity — Skyfire issues verifiable credentials per agent; a customer-built provisioning service maps each Skyfire agent to an Ory - Kratos identity, and Hydra issues OAuth2 access tokens (client_credentials) for the agent to call APIs. + Hydra OAuth2 client, and Hydra issues OAuth2 access tokens (client_credentials) for the agent to call APIs. useCase: >- A product running autonomous AI agents that need to authenticate to backend APIs wants the agents to have verifiable identity (so the call site can answer "which agent is this and is it KYA-verified") plus per-agent spend controls — patterns that combining Skyfire and Ory makes natural. coreFunctionality: |- - - Each agent = one Kratos identity (not one user with multiple agents) — keeps audit and revocation clean. - - metadata_public.skyfire stores agent_id + kya_status on the Kratos identity. - - Ory Hydra issues access tokens via client_credentials; sub = Kratos identity id. - - API gateways validate tokens at the edge (see api-gateways/*) and can read metadata_public.skyfire.agent_id for access control. - - Skyfire can revoke agents — periodically re-check KYA status before token issuance to respect revocations. + - Each agent = one Hydra OAuth2 client (not one user with multiple agents) — keeps audit and revocation clean. + - The client's metadata stores skyfire.agent_id + kya_status. + - Ory Hydra issues access tokens via client_credentials; sub = the OAuth2 client ID. + - API gateways validate tokens at the edge (see api-gateways/*) and map sub to the agent via the client's metadata, or read an agent ID claim added by an OAuth2 token webhook. + - Skyfire can revoke agents — re-check KYA status on token issuance; the OAuth2 token webhook runs on every token request and can deny it with 403. - Payment / spend controls stay on the Skyfire side. - Status: community/proposed — emerging space, reference architecture more than turnkey product. oryMechanism: diff --git a/agent-identity/tetrate/README.md b/agent-identity/tetrate/README.md index a7c8a2c..2bb3ca3 100644 --- a/agent-identity/tetrate/README.md +++ b/agent-identity/tetrate/README.md @@ -11,7 +11,7 @@ Two layers, each owning a distinct concern: -1. **Authorization / policy layer (Ory)** — decides what an agent or user may access at the resource level. AI agents are first-class identities authenticated through Ory; Hydra issues OAuth2/OIDC tokens (`client_credentials`), and Keto holds the fine-grained policies. +1. **Authorization / policy layer (Ory)** — decides what an agent or user may access at the resource level. Each AI agent is an OAuth2 client in Ory Hydra and gets tokens with the `client_credentials` grant. In these tokens, `sub` is the client ID, so policies in Ory Keto refer to the agent by its client ID. An agent that acts for a user needs a flow with user consent, such as the authorization code flow, so that the token's `sub` identifies the user. For delegated requests, identify the agent from the validated access token's `client_id` claim and check both the agent's and the user's permissions. 2. **Network / gateway layer (Tetrate)** — enforces those policies on live traffic when agents call models, tools, and enterprise services. When an agent invokes an MCP tool, Tetrate Agent Router Enterprise evaluates the request against the Ory-defined policies. Because enforcement is parameter-level, Tetrate can gate **not only which tools** an agent may use **but also which request parameters** are allowed, based on policies defined in Ory Keto. @@ -29,7 +29,7 @@ For example: an agent processes routine refunds automatically but requires appro ## Notable - Tetrate Agent Router Enterprise is built on **Envoy AI Gateway** — see [`api-gateways/envoy`](../../api-gateways/envoy/) for the underlying pattern of validating Ory tokens at the edge. -- Closely related to [`agent-identity/skyfire`](../skyfire/): both treat AI agents as first-class Ory identities, differing in where verification and enforcement sit. +- Closely related to [`agent-identity/skyfire`](../skyfire/): both model AI agents as OAuth2 clients in Ory Hydra, differing in where verification and enforcement sit. - Agent-identity is an emerging space — this integration reflects an announced partnership and is a reference architecture rather than a turnkey product. ## Status diff --git a/agent-identity/tetrate/registry.entry.yaml b/agent-identity/tetrate/registry.entry.yaml index 2e58360..0ab5ad5 100644 --- a/agent-identity/tetrate/registry.entry.yaml +++ b/agent-identity/tetrate/registry.entry.yaml @@ -20,7 +20,7 @@ useCase: >- for sensitive data. coreFunctionality: |- - Two-layer architecture: Ory is the authorization/policy layer (what an agent or user may access at the resource level); Tetrate Agent Router Enterprise is the network/gateway layer that enforces policy on live traffic. - - Agents are first-class identities authenticated through Ory; Hydra issues OAuth2/OIDC tokens via client_credentials. + - Each agent is a Hydra OAuth2 client using client_credentials, so the token's sub is the client ID and Keto policies refer to that ID; agents acting for a user use a consented flow (e.g. authorization code), where sub is the user and the agent is the token's client_id. - Authorization policies defined in Ory Keto; Tetrate evaluates each agent request (tool call + request parameters) against them at the point an agent invokes an MCP tool. - Parameter-level enforcement: Tetrate can gate not just which tools an agent may use but which request parameters are allowed, based on Keto policies. - Step-up auth: requests exceeding a risk threshold can pause, trigger an authentication/approval flow through Ory, and issue short-lived elevated access. diff --git a/directory-sync/bamboohr/README.md b/directory-sync/bamboohr/README.md index f81e195..0c3529a 100644 --- a/directory-sync/bamboohr/README.md +++ b/directory-sync/bamboohr/README.md @@ -2,22 +2,23 @@ > **Maintained by:** Community contributors -[BambooHR](https://bamboohr.com) is an HRIS popular with SMB and mid-market companies. This integration enriches Ory identities with employee data from BambooHR via an Ory Action webhook on login or registration, returning `{ employed, employee_id, job_title, department, hire_date }` so a post-flow Action can gate access on employment status or write the fields into identity metadata. +[BambooHR](https://bamboohr.com) is an HRIS popular with SMB and mid-market companies. This integration checks employment status in BambooHR from an Ory Action webhook on login or registration, and blocks the flow when the user isn't an active employee. **Type:** webhook (Ory Action calls a handler during a flow) **Docs page:** [ory.com/docs/integrates-with/directory-sync/bamboohr](https://www.ory.com/docs/integrates-with/directory-sync/bamboohr) ## Use case -A company runs internal SaaS for employees and wants login to gate on employment status — off-boarded employees automatically lose access without a separate deprovision step. BambooHR is the HRIS source of truth; the integration looks up the user's BambooHR employee record at login and returns the employment flag so Ory can fail the flow on `employed: false`. +A company runs internal SaaS for employees and wants login to gate on employment status — off-boarded employees automatically lose access without a separate deprovision step. BambooHR is the HRIS source of truth; the integration looks up the user's BambooHR employee record at login and blocks the sign-in when there is no active record. ## How it works 1. A user logs in (or registers) through an Ory flow. 2. Ory fires the sync Action webhook to this handler. The handler verifies the shared secret. 3. The handler calls `GET /employees/directory` and filters by `workEmail` (BambooHR lacks a direct lookup-by-email API). -4. On match, the handler calls `GET /employees/?fields=status,jobTitle,department,hireDate,terminationDate` and returns `{ employed: status === "Active", employee_id, job_title, department, hire_date }`. -5. On no match, the handler returns `{ employed: false }` so Ory can decide (some companies want to allow non-employee logins; others gate access entirely). +4. On match, the handler calls `GET /employees/?fields=status,jobTitle,department,hireDate,terminationDate`. An `Active` employee gets `204 No Content`, and the flow continues. +5. On no match or a non-`Active` status, the handler responds with `403` and a [`messages` body](https://www.ory.com/docs/kratos/hooks/configure-hooks#webhook-responses), so Ory stops the flow and shows the user why. A `200` response doesn't block anything, whatever its body says. +6. If BambooHR is slow or unreachable, the handler responds with `502`, and Ory fails the flow. This check makes every sign-in depend on BambooHR, so decide whether to keep that fail-closed behavior or let users in when BambooHR can't answer. ## Prerequisites @@ -42,9 +43,9 @@ The server listens on the port specified in `.env` (default 3000) and exposes: ## Configure Ory -1. Configure the Action hook using the snippet in [`ory-actions.yaml`](ory-actions.yaml) — register on `after:login` and optionally `after:registration`. +1. Configure the Action hook using the snippet in [`ory-actions.yaml`](ory-actions.yaml). Add it to the login method lists, for example `selfservice.flows.login.after.password.hooks`, and optionally the registration method lists. Ory runs the global `selfservice.flows.login.after.hooks` list only for a method that has no hooks of its own. 2. The body template is [`jsonnet/identity.jsonnet`](jsonnet/identity.jsonnet); only `email` is required. -3. Keep `response.parse: true` and `response.ignore: false` so Ory consumes the enrichment payload. +3. Keep `response.parse: true` and `response.ignore: false` so Ory reads the `messages` body of a `403` and shows it to the user. 4. Set `ORY_WEBHOOK_SECRET` in the handler's `.env` to match the `X-Webhook-Secret` value in the hook config. Off-boarded-employee gating, role-based attribute mapping, and saved-report lookups for large directories: see the [docs page](https://ory.com/docs/integrates-with/directory-sync/bamboohr). diff --git a/directory-sync/bamboohr/registry.entry.yaml b/directory-sync/bamboohr/registry.entry.yaml index 36862bd..0312fdc 100644 --- a/directory-sync/bamboohr/registry.entry.yaml +++ b/directory-sync/bamboohr/registry.entry.yaml @@ -8,18 +8,18 @@ category: directory-sync type: webhook maintainedBy: Community contributors description: >- - BambooHR is an HRIS popular with SMB and mid-market companies. This integration enriches Ory identities with employee - data from BambooHR via an Ory Action webhook on login or registration, returning employment status, job title, - department, and hire date so a post-flow Action can gate access or write the fields into identity metadata. + BambooHR is an HRIS popular with SMB and mid-market companies. This integration checks employment status in + BambooHR from an Ory Action webhook on login or registration and blocks the flow for users who aren't active + employees. useCase: >- A company runs internal SaaS for employees and wants login to gate on employment status — off-boarded employees lose access automatically without a separate deprovision step. BambooHR is the HRIS source of truth; the integration looks - up the user's BambooHR record at login and returns the employment flag so Ory can fail the flow on employed: false. + up the user's BambooHR record at login and blocks the sign-in when there is no active record. coreFunctionality: |- - - Sync Ory Action webhook (response.parse: true) on after:login and optionally after:registration. - - Looks up the employee via /employees/directory filtered by workEmail (BambooHR has no direct lookup-by-email API). - - Fetches detail fields (status, jobTitle, department, hireDate, terminationDate) and returns { employed, employee_id, job_title, department, hire_date }. - - Returns { employed: false } on no match so Ory can branch on member-vs-non-member traffic instead of erroring. + - Sync Ory Action webhook (response.parse: true) in the login method hook lists (for example selfservice.flows.login.after.password.hooks) and optionally registration. + - Looks up the employee via /employees/directory filtered by workEmail (BambooHR has no direct lookup-by-email API), then fetches the employee's status. + - Active employees get 204 No Content; no match or a non-Active status gets 403 with a Kratos `messages` body, which blocks the flow and shows the reason. + - BambooHR errors return 502, which fails the flow, so every sign-in depends on BambooHR availability. - BambooHR Basic auth: API key as username, literal "x" as password — documented in code so it doesn't look like a typo. oryMechanism: - actions diff --git a/directory-sync/bamboohr/webhook/server.ts b/directory-sync/bamboohr/webhook/server.ts index 4ae3b74..240c8a5 100644 --- a/directory-sync/bamboohr/webhook/server.ts +++ b/directory-sync/bamboohr/webhook/server.ts @@ -1,9 +1,11 @@ // SPDX-License-Identifier: Apache-2.0 // // Reference webhook handler for the Ory <> BambooHR integration. -// Looks up the BambooHR employee matching an Ory identity's email and returns -// employment fields back to Ory so the post-flow Action can decide whether to -// allow the flow. +// Looks up the BambooHR employee matching an Ory identity's email. Active +// employees get 204 No Content, which lets the flow continue. Everyone else +// gets 403 with a Kratos `messages` body, which blocks the flow and shows the +// reason to the user. The hook must use `response.parse: true` for Kratos to +// read that body. import "dotenv/config"; import crypto from "node:crypto"; @@ -39,6 +41,18 @@ interface BamboohrDirectoryEmployee { interface BamboohrDirectoryResponse { employees?: BamboohrDirectoryEmployee[]; } +// Kratos only renders messages from a 4xx body in this shape. +function denyFlow(res: Response, text: string) { + res.status(403).json({ + messages: [ + { + instance_ptr: "#/", + messages: [{ id: 10000001, text, type: "error", context: {} }], + }, + ], + }); +} + interface BamboohrEmployeeDetail { status?: string; jobTitle?: string; @@ -97,7 +111,7 @@ app.post( if (!employee) { console.log(`No BambooHR record for ${email} (identity ${identity_id})`); - res.json({ ok: true, employed: false }); + denyFlow(res, "Only current employees can sign in."); return; } @@ -116,14 +130,12 @@ app.post( } const detail = (await empRes.json()) as BamboohrEmployeeDetail; - res.json({ - ok: true, - employed: detail.status === "Active", - employee_id: employee.id, - job_title: detail.jobTitle ?? null, - department: detail.department ?? null, - hire_date: detail.hireDate ?? null, - }); + if (detail.status !== "Active") { + console.log(`BambooHR employee ${employee.id} is ${detail.status ?? "unknown"} (identity ${identity_id})`); + denyFlow(res, "Only current employees can sign in."); + return; + } + res.status(204).end(); } catch (err) { console.error("Enrich error:", (err as Error).message); res.status(502).json({ error: "enrich_failed" }); diff --git a/directory-sync/google-workspace-scim/README.md b/directory-sync/google-workspace-scim/README.md index 15f7bea..7461026 100644 --- a/directory-sync/google-workspace-scim/README.md +++ b/directory-sync/google-workspace-scim/README.md @@ -13,10 +13,12 @@ Automatic user provisioning and deprovisioning from Google Workspace into Ory Ne The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/kratos/manage-identities/scim/google-workspace). Short version: -1. In **Google Workspace Admin Console** → **Apps → Web and mobile apps** → **Add app → Search for apps**, find or add **Ory Network** (or your custom SAML app). -2. Under the app's **Auto-provisioning** section, enable SCIM and paste: - - **Endpoint URL** = SCIM endpoint from your Ory Network organization's setup-link. - - **Access token** = SCIM bearer token from the same setup-link. +Google Workspace provisions users only to the apps in its [list of supported apps](https://knowledge.workspace.google.com/admin/users/advanced/about-automated-user-provisioning), not to a custom SCIM endpoint such as Ory Network. The Ory Network guide works around this with a supported catalog app. + +1. In **Google Workspace Admin Console** → **Apps → Web and mobile apps** → **Add app → Search for apps**, search for **Keeper** and select **Keeper Web (SAML)**. +2. Under the app's provisioning section, click **Configure autoprovisioning** and enter: + - **Access token** = the authorization header secret of the SCIM client on your Ory Network organization. + - **Endpoint URL** = the SCIM client's base URL. 3. Configure the **attribute mapping** — Google primary email → `userName`, given/family name → `name.givenName`/`name.familyName`, groups → `groups`. 4. Choose the provisioning scope — which OUs / groups Workspace will sync to Ory. 5. Toggle **on for all** users / OUs covered. diff --git a/directory-sync/google-workspace-scim/registry.entry.yaml b/directory-sync/google-workspace-scim/registry.entry.yaml index e4d8de2..66d36ea 100644 --- a/directory-sync/google-workspace-scim/registry.entry.yaml +++ b/directory-sync/google-workspace-scim/registry.entry.yaml @@ -16,7 +16,7 @@ useCase: >- update / disable) in Workspace to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in Google Workspace Admin Console → Apps → Web and mobile apps → app → Auto-provisioning. Pastes SCIM endpoint URL + access token from Ory's setup-link. + - Google Workspace provisions only to apps in its supported-app catalog, not to custom SCIM endpoints; the Ory Network guide adds the Keeper Web (SAML) catalog app and enters the Ory SCIM client's base URL and authorization header secret as its provisioning endpoint and token. - Attribute mapping: primary email → userName; given/family name → name.givenName / name.familyName; groups → groups. - Workspace pushes lifecycle events on its own schedule (typically within a few minutes of directory change) — no manual "push now". - Deactivation in Workspace becomes a deactivate in Ory (preserves identity record) — not a hard delete. diff --git a/directory-sync/jumpcloud-scim/README.md b/directory-sync/jumpcloud-scim/README.md index 2a6b827..f36b471 100644 --- a/directory-sync/jumpcloud-scim/README.md +++ b/directory-sync/jumpcloud-scim/README.md @@ -5,16 +5,18 @@ Automatic user provisioning and deprovisioning from JumpCloud into Ory Network / Ory Polis via SCIM 2.0. Pair with [`enterprise-sso/jumpcloud`](../../enterprise-sso/jumpcloud/) for the federated sign-in side. **Type:** config (SCIM endpoint configuration — no webhook code) -**Docs page:** [ory.com/docs/integrates-with/directory-sync/jumpcloud-scim](https://www.ory.com/docs/integrates-with/directory-sync/jumpcloud-scim) — full guide: [ory.com/docs/polis/directory-sync/providers/jumpcloud](https://www.ory.com/docs/polis/directory-sync/providers/jumpcloud) +**Docs page:** [ory.com/docs/integrates-with/directory-sync/jumpcloud-scim](https://www.ory.com/docs/integrates-with/directory-sync/jumpcloud-scim) +- Ory Network (managed): [ory.com/docs/kratos/manage-identities/scim](https://www.ory.com/docs/kratos/manage-identities/scim) +- Ory Polis (self-hosted): [ory.com/docs/polis/directory-sync/providers/jumpcloud](https://www.ory.com/docs/polis/directory-sync/providers/jumpcloud) ## Setup -The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/directory-sync/providers/jumpcloud). Short version: +On Ory Network, create a SCIM client on an [organization](https://www.ory.com/docs/kratos/organizations); it has its own base URL, authorization header secret, and data mapping. See [SCIM](https://www.ory.com/docs/kratos/manage-identities/scim). For self-hosted Ory Polis, the full walkthrough lives at [ory.com/docs/polis/directory-sync/providers/jumpcloud](https://www.ory.com/docs/polis/directory-sync/providers/jumpcloud). Short version: 1. In the **JumpCloud Admin Console** → **SSO Applications** → select the app paired with this directory sync → **Identity Management** tab. 2. Enable **Identity Management** and paste: - - **SCIM Base URL** = SCIM endpoint from your Ory directory-sync setup-link. - - **API key** = SCIM bearer token from the same setup-link. + - **SCIM Base URL** = the SCIM client's base URL on Ory Network, or the SCIM endpoint of your Ory Polis directory sync. + - **API key** = the SCIM client's authorization header secret on Ory Network, or your Ory Polis directory sync's bearer token. 3. Configure the **attribute mapping** — email → `userName`, given/family name → `name.givenName`/`name.familyName`, group membership → `groups`. 4. Assign user groups to the application — JumpCloud pushes only assigned-group members. diff --git a/directory-sync/jumpcloud-scim/registry.entry.yaml b/directory-sync/jumpcloud-scim/registry.entry.yaml index cf027da..80d0312 100644 --- a/directory-sync/jumpcloud-scim/registry.entry.yaml +++ b/directory-sync/jumpcloud-scim/registry.entry.yaml @@ -9,14 +9,14 @@ type: config maintainedBy: Ory Engineering description: >- Automatic user provisioning and deprovisioning from JumpCloud into Ory Network / Ory Polis via SCIM 2.0. - Documented directly in /polis/directory-sync/providers/jumpcloud. Pair with enterprise-sso/jumpcloud for + Documented in /kratos/manage-identities/scim (Ory Network) and /polis/directory-sync/providers/jumpcloud (Ory Polis self-hosted). Pair with enterprise-sso/jumpcloud for the federated sign-in side. useCase: >- An Ory customer running enterprise SSO from JumpCloud wants user lifecycle events (create / update / disable) in JumpCloud to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in JumpCloud Admin Console → SSO Applications → app → Identity Management tab. Pastes SCIM Base URL + API key from Ory's directory-sync setup-link. + - Configured in JumpCloud Admin Console → SSO Applications → app → Identity Management tab. Pastes the SCIM Base URL + API key: on Ory Network, the base URL and authorization header secret of a SCIM client created on an organization; on self-hosted Ory Polis, the directory-sync endpoint and token. - Attribute mapping: email → userName; given/family name → name.givenName / name.familyName; group membership → groups. - SCIM provisioning is tied to a SAML application — cannot run SCIM without also having the corresponding SAML app configured. - JumpCloud pushes only members of assigned user groups; manage scope via group assignment, not user assignment. diff --git a/directory-sync/onelogin-scim/README.md b/directory-sync/onelogin-scim/README.md index 2f6e63f..cbd9bd4 100644 --- a/directory-sync/onelogin-scim/README.md +++ b/directory-sync/onelogin-scim/README.md @@ -5,16 +5,18 @@ Automatic user provisioning and deprovisioning from OneLogin (One Identity) into Ory Network / Ory Polis via SCIM 2.0. Pair with [`enterprise-sso/onelogin`](../../enterprise-sso/onelogin/) for the federated sign-in side. **Type:** config (SCIM endpoint configuration — no webhook code) -**Docs page:** [ory.com/docs/integrates-with/directory-sync/onelogin-scim](https://www.ory.com/docs/integrates-with/directory-sync/onelogin-scim) — full guide: [ory.com/docs/polis/directory-sync/providers/onelogin](https://www.ory.com/docs/polis/directory-sync/providers/onelogin) +**Docs page:** [ory.com/docs/integrates-with/directory-sync/onelogin-scim](https://www.ory.com/docs/integrates-with/directory-sync/onelogin-scim) +- Ory Network (managed): [ory.com/docs/kratos/manage-identities/scim](https://www.ory.com/docs/kratos/manage-identities/scim) +- Ory Polis (self-hosted): [ory.com/docs/polis/directory-sync/providers/onelogin](https://www.ory.com/docs/polis/directory-sync/providers/onelogin) ## Setup -The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/directory-sync/providers/onelogin). Short version: +On Ory Network, create a SCIM client on an [organization](https://www.ory.com/docs/kratos/organizations); it has its own base URL, authorization header secret, and data mapping. See [SCIM](https://www.ory.com/docs/kratos/manage-identities/scim). For self-hosted Ory Polis, the full walkthrough lives at [ory.com/docs/polis/directory-sync/providers/onelogin](https://www.ory.com/docs/polis/directory-sync/providers/onelogin). Short version: 1. In the **OneLogin Admin Portal** → **Applications** → select the app paired with this directory sync → **Configuration** tab. 2. Set **API Connection**: - - **SCIM Base URL** = SCIM endpoint from your Ory directory-sync setup-link. - - **API Bearer Token** = SCIM bearer token from the same setup-link. + - **SCIM Base URL** = the SCIM client's base URL on Ory Network, or the SCIM endpoint of your Ory Polis directory sync. + - **API Bearer Token** = the SCIM client's authorization header secret on Ory Network, or your Ory Polis directory sync's bearer token. 3. Switch to the **Provisioning** tab; enable provisioning and select which events trigger automatic vs. manual approval (Create User, Delete User, Update User). 4. Configure the **Parameters** mappings — OneLogin attributes → SCIM `userName`, `name.givenName`, `name.familyName`, `emails[].value`, `groups[]`. 5. Assign users / roles to the application. diff --git a/directory-sync/onelogin-scim/registry.entry.yaml b/directory-sync/onelogin-scim/registry.entry.yaml index 47d3790..a26b145 100644 --- a/directory-sync/onelogin-scim/registry.entry.yaml +++ b/directory-sync/onelogin-scim/registry.entry.yaml @@ -9,13 +9,14 @@ type: config maintainedBy: Ory Engineering description: >- Automatic user provisioning and deprovisioning from OneLogin (One Identity) into Ory Network / Ory Polis via - SCIM 2.0. Documented directly in /polis/directory-sync/providers/onelogin. Pair with enterprise-sso/onelogin + SCIM 2.0. Documented in /kratos/manage-identities/scim (Ory Network) and + /polis/directory-sync/providers/onelogin (Ory Polis self-hosted). Pair with enterprise-sso/onelogin for the federated sign-in side. useCase: >- An Ory customer running enterprise SSO from OneLogin wants user lifecycle events (create / update / disable) to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in OneLogin Admin Portal → Applications → app → Configuration tab; paste SCIM Base URL + API Bearer Token from Ory's directory-sync setup-link. + - Configured in OneLogin Admin Portal → Applications → app → Configuration tab; paste the SCIM Base URL + API Bearer Token: on Ory Network, the base URL and authorization header secret of a SCIM client created on an organization; on self-hosted Ory Polis, the directory-sync endpoint and token. - Provisioning tab: enable provisioning and select which events trigger automatic vs manual approval (Create User, Delete User, Update User). - Parameters mappings: OneLogin attributes → SCIM userName / name.givenName / name.familyName / emails[].value / groups[]. - SCIM connector requires a matching SAML/OIDC application — directory sync is tied to an SSO app, not standalone. diff --git a/directory-sync/workday-scim/README.md b/directory-sync/workday-scim/README.md index fbf6398..a95c254 100644 --- a/directory-sync/workday-scim/README.md +++ b/directory-sync/workday-scim/README.md @@ -11,15 +11,15 @@ Provision identities from [Workday](https://www.workday.com) (one of the most wi Workday's SCIM connector is not turnkey — it requires either: -1. **Workday Studio / Integration System** approach: build a Workday integration that maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's directory-sync endpoint. This is the canonical Workday path but requires Workday Studio licensing and developer hours. +1. **Workday Studio / Integration System** approach: build a Workday integration that maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's SCIM endpoint. This is the canonical Workday path but requires Workday Studio licensing and developer hours. 2. **Mid-tier connector** approach: deploy a connector (third-party like Tools4ever HelloID, Saviynt, or a custom service) that pulls from Workday's REST/SOAP APIs and pushes to Ory's SCIM endpoint. Lower friction than Studio if a connector for Workday→SCIM already exists. -3. **Identity-platform-fronted** approach: provision Workday → Okta/Entra ID via the IdP's native Workday connector, then provision IdP → Ory via SCIM (see [`directory-sync/okta-scim`](../okta-scim/) or [`directory-sync/microsoft-scim`](../microsoft-scim/)). This is the most common path in practice and avoids touching Workday directly. +3. **Identity-platform-fronted** approach: provision Workday → Okta/Entra ID via the IdP's native Workday connector, then provision IdP → Ory via SCIM (see [`directory-sync/okta-scim`](../okta-scim/) or [`directory-sync/microsoft-scim`](../microsoft-scim/); on Ory Network follow [Provision from Okta](https://www.ory.com/docs/kratos/manage-identities/scim/okta) or [Provision from MS Entra](https://www.ory.com/docs/kratos/manage-identities/scim/ms-entra)). This is the most common path in practice and avoids touching Workday directly. ## What Ory provides -A standard SCIM 2.0 endpoint with bearer-token auth, accepting `Users` and `Groups`. Endpoint URL and bearer token are provided in your Ory directory-sync setup-link. +A standard SCIM 2.0 endpoint that accepts `Users` and `Groups`. On Ory Network, each SCIM client belongs to an organization and has its own base URL, authorization header secret, and data mapping. See [SCIM](https://www.ory.com/docs/kratos/manage-identities/scim) and the [SCIM API reference](https://www.ory.com/docs/kratos/manage-identities/scim/api-reference). ## Status diff --git a/directory-sync/workday-scim/registry.entry.yaml b/directory-sync/workday-scim/registry.entry.yaml index fec4ecc..af63681 100644 --- a/directory-sync/workday-scim/registry.entry.yaml +++ b/directory-sync/workday-scim/registry.entry.yaml @@ -18,10 +18,10 @@ useCase: >- the workforce IdP (Okta / Entra ID) being on the critical path. coreFunctionality: |- - No turnkey Workday → SCIM connector ships with Workday; integration requires one of three patterns. - - Pattern A (canonical): Workday Studio / Integration System maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's directory-sync endpoint. Requires Workday Studio licensing and developer hours. + - Pattern A (canonical): Workday Studio / Integration System maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's SCIM endpoint. Requires Workday Studio licensing and developer hours. - Pattern B: deploy a mid-tier connector (Tools4ever HelloID, Saviynt, or a custom service) that pulls Workday REST/SOAP and pushes to Ory's SCIM endpoint. - Pattern C (most common in practice): provision Workday → Okta/Entra via the IdP's native Workday connector, then Okta/Entra → Ory via the existing SCIM integration. Avoids touching Workday directly. - - Ory side is a standard SCIM 2.0 endpoint with bearer-token auth, accepting Users and Groups; endpoint URL and token come from the directory-sync setup-link. + - Ory side is a standard SCIM 2.0 endpoint accepting Users and Groups; on Ory Network each SCIM client belongs to an organization and has its own base URL, authorization header secret, and data mapping. - Status: community/proposed — documented at ory.com/docs/integrates-with/directory-sync/workday-scim. oryMechanism: - directory-sync diff --git a/enterprise-sso/auth0-saml/README.md b/enterprise-sso/auth0-saml/README.md index 3c74c27..afc69c1 100644 --- a/enterprise-sso/auth0-saml/README.md +++ b/enterprise-sso/auth0-saml/README.md @@ -2,24 +2,33 @@ > **Maintained by:** Ory Engineering -Configure [Auth0](https://auth0.com) as a SAML 2.0 Identity Provider into Ory Polis (the SAML SP). Common for organizations whose workforce identities live in Auth0 but who want Ory Network as the customer-facing identity layer with B2B SSO. +Configure [Auth0](https://auth0.com) as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Common for organizations whose workforce identities live in Auth0 but who want Ory Network as the customer-facing identity layer with B2B SSO. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/auth0-saml](https://www.ory.com/docs/integrates-with/enterprise-sso/auth0-saml) — full guide: [ory.com/docs/polis/sso-providers/auth0](https://www.ory.com/docs/polis/sso-providers/auth0) +## Ory Network connection values + +On Ory Network, add Auth0 as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Auth0 SAML application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/auth0). Short version: 1. In Auth0, create a **Regular Web Application** (or use an existing one). 2. Under the application's **Addons** tab, enable **SAML2 WEB APP**. -3. Configure the addon with the Ory Polis SP **Assertion Consumer Service (ACS) URL** and **Audience (Entity ID)** from your Ory Network organization's setup-link. +3. Configure the addon with the **Assertion Consumer Service (ACS) URL** and **Audience (Entity ID)** from [Ory Network connection values](#ory-network-connection-values). 4. Download the Auth0 signing certificate and the IdP metadata. 5. Paste the metadata (or upload the XML) into the Ory organization's SSO connection screen. ## Notes -- Auth0 supports both SP-initiated and IdP-initiated SSO; Ory Polis consumes SP-initiated. +- Auth0 supports both SP-initiated and IdP-initiated SSO. SAML connections on Ory Network support IdP-initiated login, which is off by default; see [IdP-initiated login](https://www.ory.com/docs/kratos/organizations#idp-initiated-login). - Use **Auth0 Actions** (not the SAML addon's claims editor) for any non-trivial attribute transformation — Actions are the supported, version-controlled path. - MFA enforcement should sit at the Auth0 IdP layer; Ory consumes the resulting authenticated assertion. diff --git a/enterprise-sso/auth0-saml/registry.entry.yaml b/enterprise-sso/auth0-saml/registry.entry.yaml index f78518c..5fc9d4a 100644 --- a/enterprise-sso/auth0-saml/registry.entry.yaml +++ b/enterprise-sso/auth0-saml/registry.entry.yaml @@ -16,8 +16,8 @@ useCase: >- customer's IdP happens to be Auth0 — this integration is the per-customer connection setup. coreFunctionality: |- - Configured per Ory Polis docs at /polis/sso-providers/auth0; Polis acts as the SAML SP, Auth0 as the IdP. - - Auth0 side: Regular Web Application + SAML2 WEB APP addon; configure ACS URL + Audience from Ory's setup-link. - - SP-initiated only — Auth0 also supports IdP-initiated but Polis consumes SP-initiated. + - Auth0 side: Regular Web Application + SAML2 WEB APP addon; configure ACS URL (https://.projects.oryapis.com/saml/api/oauth/saml) + Audience (https://.projects.oryapis.com/self-service/methods/saml/organizations/) on Ory Network. + - Auth0 supports both SP-initiated and IdP-initiated SSO. SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Use Auth0 Actions (not the addon's claims editor) for non-trivial attribute transformations — version-controlled, supported path. - MFA enforcement sits at the Auth0 IdP layer; Ory consumes the resulting authenticated assertion. oryMechanism: diff --git a/enterprise-sso/cyberark-identity/README.md b/enterprise-sso/cyberark-identity/README.md index 6807dc4..c5bfb6e 100644 --- a/enterprise-sso/cyberark-identity/README.md +++ b/enterprise-sso/cyberark-identity/README.md @@ -4,16 +4,28 @@ [CyberArk Identity](https://www.cyberark.com/products/identity/) (the SSO and identity portion of the CyberArk platform — distinct from CyberArk's PAM product) exposes standard SAML 2.0 and OIDC endpoints for federation. Configure as an upstream IdP in Ory Network so CyberArk-managed enterprise identities can sign in to Ory-protected applications. -**Type:** config (generic OIDC or generic SAML in Ory Polis — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or generic SAML/OIDC in self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/cyberark-identity](https://www.ory.com/docs/integrates-with/enterprise-sso/cyberark-identity) -- [Polis SAML — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml) (recommended for enterprise SSO). -- [Polis OIDC — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc) if your CyberArk app is configured for OIDC. +- [Self-hosted Ory Polis — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml) (recommended for enterprise SSO). +- [Self-hosted Ory Polis — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc) if your CyberArk app is configured for OIDC. + +## Ory Network connection values + +On Ory Network, add CyberArk Identity as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the CyberArk app, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. ## Setup outline 1. In CyberArk Identity, create a **Custom SAML App** (or **Custom OIDC App**). -2. Configure the Ory Polis SP metadata (entity ID, ACS URL, certificate) into the CyberArk app. -3. In Ory Network, configure the SSO connection using the generic SAML/OIDC provider walkthrough above; paste CyberArk's metadata XML (SAML) or issuer URL + client credentials (OIDC). +2. Enter the [Ory Network connection values](#ory-network-connection-values) in the CyberArk app. When you self-host Ory Polis, use your Ory Polis SP metadata instead. +3. In Ory Network, add a SAML or OIDC connection to an organization; paste CyberArk's metadata XML (SAML) or issuer URL + client credentials (OIDC). 4. Map the CyberArk attributes (`email`, `firstname`, `lastname`, group memberships) to Ory identity traits. 5. Enable the connection on your Ory organization. diff --git a/enterprise-sso/forgerock-am/README.md b/enterprise-sso/forgerock-am/README.md index 7c8d510..6e007e9 100644 --- a/enterprise-sso/forgerock-am/README.md +++ b/enterprise-sso/forgerock-am/README.md @@ -4,21 +4,33 @@ [ForgeRock Access Management](https://www.pingidentity.com/en/platform/forgerock.html) (now part of Ping Identity) is a widely deployed enterprise IAM platform supporting OIDC, OAuth 2.0, and SAML 2.0. Configure as an upstream IdP in Ory Network so existing ForgeRock-managed sessions flow through to Ory-protected applications. -**Type:** config (generic OIDC or generic SAML in Ory Polis — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or generic SAML/OIDC in self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/forgerock-am](https://www.ory.com/docs/integrates-with/enterprise-sso/forgerock-am) -- [Polis SAML — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). -- [Polis OIDC — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). +- [Self-hosted Ory Polis — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). +- [Self-hosted Ory Polis — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). + +## Ory Network connection values + +On Ory Network, add ForgeRock AM as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the ForgeRock app, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. ## Setup outline 1. In ForgeRock AM, create a SAML 2.0 entity (or OIDC client) — typically under **Realms → Applications → Federation** for SAML, or **OAuth 2.0 → Clients** for OIDC. -2. Configure the Ory Polis SP metadata (entity ID, ACS URL, certificate) into the ForgeRock app. -3. In Ory Network, configure the SSO connection using the generic SAML/OIDC walkthrough; paste ForgeRock's metadata XML (SAML) or OIDC discovery URL + client credentials. +2. Enter the [Ory Network connection values](#ory-network-connection-values) in the ForgeRock app. When you self-host Ory Polis, use your Ory Polis SP metadata instead. +3. In Ory Network, add a SAML or OIDC connection to an organization; paste ForgeRock's metadata XML (SAML) or OIDC discovery URL + client credentials. 4. Map ForgeRock's released attributes to Ory identity traits. ## Notes -- ForgeRock SAML supports both IdP-initiated and SP-initiated flows. Polis only consumes SP-initiated assertions; configure the ForgeRock side accordingly. +- ForgeRock SAML supports both IdP-initiated and SP-initiated flows. SAML connections on Ory Network support IdP-initiated login, which is off by default; see [IdP-initiated login](https://www.ory.com/docs/kratos/organizations#idp-initiated-login). - ForgeRock OIDC supports the standard `openid`, `profile`, `email`, `groups` scopes; group claims may need a custom OIDC scope mapper depending on your AM version. - ForgeRock AM is now branded as **Ping Identity Platform** following the 2023 acquisition; older docs may use either name. diff --git a/enterprise-sso/forgerock-am/registry.entry.yaml b/enterprise-sso/forgerock-am/registry.entry.yaml index fd58c55..ef05707 100644 --- a/enterprise-sso/forgerock-am/registry.entry.yaml +++ b/enterprise-sso/forgerock-am/registry.entry.yaml @@ -9,7 +9,7 @@ type: config maintainedBy: Community contributors description: >- Configure ForgeRock Access Management (now part of Ping Identity following the 2023 acquisition) as an upstream - SAML 2.0 or OIDC identity provider in Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/forgerock-am; configures via the Polis generic SAML or + SAML 2.0 or OIDC identity provider for an Ory Network organization or self-hosted Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/forgerock-am; configures via the Polis generic SAML or generic OIDC walkthrough. useCase: >- An enterprise running ForgeRock AM (or the rebranded Ping Identity Platform) as their workforce IdP wants @@ -18,7 +18,7 @@ useCase: >- coreFunctionality: |- - Configured as a generic SAML 2.0 SP (preferred for enterprise SSO) or generic OIDC RP in Ory Polis pointing at the ForgeRock entity / OAuth client. - ForgeRock side: SAML entity under Realms → Applications → Federation, or OAuth 2.0 client under OAuth 2.0 → Clients. - - SP-initiated only — Polis does not consume IdP-initiated SAML assertions; configure the ForgeRock side accordingly. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - OIDC supports openid / profile / email / groups; group claims may need a custom scope mapper depending on AM version. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/forgerock-am. oryMechanism: diff --git a/enterprise-sso/generic-oidc/README.md b/enterprise-sso/generic-oidc/README.md index 97baca8..9e1cebb 100644 --- a/enterprise-sso/generic-oidc/README.md +++ b/enterprise-sso/generic-oidc/README.md @@ -2,13 +2,23 @@ > **Maintained by:** Ory Engineering -Configure **any** OIDC-compliant Identity Provider into Ory Polis as the OIDC Relying Party. This is the canonical reference for setting up OIDC-based enterprise SSO with Ory and the fallback when no provider-specific guide covers your IdP. +Configure **any** OIDC-compliant Identity Provider for enterprise single sign-on (SSO). On Ory Network, Ory Kratos is the OIDC relying party for an organization's connection. When you self-host Ory Polis, Ory Polis is the OIDC relying party. This is the canonical reference for setting up OIDC-based enterprise SSO with Ory and the fallback when no provider-specific guide covers your IdP. > Mirrored under [`generic-protocols/generic-oidc`](../../generic-protocols/generic-oidc/) — same source page on ory.com/docs. -**Type:** config (Polis OIDC connection — no webhook code) +**Type:** config (OIDC connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/generic-oidc](https://www.ory.com/docs/integrates-with/enterprise-sso/generic-oidc) — full guide: [ory.com/docs/polis/sso-providers/generic-oidc](https://www.ory.com/docs/polis/sso-providers/generic-oidc) +## Ory Network connection values + +On Ory Network, add the IdP as an OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project, using the IdP's issuer URL, client ID, and client secret. In the IdP's client settings, set this value: + +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## When to use - Your IdP is **not listed** in [`polis/sso-providers/`](https://www.ory.com/docs/polis/sso-providers/) but speaks OIDC. @@ -19,10 +29,10 @@ Configure **any** OIDC-compliant Identity Provider into Ory Polis as the OIDC Re | Field | Source | | --- | --- | -| Issuer URL | Usually `https:///.well-known/openid-configuration` minus the path — Polis fetches discovery automatically. | -| Client ID | Created in the IdP when registering Polis as an OIDC client. | +| Issuer URL | Usually `https:///.well-known/openid-configuration` minus the path — Ory fetches discovery automatically. | +| Client ID | Created in the IdP when registering Ory as an OIDC client. | | Client Secret | Same — store in your secrets backend, never in source. | -| Redirect URI | Polis ACS URL from your Ory Network organization's setup-link. | +| Redirect URI | The OIDC redirect URI from [Ory Network connection values](#ory-network-connection-values). | | Scopes | At minimum `openid` and `profile`; `email` for identity, `groups` if you map them. | ## License diff --git a/enterprise-sso/generic-oidc/registry.entry.yaml b/enterprise-sso/generic-oidc/registry.entry.yaml index 61b7477..3ca0804 100644 --- a/enterprise-sso/generic-oidc/registry.entry.yaml +++ b/enterprise-sso/generic-oidc/registry.entry.yaml @@ -8,7 +8,7 @@ category: enterprise-sso type: config maintainedBy: Ory Engineering description: >- - Configure ANY OIDC-compliant Identity Provider into Ory Polis as the OIDC Relying Party. Canonical reference + Configure ANY OIDC-compliant Identity Provider for enterprise SSO. On Ory Network, Ory Kratos is the OIDC Relying Party for an organization's connection; when self-hosting, Ory Polis is the RP. Canonical reference for OIDC-based enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. Same source page is mirrored under generic-protocols/generic-oidc. useCase: >- @@ -17,8 +17,8 @@ useCase: >- documented for debugging or non-default configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-oidc; Polis acts as the OIDC RP, IdP as the OP. - - Discovery via /.well-known/openid-configuration on the issuer URL — Polis fetches and caches automatically. - - Required from the IdP: issuer URL, client id, client secret, plus the Polis ACS URL configured on the IdP side as the redirect URI. + - Discovery via /.well-known/openid-configuration on the issuer URL — Ory fetches and caches automatically. + - Required from the IdP: issuer URL, client id, client secret, plus the organization's OIDC redirect URI (https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/, or /self-service/methods/oidc/callback with pkce: force) configured on the IdP side. - Standard scopes: openid (required), profile, email; add groups if attribute mapping needs them. - Same content mirrored at generic-protocols/generic-oidc — categorization choice; either entry resolves to the same Polis page. oryMechanism: diff --git a/enterprise-sso/generic-saml/README.md b/enterprise-sso/generic-saml/README.md index 4be9044..ab783bb 100644 --- a/enterprise-sso/generic-saml/README.md +++ b/enterprise-sso/generic-saml/README.md @@ -2,32 +2,41 @@ > **Maintained by:** Ory Engineering -Configure **any** SAML 2.0-compliant Identity Provider into Ory Polis as the SAML Service Provider. This is the canonical reference for setting up SAML-based enterprise SSO with Ory and the fallback when no provider-specific guide covers your IdP. +Configure **any** SAML 2.0-compliant Identity Provider for enterprise single sign-on (SSO). Ory Network acts as the SAML service provider (SP) for organizations. When you self-host Ory Polis, Ory Polis is the SAML SP. This is the canonical reference for setting up SAML-based enterprise SSO with Ory and the fallback when no provider-specific guide covers your IdP. > Mirrored under [`generic-protocols/generic-saml`](../../generic-protocols/generic-saml/) — same source page on ory.com/docs. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/generic-saml](https://www.ory.com/docs/integrates-with/enterprise-sso/generic-saml) — full guide: [ory.com/docs/polis/sso-providers/generic-saml](https://www.ory.com/docs/polis/sso-providers/generic-saml) +## Ory Network connection values + +On Ory Network, add the IdP as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the IdP's SAML application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## When to use - Your IdP is **not listed** in [`polis/sso-providers/`](https://www.ory.com/docs/polis/sso-providers/) but speaks SAML 2.0. - Your IdP **is listed** but you want the underlying mechanics for debugging or non-default configuration. -- You're integrating a less-common IdP (CyberArk, ForgeRock, IBM Security Verify, OneLogin Directory, custom in-house SAML). +- You're integrating a less-common IdP (CyberArk, ForgeRock, IBM Verify, OneLogin Directory, custom in-house SAML). ## What you'll need from the IdP | Field | Source | | --- | --- | -| IdP Metadata XML | Most IdPs publish this at a metadata URL or as a downloadable XML file. Polis can consume either. | +| IdP Metadata XML | Most IdPs publish this at a metadata URL or as a downloadable XML file. Ory can consume either. | | Or: IdP Entity ID, SSO URL, signing certificate | If no metadata XML is available, paste these manually. | -| Attribute mapping | Define what the IdP sends as `email`, `firstName`, `lastName`, `groups`, etc. Polis maps these to Ory traits. | +| Attribute mapping | Define what the IdP sends as `email`, `firstName`, `lastName`, `groups`, etc. The connection's data mapping maps these to Ory traits. | ## What you'll give the IdP | Field | Source | | --- | --- | -| Polis SP Metadata XML | From your Ory Network organization's setup-link. The IdP will use this to know where to send the SAML assertion. | +| SP values | The ACS URL and SP entity ID from [Ory Network connection values](#ory-network-connection-values), or your self-hosted Ory Polis SP metadata. The IdP will use this to know where to send the SAML assertion. | | Or: ACS URL, Entity ID, signing certificate | Same data, manual paste. | ## License diff --git a/enterprise-sso/generic-saml/registry.entry.yaml b/enterprise-sso/generic-saml/registry.entry.yaml index b76b5d4..155400e 100644 --- a/enterprise-sso/generic-saml/registry.entry.yaml +++ b/enterprise-sso/generic-saml/registry.entry.yaml @@ -8,19 +8,19 @@ category: enterprise-sso type: config maintainedBy: Ory Engineering description: >- - Configure ANY SAML 2.0-compliant Identity Provider into Ory Polis as the SAML Service Provider. Canonical + Configure ANY SAML 2.0-compliant Identity Provider for enterprise SSO. Ory Network acts as the SAML Service Provider for organizations; when self-hosting, Ory Polis is the SAML SP. Canonical reference for SAML-based enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. Same source page is mirrored under generic-protocols/generic-saml. useCase: >- An Ory Polis customer needs to integrate a SAML IdP that isn't on the supported-vendor list (CyberArk, - ForgeRock, IBM Security Verify, custom in-house SAML), or wants the protocol mechanics documented for + ForgeRock, IBM Verify, custom in-house SAML), or wants the protocol mechanics documented for debugging or non-default configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-saml; Polis acts as the SAML SP, IdP as the IdP. - From the IdP: metadata XML (preferred — Polis can consume URL or upload), or manual entity-id / SSO URL / signing certificate paste. - - To the IdP: Polis SP metadata XML from the Ory organization's setup-link, or manual ACS URL / entity-id / certificate. + - To the IdP on Ory Network: ACS URL https://.projects.oryapis.com/saml/api/oauth/saml and SP entity ID https://.projects.oryapis.com/self-service/methods/saml/organizations/; self-hosted Polis uses its own SP metadata. - Attribute mapping defined IdP-side; Polis maps the released attributes to Ory identity traits. - - SP-initiated only — Polis does not consume IdP-initiated SAML responses. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Same content mirrored at generic-protocols/generic-saml — categorization choice; either entry resolves to the same Polis page. oryMechanism: - standards diff --git a/enterprise-sso/google-workspace/README.md b/enterprise-sso/google-workspace/README.md index 36d1a44..600ea31 100644 --- a/enterprise-sso/google-workspace/README.md +++ b/enterprise-sso/google-workspace/README.md @@ -2,18 +2,27 @@ > **Maintained by:** Ory Engineering -Configure [Google Workspace](https://workspace.google.com) (formerly G Suite) as a SAML Identity Provider into Ory Polis. One of the most common enterprise SSO integrations — most workforce identities already live in Workspace, and the Admin Console makes the SAML app setup straightforward. +Configure [Google Workspace](https://workspace.google.com) (formerly G Suite) as a SAML Identity Provider for enterprise single sign-on (SSO). One of the most common enterprise SSO integrations — most workforce identities already live in Workspace, and the Admin Console makes the SAML app setup straightforward. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/google-workspace](https://www.ory.com/docs/integrates-with/enterprise-sso/google-workspace) — full guide: [ory.com/docs/polis/sso-providers/google](https://www.ory.com/docs/polis/sso-providers/google) +## Ory Network connection values + +On Ory Network, add Google Workspace as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Google Workspace custom SAML app, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/google). Short version: 1. In the Google Workspace **Admin Console** → **Apps → Web and mobile apps**, click **Add app → Add custom SAML app**. 2. Download the IdP metadata XML (or copy the SSO URL, Entity ID, and certificate). -3. Configure the **Service Provider details** with Ory Polis's ACS URL and Entity ID from your Ory Network organization's setup-link. +3. Configure the **Service Provider details** with the ACS URL and SP entity ID from [Ory Network connection values](#ory-network-connection-values). 4. Set up the **attribute mapping** — at minimum: `Primary email` → `email`, `First name` → `firstName`, `Last name` → `lastName`. Add groups via the Group Membership attribute if you map them. 5. Enable the app for the relevant Google Workspace organizational units. @@ -21,7 +30,7 @@ The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs - Workspace requires the SAML app to be **enabled per OU** before users can sign in — easy to forget. - Group membership claims are released only when explicitly mapped in the SAML app's attribute mapping. -- For OIDC instead of SAML, configure Workspace as a Google OIDC provider via [`social-sign-in/google`](../../social-sign-in/google/) — but for true enterprise SSO with B2B per-organization isolation, SAML through Polis is the right path. +- For OIDC instead of SAML, configure Workspace as a Google OIDC provider via [`social-sign-in/google`](../../social-sign-in/google/) — but for true enterprise SSO with B2B per-organization isolation, a SAML connection on an organization is the right path. ## License diff --git a/enterprise-sso/hid-global/README.md b/enterprise-sso/hid-global/README.md index 9d4bfe7..280f3f8 100644 --- a/enterprise-sso/hid-global/README.md +++ b/enterprise-sso/hid-global/README.md @@ -4,22 +4,34 @@ [HID Global](https://www.hidglobal.com) provides trusted identity solutions across both physical (badge readers, smart cards, mobile credentials) and digital (SSO, MFA, certificate-based authentication) identity. Common in government, healthcare, financial services, and manufacturing where physical-facility access and digital-application access need a unified identity. -**Type:** config (generic OIDC or generic SAML in Ory Polis — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or generic SAML/OIDC in self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/hid-global](https://www.ory.com/docs/integrates-with/enterprise-sso/hid-global) -- [Polis SAML — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). -- [Polis OIDC — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). +- [Self-hosted Ory Polis — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). +- [Self-hosted Ory Polis — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). + +## Ory Network connection values + +On Ory Network, add HID as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the HID app, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. ## Setup outline 1. In the HID Global Authentication Service tenant, create a SAML 2.0 application (or OIDC application). -2. Paste the Ory Polis SP metadata into the HID app. +2. Enter the [Ory Network connection values](#ory-network-connection-values) in the HID app. When you self-host Ory Polis, paste your Ory Polis SP metadata instead. 3. Define the attribute release — at minimum `email`, `firstName`, `lastName`, plus any group claims you map. -4. In Ory Network, configure the SSO connection using the generic SAML/OIDC walkthrough; paste HID's metadata XML or OIDC discovery URL. +4. In Ory Network, add a SAML or OIDC connection to an organization; paste HID's metadata XML or OIDC discovery URL. ## Notes - HID's certificate-based authentication (smart cards / PIV / CAC) is enforced at the HID IdP layer; the Ory side simply consumes the resulting authenticated session. -- Step-up to physical badge / token authentication for high-value flows is typically configured as an HID policy that triggers re-auth before releasing the assertion to Polis. +- Step-up to physical badge / token authentication for high-value flows is typically configured as an HID policy that triggers re-auth before releasing the assertion to Ory. ## Status diff --git a/enterprise-sso/ibm-security-verify/README.md b/enterprise-sso/ibm-security-verify/README.md index 0a07003..09c3875 100644 --- a/enterprise-sso/ibm-security-verify/README.md +++ b/enterprise-sso/ibm-security-verify/README.md @@ -1,25 +1,37 @@ -# IBM Security Verify +# IBM Verify > **Maintained by:** Community contributors -[IBM Security Verify](https://www.ibm.com/products/verify-identity) is IBM's cloud-delivered identity and access management platform. It exposes standard OIDC and SAML 2.0 endpoints for federation. Configure as an upstream IdP in Ory Network so IBM-managed enterprise identities can sign in to Ory-protected applications. +[IBM Verify](https://www.ibm.com/products/verify-identity) (formerly IBM Security Verify) is IBM's cloud-delivered identity and access management platform. It exposes standard OIDC and SAML 2.0 endpoints for federation. Configure as an upstream IdP in Ory Network so IBM-managed enterprise identities can sign in to Ory-protected applications. -**Type:** config (generic OIDC or generic SAML in Ory Polis — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or generic SAML/OIDC in self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify](https://www.ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify) -- [Polis SAML — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). -- [Polis OIDC — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). +- [Self-hosted Ory Polis — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml). +- [Self-hosted Ory Polis — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc). + +## Ory Network connection values + +On Ory Network, add IBM Verify as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the IBM Verify application, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. ## Setup outline -1. In IBM Security Verify Admin → **Applications** → **Add application** — pick **Custom SAML 2.0** or **Custom OIDC**. -2. Configure the application with Ory Polis SP details from your Ory Network organization's setup-link. +1. In IBM Verify, go to **Applications** and add a custom application. On the **Sign-on** tab, set the sign-on method to **SAML2.0** or **OpenID Connect 1.0**. +2. Enter the [Ory Network connection values](#ory-network-connection-values) in the application. When you self-host Ory Polis, use your Ory Polis SP details instead. 3. Map the attribute release — IBM Verify exposes a flexible attribute mapper; map email, name, and any group claims you need. -4. In Ory Network, configure the SSO connection using the generic SAML/OIDC walkthrough; paste IBM's metadata XML or OIDC discovery URL + client credentials. +4. In Ory Network, add a SAML or OIDC connection to an organization; paste IBM's metadata XML or OIDC discovery URL + client credentials. ## Notes -- IBM Verify supports both Verify Cloud (SaaS) and Verify Access (on-prem) — the federation flows are the same; the difference is where you administer the IdP. -- IBM-style "access policies" with risk-based authentication stay on the IBM side; Polis consumes the resulting authenticated assertion. +- IBM Verify (SaaS) and IBM Verify Identity Access (on-premises, formerly IBM Security Verify Access) both support SAML 2.0 and OIDC federation; the difference is where you administer the IdP. +- IBM-style "access policies" with risk-based authentication stay on the IBM side; Ory consumes the resulting authenticated assertion. - For passkey / FIDO2 enforcement at the IdP layer, configure that in IBM Verify's policy engine — Ory simply consumes the assurance level reported in the assertion. ## Status diff --git a/enterprise-sso/ibm-security-verify/registry.entry.yaml b/enterprise-sso/ibm-security-verify/registry.entry.yaml index b4c37aa..8fbba6b 100644 --- a/enterprise-sso/ibm-security-verify/registry.entry.yaml +++ b/enterprise-sso/ibm-security-verify/registry.entry.yaml @@ -2,22 +2,22 @@ # Run `node scripts/build-registry.js` from the repo root to regenerate registry.yaml. name: ibm-security-verify -displayName: IBM Security Verify +displayName: IBM Verify vendor: IBM category: enterprise-sso type: config maintainedBy: Community contributors description: >- - Configure IBM Security Verify (IBM's cloud-delivered IAM platform) as an upstream SAML 2.0 or OIDC identity - provider in Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify; configures via the Polis generic SAML or generic OIDC walkthrough. + Configure IBM Verify (formerly IBM Security Verify, IBM's cloud-delivered IAM platform) as an upstream SAML 2.0 or OIDC identity + provider for an Ory Network organization or self-hosted Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify; configures via the Polis generic SAML or generic OIDC walkthrough. useCase: >- - An enterprise running IBM Security Verify (Verify Cloud SaaS or Verify Access on-prem) as their workforce IdP + An enterprise running IBM Verify (SaaS) or IBM Verify Identity Access (on-premises) as their workforce IdP wants Ory-protected applications to consume IBM-issued sessions instead of standing up a separate identity store. coreFunctionality: |- - Configured as a generic SAML 2.0 SP (preferred) or generic OIDC RP in Ory Polis pointing at an IBM Verify Custom SAML 2.0 / Custom OIDC application. - - Same federation flows for both Verify Cloud (SaaS) and Verify Access (on-prem) — difference is administration location. - - IBM access policies (risk-based auth, conditional access) stay on the IBM side; Polis consumes the resulting authenticated assertion. + - IBM Verify (SaaS) and IBM Verify Identity Access (on-premises, formerly IBM Security Verify Access) both support SAML 2.0 and OIDC federation — difference is administration location. + - IBM access policies (risk-based auth, conditional access) stay on the IBM side; Ory consumes the resulting authenticated assertion. - Passkey / FIDO2 enforcement configured in IBM Verify's policy engine; Ory consumes the assurance level reported in the assertion. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify. oryMechanism: diff --git a/enterprise-sso/jumpcloud/README.md b/enterprise-sso/jumpcloud/README.md index 0549d61..c5d73e5 100644 --- a/enterprise-sso/jumpcloud/README.md +++ b/enterprise-sso/jumpcloud/README.md @@ -2,17 +2,26 @@ > **Maintained by:** Ory Engineering -Configure [JumpCloud](https://jumpcloud.com) — the cloud directory platform — as a SAML 2.0 Identity Provider into Ory Polis. JumpCloud is the modern alternative to on-prem Active Directory and a common workforce IdP for organizations without legacy AD. +Configure [JumpCloud](https://jumpcloud.com) — the cloud directory platform — as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). JumpCloud is the modern alternative to on-prem Active Directory and a common workforce IdP for organizations without legacy AD. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/jumpcloud](https://www.ory.com/docs/integrates-with/enterprise-sso/jumpcloud) — full guide: [ory.com/docs/polis/sso-providers/jumpcloud](https://www.ory.com/docs/polis/sso-providers/jumpcloud) +## Ory Network connection values + +On Ory Network, add JumpCloud as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the JumpCloud SSO application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/jumpcloud). Short version: 1. In the **JumpCloud Admin console** → **SSO**, click the plus icon → **Custom SAML App**. -2. Configure the SP-side fields (IdP Entity ID, ACS URL, Audience URI) using the values from your Ory Network organization's setup-link. +2. Configure the SP-side fields (ACS URL, SP entity ID) using the values from [Ory Network connection values](#ory-network-connection-values). 3. Set up the **attribute mapping** — at minimum: `email`, `firstname`, `lastname`. Add group claims via the `memberOf` attribute if you map them. 4. Assign user groups to the SAML application. 5. Activate the application. diff --git a/enterprise-sso/keycloak/README.md b/enterprise-sso/keycloak/README.md index 4ad8032..fef622c 100644 --- a/enterprise-sso/keycloak/README.md +++ b/enterprise-sso/keycloak/README.md @@ -2,27 +2,40 @@ > **Maintained by:** Community contributors -[Keycloak](https://www.keycloak.org) is the open-source identity and access management server (originally Red Hat / now CNCF graduated). Speaks SAML 2.0, OIDC, and OAuth 2.0. Common choice for enterprises that need a self-hosted IdP — full control of the infrastructure, data residency, no vendor lock-in. +[Keycloak](https://www.keycloak.org) is the open-source identity and access management server (originally Red Hat / now a CNCF incubating project). Speaks SAML 2.0, OIDC, and OAuth 2.0. Common choice for enterprises that need a self-hosted IdP — full control of the infrastructure, data residency, no vendor lock-in. -**Type:** config (generic OIDC or generic SAML in Ory Polis — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or generic SAML/OIDC in self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/keycloak](https://www.ory.com/docs/integrates-with/enterprise-sso/keycloak) -- [Polis OIDC — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc) (recommended — Keycloak's OIDC support is first-class). -- [Polis SAML — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml) (when SAML is required by policy). +- [Self-hosted Ory Polis — generic OIDC provider](https://www.ory.com/docs/polis/sso-providers/generic-oidc) (recommended — Keycloak's OIDC support is first-class). +- [Self-hosted Ory Polis — generic SAML 2.0 SP](https://www.ory.com/docs/polis/sso-providers/generic-saml) (when SAML is required by policy). + +## Ory Network connection values + +On Ory Network, add Keycloak as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Keycloak client, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. ## Setup outline (OIDC, recommended) -1. In Keycloak Admin → **Clients** → **Create client** — pick **OpenID Connect**, set Client type to **Confidential**. -2. Set the **Valid redirect URI** to the Polis ACS URL from your Ory Network organization's setup-link. -3. Note the **Client ID** and the **Client Secret** (under the client's Credentials tab). -4. The Keycloak issuer URL is `https:///realms/` — Polis discovers via `/.well-known/openid-configuration` automatically. -5. In Ory Network, configure the SSO connection with issuer URL + client id + secret per the generic OIDC walkthrough. +1. In the Keycloak admin console, go to **Clients → Create client**. Leave **Client type** set to **OpenID Connect** and enter a client ID. +2. Turn **Client authentication** on. This makes the client confidential. +3. In **Valid redirect URIs**, enter the OIDC redirect URI for your connection's PKCE setting from [Ory Network connection values](#ory-network-connection-values). +4. Save the client, then copy the **Client Secret** from the **Credentials** tab. +5. The Keycloak issuer URL is `https:///realms/` — Ory discovers the endpoints via `/.well-known/openid-configuration` automatically. +6. In Ory Network, add an OIDC connection to an organization with the issuer URL, client ID, and client secret. For SAML, the steps are similar but use **Clients → Create client → SAML**, then export the IdP metadata XML and paste into Ory. ## Notes - Keycloak's "groups" are released by adding a **Group Membership** mapper to the client's dedicated client scope. Add this if you map roles or groups into Ory traits. -- Self-hosted Keycloak: pin both the Keycloak version and the Polis library version, and test upgrades against staging — Keycloak's protocol responses occasionally change in major releases. +- Self-hosted Keycloak: pin the Keycloak version, and test upgrades against staging — Keycloak's protocol responses occasionally change in major releases. - For Keycloak as a **downstream** SP (your app authenticates users via Keycloak that itself federates from another IdP), this entry doesn't apply — that's a Keycloak configuration concern. ## Status diff --git a/enterprise-sso/keycloak/registry.entry.yaml b/enterprise-sso/keycloak/registry.entry.yaml index 15def46..21d922c 100644 --- a/enterprise-sso/keycloak/registry.entry.yaml +++ b/enterprise-sso/keycloak/registry.entry.yaml @@ -8,8 +8,8 @@ category: enterprise-sso type: config maintainedBy: Community contributors description: >- - Configure Keycloak — the open-source CNCF-graduated identity and access management server — as an upstream - OIDC (preferred) or SAML 2.0 identity provider in Ory Polis. Common when an enterprise self-hosts their IdP + Configure Keycloak — the open-source, CNCF incubating identity and access management server — as an upstream + OIDC (preferred) or SAML 2.0 identity provider for an Ory Network organization or self-hosted Ory Polis. Common when an enterprise self-hosts their IdP for control, data residency, or vendor-lock-in avoidance. Documented at ory.com/docs/integrates-with/enterprise-sso/keycloak; configures via the Polis generic OIDC or generic SAML walkthrough. useCase: >- @@ -17,10 +17,10 @@ useCase: >- consume Keycloak-issued sessions instead of standing up a separate identity store. coreFunctionality: |- - Configured as a generic OIDC RP (recommended — Keycloak's OIDC support is first-class) or generic SAML SP in Ory Polis pointing at a Keycloak client. - - Keycloak side: Clients → Create client (OpenID Connect, Confidential type); set Valid redirect URI to Polis ACS URL. - - Issuer URL pattern: https:///realms/; Polis uses /.well-known/openid-configuration automatically. + - Keycloak side: Clients → Create client (OpenID Connect, Confidential type); turn Client authentication on; set Valid redirect URIs to the organization's OIDC redirect URI (https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/, or /self-service/methods/oidc/callback with pkce: force). + - Issuer URL pattern: https:///realms/; Ory uses /.well-known/openid-configuration automatically. - Group claims released via a Group Membership mapper on the client's dedicated client scope — must be added explicitly. - - Self-hosted: pin both Keycloak and Polis library versions; test upgrades against staging since Keycloak's protocol responses occasionally change in major releases. + - Self-hosted: pin the Keycloak version; test upgrades against staging since Keycloak's protocol responses occasionally change in major releases. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/keycloak. oryMechanism: - standards diff --git a/enterprise-sso/microsoft-adfs/README.md b/enterprise-sso/microsoft-adfs/README.md index 908e889..591726c 100644 --- a/enterprise-sso/microsoft-adfs/README.md +++ b/enterprise-sso/microsoft-adfs/README.md @@ -2,17 +2,26 @@ > **Maintained by:** Ory Engineering -Configure on-premises **Microsoft Active Directory Federation Services (AD FS)** as a SAML 2.0 Identity Provider into Ory Polis. Common path for enterprises maintaining on-prem Active Directory who want SSO to cloud apps without migrating to Entra ID. +Configure on-premises **Microsoft Active Directory Federation Services (AD FS)** as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Common path for enterprises maintaining on-prem Active Directory who want SSO to cloud apps without migrating to Entra ID. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/microsoft-adfs](https://www.ory.com/docs/integrates-with/enterprise-sso/microsoft-adfs) — full guide: [ory.com/docs/polis/sso-providers/microsoft-adfs](https://www.ory.com/docs/polis/sso-providers/microsoft-adfs) +## Ory Network connection values + +On Ory Network, add AD FS as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the AD FS relying party trust, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/microsoft-adfs). Short version: 1. In **AD FS Management** → **Relying Party Trusts** → **Add Relying Party Trust**. -2. Choose **Import data about the relying party from a file** and upload the Polis SP metadata XML from your Ory Network organization's setup-link (or paste the metadata URL). +2. Choose **Import data about the relying party from a file** and upload the SP metadata XML, or choose **Enter data about the relying party manually** and enter the ACS URL and SP entity ID from [Ory Network connection values](#ory-network-connection-values). 3. Configure the **Claim Issuance Policy**: - LDAP attribute mapping: `E-Mail-Addresses → Email Address`, `Given-Name → Given Name`, `Surname → Surname`. - Send LDAP attributes as claims; transform to NameID format `Email`. @@ -21,9 +30,9 @@ The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs ## Notes - AD FS supports both 2016 and 2019/2022 versions; the SAML federation flow is the same — minor UI differences in the management console. -- Token signing certificate auto-rollover requires updating the metadata in Polis when the cert rotates (typically yearly). Subscribe to AD FS event 102 (cert rollover) or pull metadata on a schedule. +- Token signing certificate auto-rollover requires updating the IdP metadata on the Ory SAML connection when the cert rotates (typically yearly). Subscribe to AD FS event 102 (cert rollover) or pull metadata on a schedule. - For groups, add a **Group SID** or **Token-Groups - Unqualified Names** claim and map it server-side in Ory. -- AD FS over WS-Federation is **not supported** — Polis only consumes SAML 2.0. +- AD FS over WS-Federation is **not supported** — Ory only consumes SAML 2.0. ## License diff --git a/enterprise-sso/microsoft-entra-id/README.md b/enterprise-sso/microsoft-entra-id/README.md index c2c9e1c..9ac877c 100644 --- a/enterprise-sso/microsoft-entra-id/README.md +++ b/enterprise-sso/microsoft-entra-id/README.md @@ -2,18 +2,27 @@ > **Maintained by:** Ory Engineering -Configure [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure Active Directory) as a SAML 2.0 Identity Provider into Ory Polis. Entra ID is the default IdP for organizations on Microsoft 365 / Azure — the most common enterprise SSO integration alongside Google Workspace. +Configure [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure Active Directory) as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Entra ID is the default IdP for organizations on Microsoft 365 / Azure — the most common enterprise SSO integration alongside Google Workspace. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/microsoft-entra-id](https://www.ory.com/docs/integrates-with/enterprise-sso/microsoft-entra-id) — full guide: [ory.com/docs/polis/sso-providers/azure](https://www.ory.com/docs/polis/sso-providers/azure) +## Ory Network connection values + +On Ory Network, add Microsoft Entra ID as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Entra ID enterprise application's SAML settings, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/azure). Short version: 1. In **Microsoft Entra Admin Center** → **Enterprise applications** → **New application** → **Create your own application**, choose **Integrate any other application you don't find in the gallery (Non-gallery)**. 2. Under the new app → **Single sign-on** → **SAML**, configure: - - **Identifier (Entity ID)** and **Reply URL (ACS)** from your Ory Network organization's setup-link. + - **Identifier (Entity ID)** and **Reply URL (ACS)** from [Ory Network connection values](#ory-network-connection-values). 3. Download the **Federation Metadata XML** and paste into Ory's organization SSO connection. 4. Configure user/group **assignments** to the application — by default Entra ID requires explicit assignment (this can be disabled per app, but explicit is safer). 5. Adjust the **claims** if you need anything beyond `email`/`given_name`/`surname`/`name` — Entra ID's defaults are usually fine. @@ -22,7 +31,7 @@ The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs - **Assignment required** is on by default — easy to forget. Users must be in an assigned group (or directly assigned) to sign in even if they exist in the tenant. - Entra ID's **Conditional Access** policies (MFA, device compliance, named locations) sit at the IdP layer; the resulting authenticated assertion flows through to Ory unchanged. -- For OIDC sign-in (typically consumer or low-friction), use [`social-sign-in/microsoft`](../../social-sign-in/microsoft/) — Polis SAML is for B2B enterprise SSO with per-organization isolation. +- For OIDC sign-in (typically consumer or low-friction), use [`social-sign-in/microsoft`](../../social-sign-in/microsoft/) — a SAML connection on an organization is for B2B enterprise SSO with per-organization isolation. - For SCIM provisioning of Entra ID users into Ory, see [`directory-sync/microsoft-scim`](../../directory-sync/microsoft-scim/) — separate concern from SSO. ## License diff --git a/enterprise-sso/okta/README.md b/enterprise-sso/okta/README.md index e52cdc9..1b2029e 100644 --- a/enterprise-sso/okta/README.md +++ b/enterprise-sso/okta/README.md @@ -2,20 +2,32 @@ > **Maintained by:** Ory Engineering -Configure [Okta](https://www.okta.com) as a SAML 2.0 (preferred for B2B SSO) or OIDC Identity Provider into Ory Polis. Okta is the dominant cloud workforce identity platform — a near-default option in most enterprise SSO conversations. +Configure [Okta](https://www.okta.com) as a SAML 2.0 (preferred for B2B SSO) or OIDC Identity Provider for enterprise single sign-on (SSO). Okta is the dominant cloud workforce identity platform — a near-default option in most enterprise SSO conversations. -**Type:** config (Polis SAML or OIDC connection — no webhook code) +**Type:** config (SAML or OIDC connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/okta](https://www.ory.com/docs/integrates-with/enterprise-sso/okta) — full guide: [ory.com/docs/polis/sso-providers/okta](https://www.ory.com/docs/polis/sso-providers/okta) +## Ory Network connection values + +On Ory Network, add Okta as a SAML or OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Okta app integration, enter these values: + +- **SAML ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SAML SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/okta). Short version: 1. In the **Okta Admin Console** → **Applications** → **Create App Integration** → choose **SAML 2.0**. 2. On the SAML Settings step, configure: - - **Single sign-on URL** = Polis ACS URL. - - **Audience URI (SP Entity ID)** = Polis Entity ID. - - Both from your Ory Network organization's setup-link. + - **Single sign-on URL** = ACS URL. + - **Audience URI (SP Entity ID)** = SP entity ID. + - Both from [Ory Network connection values](#ory-network-connection-values). 3. Add the standard attribute statements: `email`, `firstName`, `lastName`. Add a Group attribute statement if you map groups. 4. Assign people / groups to the application. 5. From the application's **Sign On** tab, copy the **Identity Provider metadata** URL (or download the XML) and paste into Ory. diff --git a/enterprise-sso/okta/ory-console-steps.md b/enterprise-sso/okta/ory-console-steps.md index a46b091..c94787c 100644 --- a/enterprise-sso/okta/ory-console-steps.md +++ b/enterprise-sso/okta/ory-console-steps.md @@ -1,6 +1,6 @@ # Okta — Ory Console setup steps -This is the manual setup flow for adding Okta as an OIDC social-signin provider to an Ory Network project. The full walkthrough with screenshots lives at [ory.com/docs/integrations/okta](https://ory.com/docs/integrations/okta). +This is the manual setup flow for adding Okta as an OIDC social-signin provider to an Ory Network project. The full walkthrough with screenshots lives at [ory.com/docs/integrates-with/enterprise-sso/okta](https://www.ory.com/docs/integrates-with/enterprise-sso/okta). ## 1. Create the Okta application @@ -46,16 +46,18 @@ By default Okta returns `sub`, `email`, `name`, and `picture` in the `profile` a { identity: { traits: { - email: claims.email, + [if 'email' in claims && claims.email_verified then 'email' else null]: claims.email, name: { - first: claims.given_name, - last: claims.family_name, + [if 'given_name' in claims then 'first' else null]: claims.given_name, + [if 'family_name' in claims then 'last' else null]: claims.family_name, }, }, }, } ``` + This mapping works with identity schemas that define `email`, `name.first`, and `name.last` traits, such as `preset://basic`. Okta leaves out claims it has no value for, so the mapping only sets a trait when its claim is present. + 6. Click **Save**. ## 4. Test diff --git a/enterprise-sso/okta/registry.entry.yaml b/enterprise-sso/okta/registry.entry.yaml index 7dd1850..2025cae 100644 --- a/enterprise-sso/okta/registry.entry.yaml +++ b/enterprise-sso/okta/registry.entry.yaml @@ -17,7 +17,7 @@ useCase: >- coreFunctionality: |- - Configured per Ory Polis docs at /polis/sso-providers/okta; Polis acts as the SAML SP / OIDC RP, Okta as the IdP. - Okta side: Applications → Create App Integration → SAML 2.0 (preferred) or OIDC Web Application. - - SAML: Single sign-on URL = Polis ACS URL; Audience URI = Polis Entity ID; both from Ory's setup-link. + - SAML on Ory Network: Single sign-on URL = https://.projects.oryapis.com/saml/api/oauth/saml; Audience URI = https://.projects.oryapis.com/self-service/methods/saml/organizations/. - Attribute statements: email, firstName, lastName. Groups released only if explicitly mapped in attribute statements (SAML) or claims (OIDC). - Sign-on Policies (MFA, network zones, device trust) sit at the Okta layer; resulting authenticated assertion flows through to Ory. - For SCIM provisioning of Okta users into Ory, see directory-sync/okta-scim (separate concern). diff --git a/enterprise-sso/onelogin/README.md b/enterprise-sso/onelogin/README.md index 12f97a3..8026c9c 100644 --- a/enterprise-sso/onelogin/README.md +++ b/enterprise-sso/onelogin/README.md @@ -2,17 +2,26 @@ > **Maintained by:** Ory Engineering -Configure [OneLogin](https://www.onelogin.com) (One Identity) as a SAML 2.0 Identity Provider into Ory Polis. Common workforce IdP; competes in the same space as Okta and JumpCloud. +Configure [OneLogin](https://www.onelogin.com) (One Identity) as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Common workforce IdP; competes in the same space as Okta and JumpCloud. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/onelogin](https://www.ory.com/docs/integrates-with/enterprise-sso/onelogin) — full guide: [ory.com/docs/polis/sso-providers/onelogin](https://www.ory.com/docs/polis/sso-providers/onelogin) +## Ory Network connection values + +On Ory Network, add OneLogin as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the OneLogin SAML application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/onelogin). Short version: 1. In the **OneLogin Admin Portal** → **Applications** → **Add App**, search for **SAML Custom Connector (Advanced)** and add it. -2. Configure the SAML configuration with values from your Ory Network organization's setup-link: +2. Configure the SAML configuration with values from [Ory Network connection values](#ory-network-connection-values): - **Audience (EntityID)**, **Recipient**, **ACS (Consumer) URL**, **ACS (Consumer) URL Validator** (regex match against ACS URL). 3. Add **Parameters** for the user attributes you map: `Email` → `Email`, `firstName` → `First Name`, `lastName` → `Last Name`. Add a Groups parameter if you map them. 4. Assign users / roles to the application. diff --git a/enterprise-sso/pingone/README.md b/enterprise-sso/pingone/README.md index b20919b..70ec7a2 100644 --- a/enterprise-sso/pingone/README.md +++ b/enterprise-sso/pingone/README.md @@ -2,17 +2,26 @@ > **Maintained by:** Ory Engineering -Configure [PingOne](https://www.pingidentity.com/en/platform/capabilities/single-sign-on.html) — Ping Identity's cloud-based identity platform — as a SAML 2.0 Identity Provider into Ory Polis. Common in regulated industries (financial services, healthcare, government) where Ping's compliance posture and governance features matter. +Configure [PingOne](https://www.pingidentity.com/en/platform/capabilities/single-sign-on.html) — Ping Identity's cloud-based identity platform — as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Common in regulated industries (financial services, healthcare, government) where Ping's compliance posture and governance features matter. -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/pingone](https://www.ory.com/docs/integrates-with/enterprise-sso/pingone) — full guide: [ory.com/docs/polis/sso-providers/pingone](https://www.ory.com/docs/polis/sso-providers/pingone) +## Ory Network connection values + +On Ory Network, add PingOne as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the PingOne SAML application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/pingone). Short version: 1. In the **PingOne Admin Console** → **Connections** → **Applications** → **+** → **Add Application** → choose **Web App** → **SAML**. -2. Configure the SAML application with values from your Ory Network organization's setup-link: +2. Configure the SAML application with values from [Ory Network connection values](#ory-network-connection-values): - **ACS URL** and **Entity ID**. 3. Configure **Attribute Mapping**: `email`, `firstName`, `lastName`. Add a Group attribute mapping if you map them. 4. Assign user / group **Access** to the application. diff --git a/enterprise-sso/rippling/README.md b/enterprise-sso/rippling/README.md index f001813..05f0213 100644 --- a/enterprise-sso/rippling/README.md +++ b/enterprise-sso/rippling/README.md @@ -2,17 +2,26 @@ > **Maintained by:** Ory Engineering -Configure [Rippling](https://www.rippling.com) — the unified workforce platform combining HR, IT, and Finance — as a SAML 2.0 Identity Provider into Ory Polis. Less common as a pure SSO IdP than Okta or Entra ID, but a natural fit for organizations already using Rippling for HR/IT-driven access lifecycle (onboard / offboard / role-change events trigger access changes automatically). +Configure [Rippling](https://www.rippling.com) — the unified workforce platform combining HR, IT, and Finance — as a SAML 2.0 Identity Provider for enterprise single sign-on (SSO). Less common as a pure SSO IdP than Okta or Entra ID, but a natural fit for organizations already using Rippling for HR/IT-driven access lifecycle (onboard / offboard / role-change events trigger access changes automatically). -**Type:** config (Polis SAML connection — no webhook code) +**Type:** config (SAML connection on an Ory Network organization, or self-hosted Ory Polis — no webhook code) **Docs page:** [ory.com/docs/integrates-with/enterprise-sso/rippling](https://www.ory.com/docs/integrates-with/enterprise-sso/rippling) — full guide: [ory.com/docs/polis/sso-providers/rippling](https://www.ory.com/docs/polis/sso-providers/rippling) +## Ory Network connection values + +On Ory Network, add Rippling as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the Rippling SAML app, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Setup The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs/polis/sso-providers/rippling). Short version: 1. In the **Rippling Admin Portal** → **IT Management** → **Single Sign-On** → **Add Custom App** → choose **SAML**. -2. Configure the SAML configuration with values from your Ory Network organization's setup-link: +2. Configure the SAML configuration with values from [Ory Network connection values](#ory-network-connection-values): - **ACS URL**, **SP Entity ID**. 3. Configure attribute mapping — Rippling maps HR fields (work email, first name, last name, department, employee ID) to SAML attributes. 4. Define **role-based access policies** in Rippling — who in the workforce gets access to this app. The HR-driven assignment is Rippling's distinguishing feature. diff --git a/generic-protocols/generic-oidc/README.md b/generic-protocols/generic-oidc/README.md index 597ae32..2d875f1 100644 --- a/generic-protocols/generic-oidc/README.md +++ b/generic-protocols/generic-oidc/README.md @@ -5,7 +5,7 @@ Configure any OpenID Connect-compliant Identity Provider with Ory. OIDC shows up in two Ory product surfaces: - **Ory Kratos social sign-in / federated sign-in** — for consumer or user-facing sign-in flows. Kratos is the OIDC Relying Party. -- **Ory Polis enterprise SSO** — for B2B SSO with per-organization isolation. Polis is the OIDC Relying Party on behalf of an organization. +- **Enterprise SSO for organizations** — for B2B SSO with per-organization isolation. On Ory Network, add the IdP as an OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations); Ory Kratos is the OIDC Relying Party. When you self-host Ory Polis, Ory Polis is the OIDC Relying Party on behalf of an organization. > Same source page as [`enterprise-sso/generic-oidc`](../../enterprise-sso/generic-oidc/) — categorization choice. @@ -14,12 +14,22 @@ Configure any OpenID Connect-compliant Identity Provider with Ory. OIDC shows up - Kratos generic OIDC: [ory.com/docs/kratos/social-signin/generic](https://www.ory.com/docs/kratos/social-signin/generic) - Polis generic OIDC: [ory.com/docs/polis/sso-providers/generic-oidc](https://www.ory.com/docs/polis/sso-providers/generic-oidc) +## Ory Network connection values + +On Ory Network, add the IdP as an OIDC connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project, using the IdP's issuer URL, client ID, and client secret. In the IdP's client settings, set this value: + +- **OIDC redirect URI:** `https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/` + +With `pkce: force`, the OIDC redirect URI is `https://.projects.oryapis.com/self-service/methods/oidc/callback` instead. Register the URI for your connection's PKCE setting, using the project's custom domain if configured. + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## Which one to use | Use case | Product | Configure as | | --- | --- | --- | | "Sign in with X" for end users | Kratos | Social sign-in provider | -| "B2B SSO — let an enterprise customer's IdP authenticate their users" | Polis | OIDC Relying Party per organization | +| "B2B SSO — let an enterprise customer's IdP authenticate their users" | Ory Network organizations (or self-hosted Polis) | OIDC connection per organization | | Vendor without a dedicated guide that speaks OIDC | Either | Whichever fits the use case | ## What you'll need from the IdP @@ -29,7 +39,7 @@ Configure any OpenID Connect-compliant Identity Provider with Ory. OIDC shows up | Issuer URL | Discovered via `/.well-known/openid-configuration` automatically. | | Client ID | Created when registering Ory as an OIDC client on the IdP side. | | Client Secret | Same — store in secrets backend, never source. | -| Redirect URI | Ory's callback URL (different for Kratos vs Polis). | +| Redirect URI | Ory's callback URL. Social sign-in uses `/self-service/methods/oidc/callback/`; organization connections use the URI in [Ory Network connection values](#ory-network-connection-values). | | Scopes | At minimum `openid`, plus `profile` / `email` / `groups` as needed. | ## License diff --git a/generic-protocols/generic-oidc/registry.entry.yaml b/generic-protocols/generic-oidc/registry.entry.yaml index 9b6725d..da5d300 100644 --- a/generic-protocols/generic-oidc/registry.entry.yaml +++ b/generic-protocols/generic-oidc/registry.entry.yaml @@ -9,8 +9,8 @@ type: config maintainedBy: Ory Engineering description: >- Configure any OpenID Connect-compliant Identity Provider with Ory. OIDC shows up in two product surfaces: - Ory Kratos (consumer / federated sign-in — Kratos is the RP) and Ory Polis (B2B enterprise SSO with - per-organization isolation — Polis is the RP). Same source content mirrored under enterprise-sso/generic-oidc. + Ory Kratos (consumer / federated sign-in — Kratos is the RP) and B2B enterprise SSO with per-organization + isolation (an OIDC connection on an Ory Network organization, or self-hosted Ory Polis). Same source content mirrored under enterprise-sso/generic-oidc. useCase: >- An Ory customer needs to integrate an OIDC IdP that isn't on a vendor-specific docs list — open-source IdPs (Keycloak, Authentik, Zitadel), in-house implementations, or any custom OIDC server. Same reference works @@ -18,7 +18,7 @@ useCase: >- coreFunctionality: |- - Two product surfaces: Kratos social sign-in (docs/kratos/social-signin/generic — for consumer/user-facing flows) and Polis (docs/polis/sso-providers/generic-oidc — for B2B enterprise SSO). - Discovery via /.well-known/openid-configuration on the issuer URL — Ory fetches and caches automatically. - - Required from the IdP: issuer URL, client id, client secret, plus the Ory callback URL configured as redirect URI. + - Required from the IdP: issuer URL, client id, client secret, plus the Ory callback URL configured as redirect URI (/self-service/methods/oidc/callback/ for social sign-in, /self-service/methods/oidc/organization//callback/ for organization connections, or /self-service/methods/oidc/callback with pkce: force). - Standard scopes: openid (required), profile, email; groups when claim mapping needs them. - Same content mirrored at enterprise-sso/generic-oidc — categorization choice; either entry resolves to the same authoritative Ory docs. oryMechanism: diff --git a/generic-protocols/generic-saml/README.md b/generic-protocols/generic-saml/README.md index 878f773..c9af1ea 100644 --- a/generic-protocols/generic-saml/README.md +++ b/generic-protocols/generic-saml/README.md @@ -2,24 +2,33 @@ > **Maintained by:** Ory Engineering -Configure any SAML 2.0-compliant Identity Provider with Ory. SAML support in Ory is provided by **Ory Polis** (formerly SAML Jackson) acting as the SAML Service Provider — Kratos itself does not natively speak SAML. +Configure any SAML 2.0-compliant Identity Provider with Ory. On Ory Network, add the IdP as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations), and Ory Network acts as the SAML Service Provider (SP), with no Ory Polis deployment of your own. SAML connections are available on select Ory Network Enterprise plans. When you self-host, **Ory Polis** (formerly SAML Jackson) acts as the SAML SP. > Same source page as [`enterprise-sso/generic-saml`](../../enterprise-sso/generic-saml/) — categorization choice. **Type:** config (no webhook code) **Docs page:** [ory.com/docs/integrates-with/generic-protocols/generic-saml](https://www.ory.com/docs/integrates-with/generic-protocols/generic-saml) — full guide: [ory.com/docs/polis/sso-providers/generic-saml](https://www.ory.com/docs/polis/sso-providers/generic-saml) +## Ory Network connection values + +On Ory Network, add the IdP as a SAML connection to an [organization](https://www.ory.com/docs/kratos/organizations) in your project. In the IdP's SAML application, enter these values: + +- **ACS URL:** `https://.projects.oryapis.com/saml/api/oauth/saml` +- **SP entity ID:** `https://.projects.oryapis.com/self-service/methods/saml/organizations/` + +The Ory Console shows these values when you add the connection. When you self-host Ory Polis, use the URLs of your own Ory Polis deployment instead. + ## When to use - Your IdP is **not listed** in [`polis/sso-providers/`](https://www.ory.com/docs/polis/sso-providers/) but speaks SAML 2.0. - Your IdP **is listed** but you want the underlying mechanics for debugging or non-default configuration. -- You're integrating a less-common IdP (CyberArk, ForgeRock, IBM Security Verify, in-house Shibboleth, SimpleSAMLphp, custom SAML). +- You're integrating a less-common IdP (CyberArk, ForgeRock, IBM Verify, in-house Shibboleth, SimpleSAMLphp, custom SAML). ## What you'll need from the IdP | Field | Source | | --- | --- | -| IdP Metadata XML | Most IdPs publish this at a metadata URL or as a downloadable XML file. Polis can consume either. | +| IdP Metadata XML | Most IdPs publish this at a metadata URL or as a downloadable XML file. Ory can consume either. | | Or: IdP Entity ID, SSO URL, signing certificate | If no metadata XML available, paste manually. | | Attribute mapping | Define what the IdP sends as `email`, `firstName`, `lastName`, `groups`, etc. | @@ -27,10 +36,10 @@ Configure any SAML 2.0-compliant Identity Provider with Ory. SAML support in Ory | Field | Source | | --- | --- | -| Polis SP Metadata XML | From your Ory Network organization's setup-link. The IdP uses this to know where to send the SAML assertion. | +| SP values | The ACS URL and SP entity ID from [Ory Network connection values](#ory-network-connection-values), or your self-hosted Ory Polis SP metadata. The IdP uses this to know where to send the SAML assertion. | | Or: ACS URL, Entity ID, signing certificate | Same data, manual paste. | -Polis is **SP-initiated only** — it does not consume IdP-initiated SAML responses. +SAML connections on Ory Network support IdP-initiated login. It's off by default. See [IdP-initiated login](https://www.ory.com/docs/kratos/organizations#idp-initiated-login). ## License diff --git a/generic-protocols/generic-saml/registry.entry.yaml b/generic-protocols/generic-saml/registry.entry.yaml index 3925635..3031aad 100644 --- a/generic-protocols/generic-saml/registry.entry.yaml +++ b/generic-protocols/generic-saml/registry.entry.yaml @@ -8,19 +8,19 @@ category: generic-protocols type: config maintainedBy: Ory Engineering description: >- - Configure any SAML 2.0-compliant Identity Provider with Ory. SAML support is provided by Ory Polis (formerly - SAML Jackson) acting as the SAML Service Provider — Kratos does not natively speak SAML. Same source content + Configure any SAML 2.0-compliant Identity Provider with Ory. On Ory Network, add the IdP as a SAML connection to an + organization and Ory Network acts as the SAML Service Provider; when self-hosting, Ory Polis (formerly SAML Jackson) is the SP. Same source content mirrored under enterprise-sso/generic-saml. useCase: >- An Ory Polis customer needs to integrate a SAML IdP that isn't on the supported-vendor list (CyberArk, - ForgeRock, IBM Security Verify, in-house Shibboleth or SimpleSAMLphp, custom SAML), or wants the protocol + ForgeRock, IBM Verify, in-house Shibboleth or SimpleSAMLphp, custom SAML), or wants the protocol mechanics documented for debugging or non-default configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-saml; Polis acts as the SAML SP, IdP as the IdP. - From the IdP: metadata XML (preferred — Polis can consume URL or upload), or manual entity-id / SSO URL / signing certificate paste. - - To the IdP: Polis SP metadata XML from the Ory organization's setup-link, or manual ACS URL / entity-id / certificate. + - To the IdP on Ory Network: ACS URL https://.projects.oryapis.com/saml/api/oauth/saml and SP entity ID https://.projects.oryapis.com/self-service/methods/saml/organizations/; self-hosted Polis uses its own SP metadata. - Attribute mapping defined IdP-side; Polis maps the released attributes to Ory identity traits. - - SP-initiated only — Polis does not consume IdP-initiated SAML responses. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Same content mirrored at enterprise-sso/generic-saml — categorization choice; either entry resolves to the same authoritative Ory Polis page. oryMechanism: - standards diff --git a/government-identity/aadhaar/README.md b/government-identity/aadhaar/README.md index 52da06e..f606fd0 100644 --- a/government-identity/aadhaar/README.md +++ b/government-identity/aadhaar/README.md @@ -25,7 +25,7 @@ Common licensed providers: ## Setup outline 1. Sign up with a licensed Aadhaar eKYC provider; complete KYB and licensing. -2. Configure an Ory Actions webhook on `registration.after` (async) pointing at your verification service. +2. Configure an Ory Actions web hook pointing at your verification service, without `response.parse`, in a registration method list such as `selfservice.flows.registration.after.password.hooks`. That hook runs after Ory saves the identity, so it receives the real identity ID. Hooks with `response.parse: true` run before the identity is saved and receive the ID `00000000-0000-0000-0000-000000000000`. Ory runs the global `selfservice.flows.registration.after.hooks` list only for a method that has no hooks of its own. 3. Your service kicks off the OTP-based eKYC flow with the licensed provider. 4. After the user completes OTP verification, write the verified eKYC fields back to Ory `metadata_public.aadhaar` via the Kratos Admin API. diff --git a/government-identity/aadhaar/registry.entry.yaml b/government-identity/aadhaar/registry.entry.yaml index 9a9083f..21e8853 100644 --- a/government-identity/aadhaar/registry.entry.yaml +++ b/government-identity/aadhaar/registry.entry.yaml @@ -16,6 +16,7 @@ useCase: >- identity verification at signup and is willing to integrate via a licensed eKYC provider. coreFunctionality: |- - Architecture: Ory Kratos webhook → your verification service → licensed ASA/AUA provider → UIDAI CIDR. + - The webhook runs without response.parse in a registration method hook list (e.g. selfservice.flows.registration.after.password.hooks) so it runs after the identity is saved and receives the real identity ID for the Admin API write-back. - Common licensed providers: Signzy, Digio, Karza Technologies, IDfy. Direct UIDAI API access is prohibited. - OTP-based eKYC flow is the typical path; biometric flow is also possible but requires registered devices. - Compliance non-negotiables: NEVER store the full Aadhaar number (mask / last 4 only); explicit `consent: "Y"` per call; data localization (Aadhaar-derived data must stay in India — keep full eKYC in India-hosted infra, only store masked/verified-status in Ory metadata which is global); 5-year audit trail. diff --git a/government-identity/eidas/README.md b/government-identity/eidas/README.md index 365d0e4..a00f4d5 100644 --- a/government-identity/eidas/README.md +++ b/government-identity/eidas/README.md @@ -36,7 +36,9 @@ Common brokers: ## Assurance levels -eIDAS defines three assurance levels — map these to Ory session AAL: +eIDAS defines three levels of assurance (LoA): low, substantial, and high. The broker reports the level in the ID token's `acr` claim. The eIDAS specifications identify the levels as `http://eidas.europa.eu/LoA/low`, `http://eidas.europa.eu/LoA/substantial`, and `http://eidas.europa.eu/LoA/high`. Check which values your broker emits. + +Decide which levels count as AAL2 for your sessions: | eIDAS LoA | Description | Ory AAL | | --- | --- | --- | @@ -44,7 +46,31 @@ eIDAS defines three assurance levels — map these to Ory session AAL: | Substantial | Verified via national eID, no biometrics | aal1 / aal2 | | High | Hardware-backed, biometric, or in-person | aal2 | -The broker reports the LoA in the ID token; map it in Jsonnet and surface as `metadata_public.eidas.loa` for downstream policy. +Mapping the LoA into identity metadata with Jsonnet doesn't change the session's authenticator assurance level (AAL). To mark a session as AAL2, list the matching `acr` values in the provider's `aal2_acr_values`. Ory compares them with the `acr` claim at every sign-in: + +```yaml +selfservice: + methods: + oidc: + enabled: true + config: + providers: + - id: eidas + provider: generic + client_id: + client_secret: + issuer_url: + mapper_url: base64:// + scope: + - openid + - profile + aal2_acr_values: + - http://eidas.europa.eu/LoA/high +``` + +Sessions with any other `acr` value stay at AAL1. To ask the broker for a specific level, include `upstream_parameters: {"acr_values": "http://eidas.europa.eu/LoA/high"}` when submitting the login flow with `method: oidc` and the provider ID. See [Upstream MFA carry-over](https://www.ory.com/docs/kratos/social-signin/upstream-mfa). + +You can still map the LoA to `metadata_public.eidas.loa` with Jsonnet for downstream policy. ## Status diff --git a/government-identity/eidas/registry.entry.yaml b/government-identity/eidas/registry.entry.yaml index b9531af..92e2120 100644 --- a/government-identity/eidas/registry.entry.yaml +++ b/government-identity/eidas/registry.entry.yaml @@ -18,7 +18,7 @@ useCase: >- coreFunctionality: |- - Configured as a generic OIDC provider in Kratos pointing at the broker's issuer; broker handles per-country eIDAS node integration. - Common brokers: Signicat (pan-EU), Criipto (Nordic + EU), IDnow, yes.com (DE). - - eIDAS Levels of Assurance: Low / Substantial / High — broker reports LoA in the ID token; Jsonnet maps to identity metadata for downstream policy. Substantial roughly maps to Ory aal1; High to aal2. + - eIDAS Levels of Assurance: Low / Substantial / High — broker reports LoA in the ID token's acr claim (e.g. http://eidas.europa.eu/LoA/high). List the acr values that count as AAL2 in the provider's aal2_acr_values; Jsonnet metadata mapping alone doesn't change the session AAL. Request a level with upstream_parameters acr_values. - Per-country eID schemes vary in user experience (card reader for DE Personalausweis, mobile app for FR FranceConnect, etc.) — the broker abstracts this. - Status: community/proposed — documented at ory.com/docs/integrates-with/government-identity/eidas; configures via the generic OIDC path once a broker is chosen. oryMechanism: diff --git a/registry.yaml b/registry.yaml index e95f115..b3b81c4 100644 --- a/registry.yaml +++ b/registry.yaml @@ -8,7 +8,7 @@ apiVersion: ory.com/integrations-v1 kind: Registry metadata: name: ory-integrates - generated: 2026-08-31T14:26:35Z + generated: 2026-10-08T18:28:36Z integrations: - name: skyfire displayName: Skyfire @@ -20,18 +20,18 @@ integrations: status: active description: >- Pair Skyfire's "Know Your Agent" (KYA) verification with Ory for AI-agent identity — Skyfire issues verifiable - credentials per agent; a customer-built provisioning service maps each Skyfire agent to an Ory Kratos identity, - and Hydra issues OAuth2 access tokens (client_credentials) for the agent to call APIs. + credentials per agent; a customer-built provisioning service maps each Skyfire agent to an Ory Hydra OAuth2 + client, and Hydra issues OAuth2 access tokens (client_credentials) for the agent to call APIs. useCase: >- A product running autonomous AI agents that need to authenticate to backend APIs wants the agents to have verifiable identity (so the call site can answer "which agent is this and is it KYA-verified") plus per-agent spend controls — patterns that combining Skyfire and Ory makes natural. coreFunctionality: |- - - Each agent = one Kratos identity (not one user with multiple agents) — keeps audit and revocation clean. - - metadata_public.skyfire stores agent_id + kya_status on the Kratos identity. - - Ory Hydra issues access tokens via client_credentials; sub = Kratos identity id. - - API gateways validate tokens at the edge (see api-gateways/*) and can read metadata_public.skyfire.agent_id for access control. - - Skyfire can revoke agents — periodically re-check KYA status before token issuance to respect revocations. + - Each agent = one Hydra OAuth2 client (not one user with multiple agents) — keeps audit and revocation clean. + - The client's metadata stores skyfire.agent_id + kya_status. + - Ory Hydra issues access tokens via client_credentials; sub = the OAuth2 client ID. + - API gateways validate tokens at the edge (see api-gateways/*) and map sub to the agent via the client's metadata, or read an agent ID claim added by an OAuth2 token webhook. + - Skyfire can revoke agents — re-check KYA status on token issuance; the OAuth2 token webhook runs on every token request and can deny it with 403. - Payment / spend controls stay on the Skyfire side. - Status: community/proposed — emerging space, reference architecture more than turnkey product. oryMechanism: @@ -59,7 +59,7 @@ integrations: data. coreFunctionality: |- - Two-layer architecture: Ory is the authorization/policy layer (what an agent or user may access at the resource level); Tetrate Agent Router Enterprise is the network/gateway layer that enforces policy on live traffic. - - Agents are first-class identities authenticated through Ory; Hydra issues OAuth2/OIDC tokens via client_credentials. + - Each agent is a Hydra OAuth2 client using client_credentials, so the token's sub is the client ID and Keto policies refer to that ID; agents acting for a user use a consented flow (e.g. authorization code), where sub is the user and the agent is the token's client_id. - Authorization policies defined in Ory Keto; Tetrate evaluates each agent request (tool call + request parameters) against them at the point an agent invokes an MCP tool. - Parameter-level enforcement: Tetrate can gate not just which tools an agent may use but which request parameters are allowed, based on Keto policies. - Step-up auth: requests exceeding a risk threshold can pause, trigger an authentication/approval flow through Ory, and issue short-lived elevated access. @@ -810,19 +810,18 @@ integrations: maintainedBy: Community contributors status: active description: >- - BambooHR is an HRIS popular with SMB and mid-market companies. This integration enriches Ory identities with - employee data from BambooHR via an Ory Action webhook on login or registration, returning employment status, job - title, department, and hire date so a post-flow Action can gate access or write the fields into identity metadata. + BambooHR is an HRIS popular with SMB and mid-market companies. This integration checks employment status in + BambooHR from an Ory Action webhook on login or registration and blocks the flow for users who aren't active + employees. useCase: >- A company runs internal SaaS for employees and wants login to gate on employment status — off-boarded employees lose access automatically without a separate deprovision step. BambooHR is the HRIS source of truth; the - integration looks up the user's BambooHR record at login and returns the employment flag so Ory can fail the flow - on employed: false. + integration looks up the user's BambooHR record at login and blocks the sign-in when there is no active record. coreFunctionality: |- - - Sync Ory Action webhook (response.parse: true) on after:login and optionally after:registration. - - Looks up the employee via /employees/directory filtered by workEmail (BambooHR has no direct lookup-by-email API). - - Fetches detail fields (status, jobTitle, department, hireDate, terminationDate) and returns { employed, employee_id, job_title, department, hire_date }. - - Returns { employed: false } on no match so Ory can branch on member-vs-non-member traffic instead of erroring. + - Sync Ory Action webhook (response.parse: true) in the login method hook lists (for example selfservice.flows.login.after.password.hooks) and optionally registration. + - Looks up the employee via /employees/directory filtered by workEmail (BambooHR has no direct lookup-by-email API), then fetches the employee's status. + - Active employees get 204 No Content; no match or a non-Active status gets 403 with a Kratos `messages` body, which blocks the flow and shows the reason. + - BambooHR errors return 502, which fails the flow, so every sign-in depends on BambooHR availability. - BambooHR Basic auth: API key as username, literal "x" as password — documented in code so it doesn't look like a typo. oryMechanism: - actions @@ -845,7 +844,7 @@ integrations: / disable) in Workspace to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in Google Workspace Admin Console → Apps → Web and mobile apps → app → Auto-provisioning. Pastes SCIM endpoint URL + access token from Ory's setup-link. + - Google Workspace provisions only to apps in its supported-app catalog, not to custom SCIM endpoints; the Ory Network guide adds the Keeper Web (SAML) catalog app and enters the Ory SCIM client's base URL and authorization header secret as its provisioning endpoint and token. - Attribute mapping: primary email → userName; given/family name → name.givenName / name.familyName; groups → groups. - Workspace pushes lifecycle events on its own schedule (typically within a few minutes of directory change) — no manual "push now". - Deactivation in Workspace becomes a deactivate in Ory (preserves identity record) — not a hard delete. @@ -864,13 +863,13 @@ integrations: status: active description: >- Automatic user provisioning and deprovisioning from JumpCloud into Ory Network / Ory Polis via SCIM 2.0. - Documented directly in /polis/directory-sync/providers/jumpcloud. Pair with enterprise-sso/jumpcloud for the - federated sign-in side. + Documented in /kratos/manage-identities/scim (Ory Network) and /polis/directory-sync/providers/jumpcloud (Ory + Polis self-hosted). Pair with enterprise-sso/jumpcloud for the federated sign-in side. useCase: >- An Ory customer running enterprise SSO from JumpCloud wants user lifecycle events (create / update / disable) in JumpCloud to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in JumpCloud Admin Console → SSO Applications → app → Identity Management tab. Pastes SCIM Base URL + API key from Ory's directory-sync setup-link. + - Configured in JumpCloud Admin Console → SSO Applications → app → Identity Management tab. Pastes the SCIM Base URL + API key: on Ory Network, the base URL and authorization header secret of a SCIM client created on an organization; on self-hosted Ory Polis, the directory-sync endpoint and token. - Attribute mapping: email → userName; given/family name → name.givenName / name.familyName; group membership → groups. - SCIM provisioning is tied to a SAML application — cannot run SCIM without also having the corresponding SAML app configured. - JumpCloud pushes only members of assigned user groups; manage scope via group assignment, not user assignment. @@ -941,13 +940,13 @@ integrations: status: active description: >- Automatic user provisioning and deprovisioning from OneLogin (One Identity) into Ory Network / Ory Polis via SCIM - 2.0. Documented directly in /polis/directory-sync/providers/onelogin. Pair with enterprise-sso/onelogin for the - federated sign-in side. + 2.0. Documented in /kratos/manage-identities/scim (Ory Network) and /polis/directory-sync/providers/onelogin (Ory + Polis self-hosted). Pair with enterprise-sso/onelogin for the federated sign-in side. useCase: >- An Ory customer running enterprise SSO from OneLogin wants user lifecycle events (create / update / disable) to flow into Ory automatically — no manual user management, no stale identities after offboarding. coreFunctionality: |- - - Configured in OneLogin Admin Portal → Applications → app → Configuration tab; paste SCIM Base URL + API Bearer Token from Ory's directory-sync setup-link. + - Configured in OneLogin Admin Portal → Applications → app → Configuration tab; paste the SCIM Base URL + API Bearer Token: on Ory Network, the base URL and authorization header secret of a SCIM client created on an organization; on self-hosted Ory Polis, the directory-sync endpoint and token. - Provisioning tab: enable provisioning and select which events trigger automatic vs manual approval (Create User, Delete User, Update User). - Parameters mappings: OneLogin attributes → SCIM userName / name.givenName / name.familyName / emails[].value / groups[]. - SCIM connector requires a matching SAML/OIDC application — directory sync is tied to an SSO app, not standalone. @@ -975,10 +974,10 @@ integrations: IdP (Okta / Entra ID) being on the critical path. coreFunctionality: |- - No turnkey Workday → SCIM connector ships with Workday; integration requires one of three patterns. - - Pattern A (canonical): Workday Studio / Integration System maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's directory-sync endpoint. Requires Workday Studio licensing and developer hours. + - Pattern A (canonical): Workday Studio / Integration System maps Workday data sources (Worker, Position, etc.) into SCIM 2.0 calls against Ory's SCIM endpoint. Requires Workday Studio licensing and developer hours. - Pattern B: deploy a mid-tier connector (Tools4ever HelloID, Saviynt, or a custom service) that pulls Workday REST/SOAP and pushes to Ory's SCIM endpoint. - Pattern C (most common in practice): provision Workday → Okta/Entra via the IdP's native Workday connector, then Okta/Entra → Ory via the existing SCIM integration. Avoids touching Workday directly. - - Ory side is a standard SCIM 2.0 endpoint with bearer-token auth, accepting Users and Groups; endpoint URL and token come from the directory-sync setup-link. + - Ory side is a standard SCIM 2.0 endpoint accepting Users and Groups; on Ory Network each SCIM client belongs to an organization and has its own base URL, authorization header secret, and data mapping. - Status: community/proposed — documented at ory.com/docs/integrates-with/directory-sync/workday-scim. oryMechanism: - directory-sync @@ -1276,8 +1275,8 @@ integrations: customer's IdP happens to be Auth0 — this integration is the per-customer connection setup. coreFunctionality: |- - Configured per Ory Polis docs at /polis/sso-providers/auth0; Polis acts as the SAML SP, Auth0 as the IdP. - - Auth0 side: Regular Web Application + SAML2 WEB APP addon; configure ACS URL + Audience from Ory's setup-link. - - SP-initiated only — Auth0 also supports IdP-initiated but Polis consumes SP-initiated. + - Auth0 side: Regular Web Application + SAML2 WEB APP addon; configure ACS URL (https://.projects.oryapis.com/saml/api/oauth/saml) + Audience (https://.projects.oryapis.com/self-service/methods/saml/organizations/) on Ory Network. + - Auth0 supports both SP-initiated and IdP-initiated SSO. SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Use Auth0 Actions (not the addon's claims editor) for non-trivial attribute transformations — version-controlled, supported path. - MFA enforcement sits at the Auth0 IdP layer; Ory consumes the resulting authenticated assertion. oryMechanism: @@ -1321,7 +1320,7 @@ integrations: status: active description: >- Configure ForgeRock Access Management (now part of Ping Identity following the 2023 acquisition) as an upstream - SAML 2.0 or OIDC identity provider in Ory Polis. Documented at + SAML 2.0 or OIDC identity provider for an Ory Network organization or self-hosted Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/forgerock-am; configures via the Polis generic SAML or generic OIDC walkthrough. useCase: >- @@ -1330,7 +1329,7 @@ integrations: coreFunctionality: |- - Configured as a generic SAML 2.0 SP (preferred for enterprise SSO) or generic OIDC RP in Ory Polis pointing at the ForgeRock entity / OAuth client. - ForgeRock side: SAML entity under Realms → Applications → Federation, or OAuth 2.0 client under OAuth 2.0 → Clients. - - SP-initiated only — Polis does not consume IdP-initiated SAML assertions; configure the ForgeRock side accordingly. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - OIDC supports openid / profile / email / groups; group claims may need a custom scope mapper depending on AM version. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/forgerock-am. oryMechanism: @@ -1347,17 +1346,18 @@ integrations: maintainedBy: Ory Engineering status: active description: >- - Configure ANY OIDC-compliant Identity Provider into Ory Polis as the OIDC Relying Party. Canonical reference for - OIDC-based enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. Same source - page is mirrored under generic-protocols/generic-oidc. + Configure ANY OIDC-compliant Identity Provider for enterprise SSO. On Ory Network, Ory Kratos is the OIDC Relying + Party for an organization's connection; when self-hosting, Ory Polis is the RP. Canonical reference for OIDC-based + enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. Same source page is + mirrored under generic-protocols/generic-oidc. useCase: >- An Ory Polis customer needs to integrate an OIDC IdP that isn't on the supported-vendor list (open-source IdPs like Keycloak, Authentik, Zitadel, or any custom OIDC implementation), or wants the protocol mechanics documented for debugging or non-default configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-oidc; Polis acts as the OIDC RP, IdP as the OP. - - Discovery via /.well-known/openid-configuration on the issuer URL — Polis fetches and caches automatically. - - Required from the IdP: issuer URL, client id, client secret, plus the Polis ACS URL configured on the IdP side as the redirect URI. + - Discovery via /.well-known/openid-configuration on the issuer URL — Ory fetches and caches automatically. + - Required from the IdP: issuer URL, client id, client secret, plus the organization's OIDC redirect URI (https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/, or /self-service/methods/oidc/callback with pkce: force) configured on the IdP side. - Standard scopes: openid (required), profile, email; add groups if attribute mapping needs them. - Same content mirrored at generic-protocols/generic-oidc — categorization choice; either entry resolves to the same Polis page. oryMechanism: @@ -1373,19 +1373,20 @@ integrations: maintainedBy: Ory Engineering status: active description: >- - Configure ANY SAML 2.0-compliant Identity Provider into Ory Polis as the SAML Service Provider. Canonical - reference for SAML-based enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. - Same source page is mirrored under generic-protocols/generic-saml. + Configure ANY SAML 2.0-compliant Identity Provider for enterprise SSO. Ory Network acts as the SAML Service + Provider for organizations; when self-hosting, Ory Polis is the SAML SP. Canonical reference for SAML-based + enterprise SSO with Ory and the fallback when no provider-specific guide covers an IdP. Same source page is + mirrored under generic-protocols/generic-saml. useCase: >- An Ory Polis customer needs to integrate a SAML IdP that isn't on the supported-vendor list (CyberArk, ForgeRock, - IBM Security Verify, custom in-house SAML), or wants the protocol mechanics documented for debugging or - non-default configuration. + IBM Verify, custom in-house SAML), or wants the protocol mechanics documented for debugging or non-default + configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-saml; Polis acts as the SAML SP, IdP as the IdP. - From the IdP: metadata XML (preferred — Polis can consume URL or upload), or manual entity-id / SSO URL / signing certificate paste. - - To the IdP: Polis SP metadata XML from the Ory organization's setup-link, or manual ACS URL / entity-id / certificate. + - To the IdP on Ory Network: ACS URL https://.projects.oryapis.com/saml/api/oauth/saml and SP entity ID https://.projects.oryapis.com/self-service/methods/saml/organizations/; self-hosted Polis uses its own SP metadata. - Attribute mapping defined IdP-side; Polis maps the released attributes to Ory identity traits. - - SP-initiated only — Polis does not consume IdP-initiated SAML responses. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Same content mirrored at generic-protocols/generic-saml — categorization choice; either entry resolves to the same Polis page. oryMechanism: - standards @@ -1445,7 +1446,7 @@ integrations: - saml2 - oidc - name: ibm-security-verify - displayName: IBM Security Verify + displayName: IBM Verify vendor: IBM category: enterprise-sso path: enterprise-sso/ibm-security-verify @@ -1453,16 +1454,17 @@ integrations: maintainedBy: Community contributors status: active description: >- - Configure IBM Security Verify (IBM's cloud-delivered IAM platform) as an upstream SAML 2.0 or OIDC identity - provider in Ory Polis. Documented at ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify; configures - via the Polis generic SAML or generic OIDC walkthrough. + Configure IBM Verify (formerly IBM Security Verify, IBM's cloud-delivered IAM platform) as an upstream SAML 2.0 or + OIDC identity provider for an Ory Network organization or self-hosted Ory Polis. Documented at + ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify; configures via the Polis generic SAML or generic + OIDC walkthrough. useCase: >- - An enterprise running IBM Security Verify (Verify Cloud SaaS or Verify Access on-prem) as their workforce IdP - wants Ory-protected applications to consume IBM-issued sessions instead of standing up a separate identity store. + An enterprise running IBM Verify (SaaS) or IBM Verify Identity Access (on-premises) as their workforce IdP wants + Ory-protected applications to consume IBM-issued sessions instead of standing up a separate identity store. coreFunctionality: |- - Configured as a generic SAML 2.0 SP (preferred) or generic OIDC RP in Ory Polis pointing at an IBM Verify Custom SAML 2.0 / Custom OIDC application. - - Same federation flows for both Verify Cloud (SaaS) and Verify Access (on-prem) — difference is administration location. - - IBM access policies (risk-based auth, conditional access) stay on the IBM side; Polis consumes the resulting authenticated assertion. + - IBM Verify (SaaS) and IBM Verify Identity Access (on-premises, formerly IBM Security Verify Access) both support SAML 2.0 and OIDC federation — difference is administration location. + - IBM access policies (risk-based auth, conditional access) stay on the IBM side; Ory consumes the resulting authenticated assertion. - Passkey / FIDO2 enforcement configured in IBM Verify's policy engine; Ory consumes the assurance level reported in the assertion. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/ibm-security-verify. oryMechanism: @@ -1504,9 +1506,9 @@ integrations: maintainedBy: Community contributors status: active description: >- - Configure Keycloak — the open-source CNCF-graduated identity and access management server — as an upstream OIDC - (preferred) or SAML 2.0 identity provider in Ory Polis. Common when an enterprise self-hosts their IdP for - control, data residency, or vendor-lock-in avoidance. Documented at + Configure Keycloak — the open-source, CNCF incubating identity and access management server — as an upstream OIDC + (preferred) or SAML 2.0 identity provider for an Ory Network organization or self-hosted Ory Polis. Common when an + enterprise self-hosts their IdP for control, data residency, or vendor-lock-in avoidance. Documented at ory.com/docs/integrates-with/enterprise-sso/keycloak; configures via the Polis generic OIDC or generic SAML walkthrough. useCase: >- @@ -1514,10 +1516,10 @@ integrations: Keycloak-issued sessions instead of standing up a separate identity store. coreFunctionality: |- - Configured as a generic OIDC RP (recommended — Keycloak's OIDC support is first-class) or generic SAML SP in Ory Polis pointing at a Keycloak client. - - Keycloak side: Clients → Create client (OpenID Connect, Confidential type); set Valid redirect URI to Polis ACS URL. - - Issuer URL pattern: https:///realms/; Polis uses /.well-known/openid-configuration automatically. + - Keycloak side: Clients → Create client (OpenID Connect, Confidential type); turn Client authentication on; set Valid redirect URIs to the organization's OIDC redirect URI (https://.projects.oryapis.com/self-service/methods/oidc/organization//callback/, or /self-service/methods/oidc/callback with pkce: force). + - Issuer URL pattern: https:///realms/; Ory uses /.well-known/openid-configuration automatically. - Group claims released via a Group Membership mapper on the client's dedicated client scope — must be added explicitly. - - Self-hosted: pin both Keycloak and Polis library versions; test upgrades against staging since Keycloak's protocol responses occasionally change in major releases. + - Self-hosted: pin the Keycloak version; test upgrades against staging since Keycloak's protocol responses occasionally change in major releases. - Status: community/proposed — documented at ory.com/docs/integrates-with/enterprise-sso/keycloak. oryMechanism: - standards @@ -1595,7 +1597,7 @@ integrations: coreFunctionality: |- - Configured per Ory Polis docs at /polis/sso-providers/okta; Polis acts as the SAML SP / OIDC RP, Okta as the IdP. - Okta side: Applications → Create App Integration → SAML 2.0 (preferred) or OIDC Web Application. - - SAML: Single sign-on URL = Polis ACS URL; Audience URI = Polis Entity ID; both from Ory's setup-link. + - SAML on Ory Network: Single sign-on URL = https://.projects.oryapis.com/saml/api/oauth/saml; Audience URI = https://.projects.oryapis.com/self-service/methods/saml/organizations/. - Attribute statements: email, firstName, lastName. Groups released only if explicitly mapped in attribute statements (SAML) or claims (OIDC). - Sign-on Policies (MFA, network zones, device trust) sit at the Okta layer; resulting authenticated assertion flows through to Ory. - For SCIM provisioning of Okta users into Ory, see directory-sync/okta-scim (separate concern). @@ -1909,8 +1911,9 @@ integrations: status: active description: >- Configure any OpenID Connect-compliant Identity Provider with Ory. OIDC shows up in two product surfaces: Ory - Kratos (consumer / federated sign-in — Kratos is the RP) and Ory Polis (B2B enterprise SSO with per-organization - isolation — Polis is the RP). Same source content mirrored under enterprise-sso/generic-oidc. + Kratos (consumer / federated sign-in — Kratos is the RP) and B2B enterprise SSO with per-organization isolation + (an OIDC connection on an Ory Network organization, or self-hosted Ory Polis). Same source content mirrored under + enterprise-sso/generic-oidc. useCase: >- An Ory customer needs to integrate an OIDC IdP that isn't on a vendor-specific docs list — open-source IdPs (Keycloak, Authentik, Zitadel), in-house implementations, or any custom OIDC server. Same reference works whether @@ -1918,7 +1921,7 @@ integrations: coreFunctionality: |- - Two product surfaces: Kratos social sign-in (docs/kratos/social-signin/generic — for consumer/user-facing flows) and Polis (docs/polis/sso-providers/generic-oidc — for B2B enterprise SSO). - Discovery via /.well-known/openid-configuration on the issuer URL — Ory fetches and caches automatically. - - Required from the IdP: issuer URL, client id, client secret, plus the Ory callback URL configured as redirect URI. + - Required from the IdP: issuer URL, client id, client secret, plus the Ory callback URL configured as redirect URI (/self-service/methods/oidc/callback/ for social sign-in, /self-service/methods/oidc/organization//callback/ for organization connections, or /self-service/methods/oidc/callback with pkce: force). - Standard scopes: openid (required), profile, email; groups when claim mapping needs them. - Same content mirrored at enterprise-sso/generic-oidc — categorization choice; either entry resolves to the same authoritative Ory docs. oryMechanism: @@ -1934,19 +1937,19 @@ integrations: maintainedBy: Ory Engineering status: active description: >- - Configure any SAML 2.0-compliant Identity Provider with Ory. SAML support is provided by Ory Polis (formerly SAML - Jackson) acting as the SAML Service Provider — Kratos does not natively speak SAML. Same source content mirrored - under enterprise-sso/generic-saml. + Configure any SAML 2.0-compliant Identity Provider with Ory. On Ory Network, add the IdP as a SAML connection to + an organization and Ory Network acts as the SAML Service Provider; when self-hosting, Ory Polis (formerly SAML + Jackson) is the SP. Same source content mirrored under enterprise-sso/generic-saml. useCase: >- An Ory Polis customer needs to integrate a SAML IdP that isn't on the supported-vendor list (CyberArk, ForgeRock, - IBM Security Verify, in-house Shibboleth or SimpleSAMLphp, custom SAML), or wants the protocol mechanics - documented for debugging or non-default configuration. + IBM Verify, in-house Shibboleth or SimpleSAMLphp, custom SAML), or wants the protocol mechanics documented for + debugging or non-default configuration. coreFunctionality: |- - Configured per the canonical Ory Polis page at /polis/sso-providers/generic-saml; Polis acts as the SAML SP, IdP as the IdP. - From the IdP: metadata XML (preferred — Polis can consume URL or upload), or manual entity-id / SSO URL / signing certificate paste. - - To the IdP: Polis SP metadata XML from the Ory organization's setup-link, or manual ACS URL / entity-id / certificate. + - To the IdP on Ory Network: ACS URL https://.projects.oryapis.com/saml/api/oauth/saml and SP entity ID https://.projects.oryapis.com/self-service/methods/saml/organizations/; self-hosted Polis uses its own SP metadata. - Attribute mapping defined IdP-side; Polis maps the released attributes to Ory identity traits. - - SP-initiated only — Polis does not consume IdP-initiated SAML responses. + - SAML connections on Ory Network support IdP-initiated login (off by default); see ory.com/docs/kratos/organizations#idp-initiated-login. - Same content mirrored at enterprise-sso/generic-saml — categorization choice; either entry resolves to the same authoritative Ory Polis page. oryMechanism: - standards @@ -1969,6 +1972,7 @@ integrations: verification at signup and is willing to integrate via a licensed eKYC provider. coreFunctionality: |- - Architecture: Ory Kratos webhook → your verification service → licensed ASA/AUA provider → UIDAI CIDR. + - The webhook runs without response.parse in a registration method hook list (e.g. selfservice.flows.registration.after.password.hooks) so it runs after the identity is saved and receives the real identity ID for the Admin API write-back. - Common licensed providers: Signzy, Digio, Karza Technologies, IDfy. Direct UIDAI API access is prohibited. - OTP-based eKYC flow is the typical path; biometric flow is also possible but requires registered devices. - Compliance non-negotiables: NEVER store the full Aadhaar number (mask / last 4 only); explicit `consent: "Y"` per call; data localization (Aadhaar-derived data must stay in India — keep full eKYC in India-hosted infra, only store masked/verified-status in Ory metadata which is global); 5-year audit trail. @@ -2026,7 +2030,7 @@ integrations: coreFunctionality: |- - Configured as a generic OIDC provider in Kratos pointing at the broker's issuer; broker handles per-country eIDAS node integration. - Common brokers: Signicat (pan-EU), Criipto (Nordic + EU), IDnow, yes.com (DE). - - eIDAS Levels of Assurance: Low / Substantial / High — broker reports LoA in the ID token; Jsonnet maps to identity metadata for downstream policy. Substantial roughly maps to Ory aal1; High to aal2. + - eIDAS Levels of Assurance: Low / Substantial / High — broker reports LoA in the ID token's acr claim (e.g. http://eidas.europa.eu/LoA/high). List the acr values that count as AAL2 in the provider's aal2_acr_values; Jsonnet metadata mapping alone doesn't change the session AAL. Request a level with upstream_parameters acr_values. - Per-country eID schemes vary in user experience (card reader for DE Personalausweis, mobile app for FR FranceConnect, etc.) — the broker abstracts this. - Status: community/proposed — documented at ory.com/docs/integrates-with/government-identity/eidas; configures via the generic OIDC path once a broker is chosen. oryMechanism: @@ -2905,7 +2909,7 @@ integrations: - First-party Kratos OIDC provider (`provider: amazon`); registered as an "OpenID Connect provider" in the Ory Console wizard. - Standard scope `profile` (also `postal_code` if needed). Amazon doesn't issue an id_token, so Ory calls the LWA customer-profile API and exposes name / email as claims. - Default Jsonnet maps email to traits.email; email may be empty if the user denied the email permission on the consent screen. - - Configured via Amazon Security Profile (Login with Amazon → Create a New Security Profile); the Allowed Return URLs in Web Settings must include the Ory redirect URI. + - Configured via Amazon Security Profile (Login with Amazon → Create a New Security Profile); the Allowed Return URLs in Web Settings must include https://.projects.oryapis.com/self-service/methods/oidc/callback — the provider rejects the default `pkce: auto`, so set `pkce: force`, which drops the provider ID from the redirect URI. oryMechanism: - standards protocol: @@ -2970,21 +2974,22 @@ integrations: maintainedBy: Community contributors status: active description: >- - Battle.net (Blizzard) as a social sign-in provider in Ory Network. OIDC-compliant and configures cleanly as a - generic OIDC provider; no Battle.net-specific Ory page yet — pattern follows the generic-OIDC docs. + Battle.net (Blizzard) as a social sign-in provider in Ory Network. Battle.net supports OpenID Connect and + configures as a generic OIDC provider; no Battle.net-specific Ory page yet — pattern follows the generic-OIDC + docs. useCase: >- A gaming product targeting Blizzard's player base (World of Warcraft, Overwatch, Hearthstone, Diablo) wants sign-in via the OAuth provider its players already use to access their games and battle.tag identity. coreFunctionality: |- - - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) — Battle.net is OIDC-certified. - - Issuer URL: https://oauth.battle.net (global identity; regional aliases also resolve here). - - Standard scopes: openid (basic identity); add `wow.profile` / `sc2.profile` etc. for game-specific data. - - Default Jsonnet maps battle_tag, sub, email when present. + - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) — Battle.net supports OpenID Connect discovery. + - Issuer URL: https://oauth.battle.net; the China region uses https://oauth.battlenet.com.cn. + - Scope: openid. + - Battle.net doesn't release email addresses. Jsonnet maps `sub` (numeric account ID) and, when present, `raw_claims.battle_tag`; the identity schema must not require an email address. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/battle-net; contributions welcome. oryMechanism: - standards protocol: - - oauth2 + - oidc - name: dingtalk displayName: DingTalk vendor: Alibaba @@ -3019,15 +3024,15 @@ integrations: status: active description: >- Discord as a social sign-in provider in Ory Network. Users sign in with their Discord account; Ory maps Discord's - OAuth2 response (username, email, avatar, optional guild membership) to the identity schema. Common in gaming, - community, and creator-facing products. + OAuth2 response (user ID, username, email and its verification status, avatar, locale) to the identity schema. + Common in gaming, community, and creator-facing products. useCase: >- A gaming or community product wants sign-in via the OAuth provider its users already use to chat with each other — - often paired with guild-membership scopes to gate features on which Discord servers the user belongs to. + Ory doesn't fetch guild membership; read it from the Discord API in application code if needed. coreFunctionality: |- - First-party Kratos OAuth2 provider (`provider: discord`). - - Standard scopes: identify (username + ID), email, and optionally guilds (read the user's Discord servers). - - Default Jsonnet maps email and identifier; can extend to avatar, username, or guild filter. + - Standard scopes: identify (username + ID) and email. Ory doesn't fetch guild (server) membership. + - Default Jsonnet maps email and identifier; can extend to avatar, username, or locale. - Discord OAuth applications are configured under the Discord Developer Portal; no Discord-side approval needed beyond enabling OAuth2. - Refresh tokens supported by default — the access token has limited TTL. oryMechanism: @@ -3128,6 +3133,7 @@ integrations: coreFunctionality: |- - Kratos ships a dedicated first-party `github-app` provider (`provider: github-app`); use `provider: github` for a plain OAuth App. The user-facing OAuth flow is identical to the regular GitHub provider. - GitHub-side registration uses GitHub Apps (settings/apps/new) instead of OAuth Apps, with the Ory redirect URI set as the Callback URL and "Request user authorization (OAuth) during installation" enabled. + - The app needs the Email addresses (read) account permission: the provider reads the user's emails on every sign-in and fails without it. - Fine-grained per-repository permissions, per-installation rate limits (5,000 req/hr per installation), and rich webhook events. - Server-to-server authentication via JWT signed with the App's private key, exchanged at GitHub for an installation access token — handled by the application, not by Ory. - Use the regular `github` provider instead if only user login is needed; choose this variant when the product also needs to act on installations. @@ -3200,15 +3206,16 @@ integrations: A consumer product targeting South Korean users wants sign-in via the platform that nearly every Korean smartphone user has installed for messaging, payments, and identity. coreFunctionality: |- - - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI). + - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) after turning on Kakao Login and OpenID Connect for the app. - Issuer URL: https://kauth.kakao.com. - - Standard scopes: openid, profile_nickname, account_email; Kakao requires explicit scope opt-in for email and other PII fields on the app's "Consent Items" screen. - - Client Secret must be explicitly enabled under the app's Security settings (it's optional for Kakao apps by default). + - Scopes: openid, profile_nickname, profile_image, account_email; each consent item must be configured on the app, and some require additional Kakao permissions such as business verification. + - Ory requires the client secret of the REST API key. + - The ID token carries sub, plus nickname, picture, and email when the user consents; there is no email_verified claim. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/kakao; contributions welcome. oryMechanism: - standards protocol: - - oauth2 + - oidc - name: lark displayName: Lark / Feishu vendor: ByteDance @@ -3226,7 +3233,7 @@ integrations: single-sign-on via the workplace platform that ~10M+ enterprise users sign into daily. coreFunctionality: |- - First-party Kratos OIDC provider (`provider: lark`); CLI-only configuration today. - - Configured via the Feishu Open Platform Developer Console; backs both Lark (overseas) and Feishu (China) tenants under one integration. + - Configured via the Feishu Open Platform Developer Console; the built-in `lark` provider calls the Feishu endpoints at passport.feishu.cn, so create the app on the Feishu Open Platform. - Default Jsonnet maps email when present; richer fields (name, avatar, employee_no) available from Lark's user-info API. - Application-side approval may be required for org-scoped scopes per Lark's tenant administration model. oryMechanism: @@ -3251,7 +3258,7 @@ integrations: coreFunctionality: |- - First-party Kratos OIDC provider (`provider: line`); both Console wizard and CLI configurations supported. - LINE channel must enable `PROFILE`, `OPENID_CONNECT`, and `OC_EMAIL` permissions on the LINE Developer Console. - - Default Jsonnet maps email + name → first_name; add scopes for richer profile or messaging access as needed. + - Default Jsonnet maps email when present (needs the email permission, the `email` scope, and user consent); the display name is available as `name` if your schema has a matching trait. - Optional pairing with LINE Messaging API enables push notifications to authenticated users. oryMechanism: - standards @@ -3319,14 +3326,14 @@ integrations: status: active description: >- Naver Login as a social sign-in provider in Ory Network. Naver is South Korea's largest search portal — a - complementary sign-in option to Kakao for products targeting Korean users. OAuth 2.0 (not OIDC). + complementary sign-in option to Kakao for products targeting Korean users. Ory has no built-in Naver provider. useCase: >- A consumer product targeting South Korean users wants sign-in via Naver in addition to (or instead of) Kakao — Naver dominates search and adjacent services in Korea while Kakao dominates messaging. coreFunctionality: |- - - Configured via the Ory CLI as a generic provider — Naver isn't OIDC (no /.well-known/openid-configuration), so the Console wizard's discovery flow doesn't apply. - - Authorization endpoint: https://nid.naver.com/oauth2.0/authorize; Token endpoint: https://nid.naver.com/oauth2.0/token; Profile API: https://openapi.naver.com/v1/nid/me. - - Default Jsonnet maps response.id (Naver user id), response.email, response.nickname. + - Ory's generic provider works only with OpenID Connect providers: it reads endpoints from discovery and claims from the ID token, and doesn't accept explicit authorization, token, or profile endpoints. + - Naver's classic OAuth 2.0 API (nid.naver.com/oauth2.0, profile at openapi.naver.com/v1/nid/me) returns no ID token, so it needs an OAuth 2.0 to OIDC bridge that you build and operate, configured in Ory as a generic provider. + - Naver also publishes OIDC discovery at https://nid.naver.com/.well-known/openid-configuration; check whether your app can sign in with a generic provider on issuer https://nid.naver.com before building a bridge. - Configured at the Naver Developers Console (developers.naver.com/apps). - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/naver; contributions welcome. oryMechanism: @@ -3366,14 +3373,14 @@ integrations: maintainedBy: Ory Engineering status: active description: >- - Patreon as a social sign-in provider in Ory Network. Patreon's OAuth response includes the user's identity plus - their pledge / membership data, which downstream code can use to gate access on tier or campaign membership. + Patreon as a social sign-in provider in Ory Network. Ory maps the user's Patreon identity (user ID, name, email, + profile image); Ory doesn't fetch pledge or membership data. useCase: >- A creator-economy product or member-only platform wants sign-in via the OAuth provider its patrons already use. Application code can read the Patreon membership API after sign-in to gate content on pledge tier. coreFunctionality: |- - First-party Kratos OIDC provider (`provider: patreon`); CLI-only configuration. - - Supported claims: Subject, Email, Name, GivenName, FamilyName, LastName, Picture. + - Supported claims: sub, email, name, given_name, family_name, last_name, picture. - Default Jsonnet maps email; downstream apps typically call Patreon's membership API with the access_token to gate access on tier. - Configured via Patreon's OAuth client portal; consent screen is Patreon-managed. oryMechanism: @@ -3413,15 +3420,16 @@ integrations: maintainedBy: Ory Engineering status: active description: >- - Slack as a social sign-in provider in Ory Network. The "Sign in with Slack" OIDC flow returns the user's identity - plus their Slack workspace (team) membership, useful for B2B products where workspace membership signals access. + Slack as a social sign-in provider in Ory Network. The provider uses Slack's OAuth 2.0 "Sign in with Slack" flow, + which returns the user's identity plus the ID of their Slack workspace (team), useful for B2B products where + workspace membership signals access. useCase: >- A B2B SaaS, internal tool, or productivity app wants single-sign-on via the workspace its users already share. - Sign in with Slack returns the team_id claim so the app can scope access by Slack workspace. + Sign in with Slack returns the workspace ID as the `team` claim so the app can scope access by Slack workspace. coreFunctionality: |- - - First-party Kratos OIDC provider (`provider: slack`); discovery at https://slack.com/.well-known/openid-configuration. - - Slack-specific scopes (openid, email, profile) under "User Token Scopes" on the Slack app config. - - Default Jsonnet maps email + name; Slack adds team-specific claims (https://slack.com/team_id, https://slack.com/team_name) that map well into identity metadata for workspace-based policy. + - First-party Kratos provider (`provider: slack`) using Slack's OAuth 2.0 identity flow (slack.com/oauth/authorize and users.identity), not OIDC. + - Scopes identity.basic and identity.email under "User Token Scopes" on the Slack app config; the provider needs both client_id and client_secret. + - Claims: sub, name, email, picture, and the workspace ID as `team`, which maps well into identity metadata for workspace-based policy. - App must be Installed to each workspace before users can sign in. - Tokens are workspace-scoped — a user in two Slack workspaces will have two different (sub, team_id) tuples even with the same email. oryMechanism: @@ -3438,7 +3446,7 @@ integrations: status: active description: >- Spotify as a social sign-in provider in Ory Network. Users sign in with their Spotify account; Ory maps Spotify's - OAuth2 response (id, email, display name, country, product tier) to the identity schema. Common in music, + profile (user ID, display name, email address, and profile image) to the identity schema. Common in music, entertainment, and creator-tool products. useCase: >- An entertainment or music-adjacent product wants sign-in via the OAuth provider its users already use to listen. @@ -3446,7 +3454,7 @@ integrations: coreFunctionality: |- - First-party Kratos OAuth2 provider (`provider: spotify`); Spotify is not OIDC, so Ory calls the Spotify API to populate the claims envelope. - Common scopes: user-read-email, user-read-private (basic identity); add music-data scopes for personalization. - - Default Jsonnet maps email + display_name; can extend to country, product (free/premium), or Spotify URI. + - Default Jsonnet maps email + display name; Ory doesn't fetch country or product (free/premium) — call the Spotify API with the access token if you need them. - Spotify apps start in Development mode with a 25-user whitelist; production requires Spotify approval. - Refresh tokens supported by default. oryMechanism: @@ -3471,7 +3479,7 @@ integrations: coreFunctionality: |- - Steam is NOT natively supported by Kratos — it speaks OpenID 2.0 (2007 spec), not OAuth 2.0/OIDC. - Recommended pattern: deploy a small OpenID 2.0 → OIDC proxy that wraps Steam's `https://steamcommunity.com/openid/login` endpoint and exposes a normal OIDC issuer; configure Kratos against the proxy as a generic provider. - - Alternative: implement Steam OpenID 2.0 in your backend and create/lookup identities via the Kratos Admin API, bypassing the social-signin subsystem. + - Ory doesn't provide the proxy; you build and operate it. - Steam does NOT share email; design the identity schema to use the 64-bit Steam ID as the credential identifier. - A Steam Web API key (from steamcommunity.com/dev/apikey) is needed to fetch profile data via GetPlayerSummaries; profile visibility may be restricted. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/steam. @@ -3488,22 +3496,23 @@ integrations: maintainedBy: Community contributors status: active description: >- - Telegram does not implement OAuth 2.0 / OIDC; it provides a Login Widget that posts an HMAC-SHA256-signed payload - to a customer-provided URL. This integration is a small bridge that validates the HMAC against the Telegram bot - token and returns the verified profile so applications can call the Ory Admin API to upsert the matching identity - and issue a session. + Telegram Login supports the OpenID Connect authorization code flow, so it connects to Ory as a generic provider + (issuer https://oauth.telegram.org). This integration also ships a validator for the legacy Login Widget's + HMAC-SHA256-signed payload, for teams that keep the widget behind their own OIDC bridge. useCase: >- - A consumer app wants Telegram as a sign-in option but Telegram has no OIDC, so Ory's native social-sign-in - providers don't apply. The bridge validates the Login Widget HMAC inline, returns suggested identity traits, and - the application uses Ory's Admin API to upsert the identity and start a session. + A consumer app wants Telegram as a sign-in option. New integrations configure Telegram's OIDC flow as a generic + provider; apps that keep the legacy widget verify its payload with the validator inside an OIDC bridge that they + build and operate. coreFunctionality: |- - - POST /telegram/validate verifies X-Webhook-Secret, computes HMAC-SHA256 over the sorted data_check_string with key SHA256(bot_token), and rejects expired auth_date. - - Returns the verified profile plus suggested_identity_traits (telegram_id, name, username) for the application's Admin API upsert. - - Configurable TELEGRAM_AUTH_MAX_AGE_SECONDS for replay window (default 24h per Telegram's recommendation; tighten for stricter session creation). - - Stateless and read-only — does not touch Ory directly; the application owns the upsert and session-bootstrap. + - OIDC: provider generic, issuer_url https://oauth.telegram.org, claims_source id_token (no UserInfo endpoint), scopes openid + profile (optionally phone); with pkce force, register /self-service/methods/oidc/callback in the bot's Allowed URLs. + - Telegram supplies sub, name, preferred_username, picture, and phone_number with the phone scope; no email address. + - Legacy widget: POST /telegram/validate verifies X-Webhook-Secret, computes HMAC-SHA256 over the sorted data_check_string with key SHA256(bot_token), and rejects expired auth_date. + - Configurable TELEGRAM_AUTH_MAX_AGE_SECONDS for the replay window (default 24h). + - The validator is stateless and does not call Ory; the bridge completes OIDC with the Telegram user ID as sub. oryMechanism: - actions protocol: + - oidc - custom - name: tiktok displayName: TikTok @@ -3516,15 +3525,15 @@ integrations: description: >- Add Login with TikTok as a social sign-in provider in Ory Network. Useful for consumer media products, creator tools, and short-form video adjacent apps where TikTok is the audience graph. TikTok Login Kit is OAuth 2.0 (not - OIDC) and is configured as a generic provider with explicit endpoints. + OIDC), so it connects to Ory through an OAuth 2.0 to OIDC bridge that you build and operate. useCase: >- A consumer media or creator product wants Login with TikTok in addition to Google/Facebook so users with strong TikTok presence can sign in with the account they actually use day to day. coreFunctionality: |- - - Configured via the Ory CLI as a generic provider — TikTok isn't OIDC so the Console wizard's discovery flow doesn't apply. - - Authorization endpoint: https://www.tiktok.com/v2/auth/authorize; Token: https://open.tiktokapis.com/v2/oauth/token/; Profile: https://open.tiktokapis.com/v2/user/info/?fields=open_id,union_id,avatar_url,display_name. - - Default Jsonnet maps data.user.open_id, display_name, and email (when the email scope is granted). - - Scopes opt-in: `user.info.basic` is base; `user.info.email` is a separately approved scope and may require TikTok app review. + - Ory has no built-in TikTok provider, and the generic provider requires OIDC discovery and an ID token, so TikTok can't be configured in Ory directly. + - The bridge calls TikTok's authorization (https://www.tiktok.com/v2/auth/authorize/), token (https://open.tiktokapis.com/v2/oauth/token/), and user info (https://open.tiktokapis.com/v2/user/info/) endpoints and returns an ID token to Ory; configure the bridge as a generic provider. + - Scope user.info.basic covers open_id, avatar, and display name; production scopes can require app review. + - TikTok has no email scope; use open_id or union_id as the identifier. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/tiktok; contributions welcome. oryMechanism: - standards @@ -3547,7 +3556,7 @@ integrations: already use. Optional Twitch scopes (channel info, follows, subscriptions) enable feature gating on creator tier. coreFunctionality: |- - Configured as a generic OIDC provider (`provider: generic`, `id: twitch`, issuer https://id.twitch.tv/oauth2) — there is no first-party `twitch` provider in Kratos. CLI-only configuration. - - Twitch publishes /.well-known/openid-configuration but the `openid` claim isn't returned in the access_token; Ory hits Twitch's /me API to populate the claims envelope. + - Twitch supports OIDC: Ory reads the claims from the ID token. email and email_verified appear only when requested via requested_claims.id_token together with the user:read:email scope. - Default Jsonnet returns email gated on email_verified. - Configured via the Twitch Developer Portal; scopes follow the Twitch Helix scope catalog. oryMechanism: @@ -3572,6 +3581,7 @@ integrations: coreFunctionality: |- - First-party Kratos OIDC provider (`provider: uaepass`); both Console wizard and CLI configurations supported. - Issuer URL is environment-specific: https://id.uaepass.ae for production, https://stg-id.uaepass.ae for staging. + - Ory always uses PKCE with UAE PASS unless `pkce: never` is set, so register the redirect URI https://.projects.oryapis.com/self-service/methods/oidc/callback (no provider ID). - Default Jsonnet maps sub → subject, email → email, fullnameEN → name. - Onboarding is gated — applications must be registered with the UAE PASS partner portal and approved before going live. - Supports both web and mobile authentication flows; mobile-app handoff to the UAE PASS app is documented on the partner portal. diff --git a/social-sign-in/amazon-lwa/README.md b/social-sign-in/amazon-lwa/README.md index 09914e1..ebe0710 100644 --- a/social-sign-in/amazon-lwa/README.md +++ b/social-sign-in/amazon-lwa/README.md @@ -12,9 +12,9 @@ Add Amazon (Login with Amazon, LWA) as a social sign-in provider in Ory Network. The full walkthrough (with screenshots and the Ory CLI alternative) lives in the [Ory docs page above](https://www.ory.com/docs/kratos/social-signin/amazon). Short version: 1. In the [Amazon Developer Console](https://developer.amazon.com/), create a **Security Profile** (Login with Amazon → Create a New Security Profile). Note the Client ID and Client Secret. -2. In the Ory Console, enable **OpenID Connect** under Social Sign-In, click **Add new OpenID Connect provider**, choose Amazon, and copy the Redirect URI. +2. In the Ory Console, enable **OpenID Connect** under Social Sign-In, click **Add new OpenID Connect provider**, and choose Amazon. 3. Paste the Client ID and Client Secret into the Ory Console form. -4. In the Amazon Security Profile → Web Settings, paste the Redirect URI into **Allowed Return URLs**. +4. In the Amazon Security Profile → Web Settings, add `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback` to **Allowed Return URLs**. The `amazon` provider rejects `pkce: auto`, the default, so set `pkce: force` as the docs page does. With forced PKCE the redirect URI has no provider ID. 5. Add the `profile` scope and the Jsonnet data-mapping snippet from the docs page (default maps `email`). ## License diff --git a/social-sign-in/amazon-lwa/registry.entry.yaml b/social-sign-in/amazon-lwa/registry.entry.yaml index 952a287..d1c42cd 100644 --- a/social-sign-in/amazon-lwa/registry.entry.yaml +++ b/social-sign-in/amazon-lwa/registry.entry.yaml @@ -17,7 +17,7 @@ coreFunctionality: |- - First-party Kratos OIDC provider (`provider: amazon`); registered as an "OpenID Connect provider" in the Ory Console wizard. - Standard scope `profile` (also `postal_code` if needed). Amazon doesn't issue an id_token, so Ory calls the LWA customer-profile API and exposes name / email as claims. - Default Jsonnet maps email to traits.email; email may be empty if the user denied the email permission on the consent screen. - - Configured via Amazon Security Profile (Login with Amazon → Create a New Security Profile); the Allowed Return URLs in Web Settings must include the Ory redirect URI. + - Configured via Amazon Security Profile (Login with Amazon → Create a New Security Profile); the Allowed Return URLs in Web Settings must include https://.projects.oryapis.com/self-service/methods/oidc/callback — the provider rejects the default `pkce: auto`, so set `pkce: force`, which drops the provider ID from the redirect URI. oryMechanism: - standards protocol: diff --git a/social-sign-in/battle-net/README.md b/social-sign-in/battle-net/README.md index a94dd6a..9e9173d 100644 --- a/social-sign-in/battle-net/README.md +++ b/social-sign-in/battle-net/README.md @@ -9,14 +9,28 @@ Add Battle.net (Blizzard) as a social sign-in provider in Ory Network. Useful fo ## Setup -Battle.net is OIDC-certified, so configure it as a generic OIDC provider in Ory. Full generic-provider walkthrough is at the docs page above. Short version: - -1. Create a new client at the [Battle.net Developer Portal](https://develop.battle.net/access/clients) and add the redirect URI from the Ory Console. -2. Copy the Client ID and Client Secret. Note the regional issuer URL: - - Americas: `https://oauth.battle.net` - - Europe: `https://oauth.battle.net` (regional aliases exist; Battle.net does identity globally on the same issuer) -3. In the Ory Console, **Authentication → Social Sign-In → Add a Generic Provider**. Set Client ID, Client Secret, and Issuer URL. -4. Add the `openid` scope (and `wow.profile`, `sc2.profile` etc. if you want game-specific data) plus a Jsonnet snippet mapping the `sub`, `battle_tag`, `email` claims to your identity schema. +Battle.net supports OpenID Connect, so configure it as a [generic provider](https://www.ory.com/docs/kratos/social-signin/generic) in Ory. Short version: + +1. Create a client at the [Battle.net Developer Portal](https://develop.battle.net/access/clients) and add the Ory redirect URI: `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/battle-net`. The last path segment is the provider ID that you set in Ory. +2. Copy the Client ID and Client Secret. The issuer URL is `https://oauth.battle.net`. For the China region, use `https://oauth.battlenet.com.cn` instead. +3. In the Ory Console, **Authentication → Social Sign-In → Add a Generic Provider**, or use the Ory CLI with `provider: generic`. Set Client ID, Client Secret, Issuer URL, and the `openid` scope. +4. Add a Jsonnet data mapping. Battle.net doesn't release email addresses. The ID token's `sub` claim is the user's numeric Battle.net account ID, and Ory passes every ID token claim to the mapping under `claims.raw_claims`: + + ```jsonnet + local claims = std.extVar('claims'); + local raw = if 'raw_claims' in claims then claims.raw_claims else {}; + + { + identity: { + traits: { + battlenet_account_id: claims.sub, + [if 'battle_tag' in raw then 'battletag' else null]: raw.battle_tag, + }, + }, + } + ``` + + Your identity schema must define the `battlenet_account_id` and `battletag` traits and must not require an email address. 5. Save and trigger a registration flow to test. ## Status diff --git a/social-sign-in/battle-net/registry.entry.yaml b/social-sign-in/battle-net/registry.entry.yaml index 9c03464..554b5c5 100644 --- a/social-sign-in/battle-net/registry.entry.yaml +++ b/social-sign-in/battle-net/registry.entry.yaml @@ -8,19 +8,19 @@ category: social-sign-in type: config maintainedBy: Community contributors description: >- - Battle.net (Blizzard) as a social sign-in provider in Ory Network. OIDC-compliant and configures cleanly as a generic - OIDC provider; no Battle.net-specific Ory page yet — pattern follows the generic-OIDC docs. + Battle.net (Blizzard) as a social sign-in provider in Ory Network. Battle.net supports OpenID Connect and + configures as a generic OIDC provider; no Battle.net-specific Ory page yet — pattern follows the generic-OIDC docs. useCase: >- A gaming product targeting Blizzard's player base (World of Warcraft, Overwatch, Hearthstone, Diablo) wants sign-in via the OAuth provider its players already use to access their games and battle.tag identity. coreFunctionality: |- - - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) — Battle.net is OIDC-certified. - - Issuer URL: https://oauth.battle.net (global identity; regional aliases also resolve here). - - Standard scopes: openid (basic identity); add `wow.profile` / `sc2.profile` etc. for game-specific data. - - Default Jsonnet maps battle_tag, sub, email when present. + - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) — Battle.net supports OpenID Connect discovery. + - Issuer URL: https://oauth.battle.net; the China region uses https://oauth.battlenet.com.cn. + - Scope: openid. + - Battle.net doesn't release email addresses. Jsonnet maps `sub` (numeric account ID) and, when present, `raw_claims.battle_tag`; the identity schema must not require an email address. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/battle-net; contributions welcome. oryMechanism: - standards protocol: - - oauth2 + - oidc status: active diff --git a/social-sign-in/discord/README.md b/social-sign-in/discord/README.md index add25b1..88b03bd 100644 --- a/social-sign-in/discord/README.md +++ b/social-sign-in/discord/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Ory Engineering -Add Discord as a social sign-in provider in Ory Network. Users sign in with their Discord account; Ory maps Discord's OAuth2 response (username, email, avatar, guild/server membership) to the identity schema. Common in gaming, community, and creator-facing products. +Add Discord as a social sign-in provider in Ory Network. Users sign in with their Discord account; Ory maps Discord's OAuth2 response (user ID, username, email address and its verification status, avatar, and locale) to the identity schema. Ory doesn't fetch guild (server) membership. Common in gaming, community, and creator-facing products. **Type:** config (Ory Console / CLI — no webhook code) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/discord](https://www.ory.com/docs/integrates-with/social-sign-in/discord) — full guide: [ory.com/docs/kratos/social-signin/discord](https://www.ory.com/docs/kratos/social-signin/discord) @@ -13,7 +13,7 @@ The full walkthrough (with screenshots and the Ory CLI alternative) lives in the 1. In the [Discord Developer Portal → Applications](https://discord.com/developers/applications), create a new application and open **OAuth2**. Add the redirect URI from the Ory Console. 2. Copy the Client ID and Client Secret into the Ory Console's Discord form. -3. Add the `identify` and `email` scopes (and `guilds` if you want to gate on server membership). Paste the Jsonnet data-mapping snippet from the docs page. +3. Add the `identify` and `email` scopes. Paste the Jsonnet data-mapping snippet from the docs page. 4. Save and trigger a registration flow to test. ## License diff --git a/social-sign-in/discord/registry.entry.yaml b/social-sign-in/discord/registry.entry.yaml index d2e6f1a..456725c 100644 --- a/social-sign-in/discord/registry.entry.yaml +++ b/social-sign-in/discord/registry.entry.yaml @@ -9,15 +9,15 @@ type: config maintainedBy: Ory Engineering description: >- Discord as a social sign-in provider in Ory Network. Users sign in with their Discord account; Ory maps Discord's - OAuth2 response (username, email, avatar, optional guild membership) to the identity schema. Common in gaming, + OAuth2 response (user ID, username, email and its verification status, avatar, locale) to the identity schema. Common in gaming, community, and creator-facing products. useCase: >- A gaming or community product wants sign-in via the OAuth provider its users already use to chat with each other — - often paired with guild-membership scopes to gate features on which Discord servers the user belongs to. + Ory doesn't fetch guild membership; read it from the Discord API in application code if needed. coreFunctionality: |- - First-party Kratos OAuth2 provider (`provider: discord`). - - Standard scopes: identify (username + ID), email, and optionally guilds (read the user's Discord servers). - - Default Jsonnet maps email and identifier; can extend to avatar, username, or guild filter. + - Standard scopes: identify (username + ID) and email. Ory doesn't fetch guild (server) membership. + - Default Jsonnet maps email and identifier; can extend to avatar, username, or locale. - Discord OAuth applications are configured under the Discord Developer Portal; no Discord-side approval needed beyond enabling OAuth2. - Refresh tokens supported by default — the access token has limited TTL. oryMechanism: diff --git a/social-sign-in/github-app/README.md b/social-sign-in/github-app/README.md index c0a3bad..d7abbfd 100644 --- a/social-sign-in/github-app/README.md +++ b/social-sign-in/github-app/README.md @@ -14,10 +14,10 @@ This is a **variant of the standard GitHub provider** — the user-facing OAuth 1. Follow the [Ory docs page](https://www.ory.com/docs/kratos/social-signin/github) for the **base GitHub provider configuration**, but at the GitHub side create a **GitHub App** at [github.com/settings/apps/new](https://github.com/settings/apps/new) instead of an OAuth App: - Set the **Callback URL** to the Ory redirect URI (`https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/github-app`). - Enable **Request user authorization (OAuth) during installation**. - - Configure the **Permissions** the app needs (e.g. repository contents, pull requests). + - Configure the **Permissions** the app needs (e.g. repository contents, pull requests). Under **Account permissions**, grant **Email addresses** read access: the `github-app` provider reads the user's email addresses from GitHub on every sign-in, and the sign-in fails without this permission. - Generate and download a **Private Key** (`.pem`) — used later for server-to-server JWTs, not for Ory. - Note the **App ID**, **Client ID**, **Client Secret**. -2. Configure the provider via Ory CLI with `provider: github-app`. Use `provider: github` for a plain GitHub OAuth App. The `id` is what appears in the redirect URI; the `provider` tells Kratos which OAuth grammar to use. +2. Configure the provider via Ory CLI with `provider: github-app` and no `scope` list — GitHub Apps use permissions instead of OAuth scopes. Use `provider: github` for a plain GitHub OAuth App. The `id` is what appears in the redirect URI; the `provider` tells Kratos which OAuth grammar to use. 3. **Server-to-server** (acting as the app itself) is **out of scope for the Ory provider** — your application code mints a JWT signed with the `.pem` key and exchanges it at `POST /app/installations/{installation_id}/access_tokens` for an installation token. Ory only handles user identification. ## When to choose this over the regular `github` provider diff --git a/social-sign-in/github-app/registry.entry.yaml b/social-sign-in/github-app/registry.entry.yaml index a36e852..22489a1 100644 --- a/social-sign-in/github-app/registry.entry.yaml +++ b/social-sign-in/github-app/registry.entry.yaml @@ -20,6 +20,7 @@ useCase: >- coreFunctionality: |- - Kratos ships a dedicated first-party `github-app` provider (`provider: github-app`); use `provider: github` for a plain OAuth App. The user-facing OAuth flow is identical to the regular GitHub provider. - GitHub-side registration uses GitHub Apps (settings/apps/new) instead of OAuth Apps, with the Ory redirect URI set as the Callback URL and "Request user authorization (OAuth) during installation" enabled. + - The app needs the Email addresses (read) account permission: the provider reads the user's emails on every sign-in and fails without it. - Fine-grained per-repository permissions, per-installation rate limits (5,000 req/hr per installation), and rich webhook events. - Server-to-server authentication via JWT signed with the App's private key, exchanged at GitHub for an installation access token — handled by the application, not by Ory. - Use the regular `github` provider instead if only user login is needed; choose this variant when the product also needs to act on installations. diff --git a/social-sign-in/kakao/README.md b/social-sign-in/kakao/README.md index 1c4d9be..cc6e4a3 100644 --- a/social-sign-in/kakao/README.md +++ b/social-sign-in/kakao/README.md @@ -9,13 +9,26 @@ Add Kakao Login as a social sign-in provider in Ory Network. Kakao is the domina ## Setup -Kakao supports OIDC. Configure as a generic provider in Ory. Short version: - -1. Create a Kakao application at the [Kakao Developers Console](https://developers.kakao.com/) and enable Kakao Login. -2. Add the redirect URI from the Ory Console under **Product Settings → Kakao Login → Redirect URI**. -3. Note the REST API key (Client ID) and the Client Secret (must be enabled separately under **Security**). Issuer URL: `https://kauth.kakao.com`. -4. In the Ory Console, **Authentication → Social Sign-In → Add a Generic Provider**. Set Client ID, Client Secret, and Issuer URL. -5. Add the `openid`, `profile_nickname`, `account_email` scopes plus a Jsonnet snippet mapping the Kakao claims (`sub`, `nickname`, `email`) to your identity schema. +Kakao Login supports OpenID Connect, so configure it as a [generic provider](https://www.ory.com/docs/kratos/social-signin/generic) in Ory. Short version: + +1. Create an app in the [Kakao Developers console](https://developers.kakao.com/console/app). Note the **REST API key**, which is the client ID, and the **client secret** of that key. Ory requires the client secret. +2. Turn on **Kakao Login** and **OpenID Connect** for the app. +3. Register the Ory redirect URI for the REST API key: `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/kakao`. The last path segment is the provider ID that you set in Ory. +4. Configure the consent items you need: `profile_nickname`, `profile_image`, and `account_email`. Kakao can require additional permissions, such as business verification, before you can use some consent items. +5. In the Ory Console, **Authentication → Social Sign-In → Add a Generic Provider**, or use the Ory CLI with `provider: generic`. Set Client ID, Client Secret, Issuer URL `https://kauth.kakao.com`, and the scopes `openid`, `profile_nickname`, `profile_image`, and `account_email`. +6. Add a Jsonnet data mapping. Kakao's ID token contains `sub`, and `nickname`, `picture`, and `email` when the user consents to the matching consent items. It has no `email_verified` claim. This mapping copies the email address to the `email` trait when Kakao returns one: + + ```jsonnet + local claims = std.extVar('claims'); + + { + identity: { + traits: { + [if 'email' in claims then 'email' else null]: claims.email, + }, + }, + } + ``` ## Status diff --git a/social-sign-in/kakao/registry.entry.yaml b/social-sign-in/kakao/registry.entry.yaml index 9993a74..8f4b44c 100644 --- a/social-sign-in/kakao/registry.entry.yaml +++ b/social-sign-in/kakao/registry.entry.yaml @@ -14,13 +14,14 @@ useCase: >- A consumer product targeting South Korean users wants sign-in via the platform that nearly every Korean smartphone user has installed for messaging, payments, and identity. coreFunctionality: |- - - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI). + - Configured via Ory's "Add a Generic Provider" Console wizard (or `provider: generic` in the CLI) after turning on Kakao Login and OpenID Connect for the app. - Issuer URL: https://kauth.kakao.com. - - Standard scopes: openid, profile_nickname, account_email; Kakao requires explicit scope opt-in for email and other PII fields on the app's "Consent Items" screen. - - Client Secret must be explicitly enabled under the app's Security settings (it's optional for Kakao apps by default). + - Scopes: openid, profile_nickname, profile_image, account_email; each consent item must be configured on the app, and some require additional Kakao permissions such as business verification. + - Ory requires the client secret of the REST API key. + - The ID token carries sub, plus nickname, picture, and email when the user consents; there is no email_verified claim. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/kakao; contributions welcome. oryMechanism: - standards protocol: - - oauth2 + - oidc status: active diff --git a/social-sign-in/lark/README.md b/social-sign-in/lark/README.md index 8462c2b..53fe6bd 100644 --- a/social-sign-in/lark/README.md +++ b/social-sign-in/lark/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Ory Engineering -Add Lark (international) / Feishu (mainland China) as a social sign-in provider in Ory Network. Lark is ByteDance's enterprise communication platform — useful for B2B and APAC products that want sign-in via the workplace identity their users already have. +Add Feishu as a social sign-in provider in Ory Network. Feishu is ByteDance's enterprise communication platform for mainland China, and Lark is its international edition — useful for B2B and APAC products that want sign-in via the workplace identity their users already have. The built-in `lark` provider calls the Feishu endpoints at `passport.feishu.cn`, so create your app on the Feishu Open Platform. **Type:** config (Ory CLI configuration) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/lark](https://www.ory.com/docs/integrates-with/social-sign-in/lark) — full guide: [ory.com/docs/kratos/social-signin/lark](https://www.ory.com/docs/kratos/social-signin/lark) diff --git a/social-sign-in/lark/registry.entry.yaml b/social-sign-in/lark/registry.entry.yaml index 143d6fd..772dcf2 100644 --- a/social-sign-in/lark/registry.entry.yaml +++ b/social-sign-in/lark/registry.entry.yaml @@ -16,7 +16,7 @@ useCase: >- single-sign-on via the workplace platform that ~10M+ enterprise users sign into daily. coreFunctionality: |- - First-party Kratos OIDC provider (`provider: lark`); CLI-only configuration today. - - Configured via the Feishu Open Platform Developer Console; backs both Lark (overseas) and Feishu (China) tenants under one integration. + - Configured via the Feishu Open Platform Developer Console; the built-in `lark` provider calls the Feishu endpoints at passport.feishu.cn, so create the app on the Feishu Open Platform. - Default Jsonnet maps email when present; richer fields (name, avatar, employee_no) available from Lark's user-info API. - Application-side approval may be required for org-scoped scopes per Lark's tenant administration model. oryMechanism: diff --git a/social-sign-in/line/README.md b/social-sign-in/line/README.md index f5aa7dc..48ebec7 100644 --- a/social-sign-in/line/README.md +++ b/social-sign-in/line/README.md @@ -14,7 +14,7 @@ The full walkthrough (with screenshots and the Ory CLI alternative) lives in the 1. Create a [LINE Business Account](https://account.line.biz/signup) and a new channel in the [LINE Developer Console](https://developers.line.biz/console/). 2. On the channel, enable the `PROFILE`, `OPENID_CONNECT`, and `OC_EMAIL` permissions and add the redirect URI from the Ory Console as a Callback URL. 3. Copy the Channel ID (Client ID) and Channel Secret (Client Secret) into the Ory Console's LINE form. -4. Add the Jsonnet data-mapping snippet from the docs page (default maps `email` and `name` → `first_name`). +4. Add the Jsonnet data-mapping snippet from the docs page (default maps `email` when present). LINE returns the email address only when your channel has permission to obtain email addresses, Ory requests the `email` scope, and the user consents. The display name is available as `claims.name`; to store it, add a matching trait to your identity schema and map it. 5. Save and trigger a registration flow to test. ## License diff --git a/social-sign-in/line/registry.entry.yaml b/social-sign-in/line/registry.entry.yaml index b9b48d7..d33c889 100644 --- a/social-sign-in/line/registry.entry.yaml +++ b/social-sign-in/line/registry.entry.yaml @@ -17,7 +17,7 @@ useCase: >- coreFunctionality: |- - First-party Kratos OIDC provider (`provider: line`); both Console wizard and CLI configurations supported. - LINE channel must enable `PROFILE`, `OPENID_CONNECT`, and `OC_EMAIL` permissions on the LINE Developer Console. - - Default Jsonnet maps email + name → first_name; add scopes for richer profile or messaging access as needed. + - Default Jsonnet maps email when present (needs the email permission, the `email` scope, and user consent); the display name is available as `name` if your schema has a matching trait. - Optional pairing with LINE Messaging API enables push notifications to authenticated users. oryMechanism: - standards diff --git a/social-sign-in/naver/README.md b/social-sign-in/naver/README.md index e9f1983..603af9e 100644 --- a/social-sign-in/naver/README.md +++ b/social-sign-in/naver/README.md @@ -4,21 +4,22 @@ Add Naver Login as a social sign-in provider in Ory Network. Naver is South Korea's largest search portal — a complementary sign-in option to Kakao for products targeting Korean users. -**Type:** config (Ory Console / CLI — no webhook code) +**Type:** config (architectural pattern, not a turnkey provider) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/naver](https://www.ory.com/docs/integrates-with/social-sign-in/naver) ## Setup -Naver supports OAuth 2.0 (not OIDC) — Ory calls Naver's profile API to populate claims. Configure as a generic OAuth provider. Short version: +Ory has no built-in Naver provider, and the [generic provider](https://www.ory.com/docs/kratos/social-signin/generic) works only with OpenID Connect providers: it reads the endpoints from the provider's discovery document and the user's claims from the ID token. It doesn't accept explicit authorization, token, or profile endpoints. -1. Register a Naver Login application at the [Naver Developers Console](https://developers.naver.com/apps/) and add the redirect URI from the Ory Console. -2. Note the Client ID and Client Secret. Naver's authorization endpoint is `https://nid.naver.com/oauth2.0/authorize`, token endpoint `https://nid.naver.com/oauth2.0/token`, profile endpoint `https://openapi.naver.com/v1/nid/me`. -3. Configure as a generic provider in the Ory Console (or via CLI). Because Naver isn't OIDC, you'll need to use the CLI variant with explicit auth/token URLs rather than the Console wizard. -4. Add a Jsonnet snippet mapping the Naver claims (`response.id`, `response.email`, `response.nickname`) to your identity schema. +Naver Login's classic API (`https://nid.naver.com/oauth2.0/...`) is OAuth 2.0 only. It returns no ID token, and the profile comes from a separate API (`https://openapi.naver.com/v1/nid/me`) as `response.id`, `response.email`, and `response.nickname`. You can't configure this API in Ory directly. -## Status +Naver also publishes an OpenID Connect discovery document at `https://nid.naver.com/.well-known/openid-configuration`, and Ory resolves it for a generic provider with the issuer URL `https://nid.naver.com`. Check whether your Naver app can sign in through these endpoints before you build a bridge. -Community/proposed — no dedicated Ory documentation yet. Naver isn't OIDC (no discovery URL), so the integration requires explicit auth/token endpoints in the provider config. Contributions to ory/docs would be valued. +### OAuth 2.0 to OIDC bridge + +To use the classic API, run a bridge that acts as an OpenID Connect provider toward Ory, the same pattern as the [Steam](../steam/) and [WeChat](../wechat/) entries describe. Ory doesn't provide this bridge: you build and operate it. + +The bridge receives the authorization request from Ory, sends the user to Naver's authorization endpoint, exchanges the code at Naver's token endpoint, calls Naver's profile API, and returns an ID token built from the profile to Ory. Configure the bridge as a generic provider in Ory. ## License diff --git a/social-sign-in/naver/registry.entry.yaml b/social-sign-in/naver/registry.entry.yaml index eb688aa..3cbd0b8 100644 --- a/social-sign-in/naver/registry.entry.yaml +++ b/social-sign-in/naver/registry.entry.yaml @@ -9,14 +9,14 @@ type: config maintainedBy: Community contributors description: >- Naver Login as a social sign-in provider in Ory Network. Naver is South Korea's largest search portal — a - complementary sign-in option to Kakao for products targeting Korean users. OAuth 2.0 (not OIDC). + complementary sign-in option to Kakao for products targeting Korean users. Ory has no built-in Naver provider. useCase: >- A consumer product targeting South Korean users wants sign-in via Naver in addition to (or instead of) Kakao — Naver dominates search and adjacent services in Korea while Kakao dominates messaging. coreFunctionality: |- - - Configured via the Ory CLI as a generic provider — Naver isn't OIDC (no /.well-known/openid-configuration), so the Console wizard's discovery flow doesn't apply. - - Authorization endpoint: https://nid.naver.com/oauth2.0/authorize; Token endpoint: https://nid.naver.com/oauth2.0/token; Profile API: https://openapi.naver.com/v1/nid/me. - - Default Jsonnet maps response.id (Naver user id), response.email, response.nickname. + - Ory's generic provider works only with OpenID Connect providers: it reads endpoints from discovery and claims from the ID token, and doesn't accept explicit authorization, token, or profile endpoints. + - Naver's classic OAuth 2.0 API (nid.naver.com/oauth2.0, profile at openapi.naver.com/v1/nid/me) returns no ID token, so it needs an OAuth 2.0 to OIDC bridge that you build and operate, configured in Ory as a generic provider. + - Naver also publishes OIDC discovery at https://nid.naver.com/.well-known/openid-configuration; check whether your app can sign in with a generic provider on issuer https://nid.naver.com before building a bridge. - Configured at the Naver Developers Console (developers.naver.com/apps). - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/naver; contributions welcome. oryMechanism: diff --git a/social-sign-in/patreon/README.md b/social-sign-in/patreon/README.md index 0292c8c..678422c 100644 --- a/social-sign-in/patreon/README.md +++ b/social-sign-in/patreon/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Ory Engineering -Add Patreon as a social sign-in provider in Ory Network. Useful for creator-economy products and member-only platforms — Patreon's OAuth response includes the user's identity plus their pledge / membership data, which downstream code can use to gate access. +Add Patreon as a social sign-in provider in Ory Network. Useful for creator-economy products and member-only platforms. Ory maps the user's Patreon identity (user ID, name, email address, and profile image) to the identity schema. Ory doesn't fetch pledge or membership data. **Type:** config (Ory CLI configuration) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/patreon](https://www.ory.com/docs/integrates-with/social-sign-in/patreon) — full guide: [ory.com/docs/kratos/social-signin/patreon](https://www.ory.com/docs/kratos/social-signin/patreon) @@ -13,7 +13,7 @@ The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs 1. Create a [Patreon OAuth2 client](https://www.patreon.com/portal/registration/register-clients). 2. Set the redirect URI to `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/patreon`. -3. Create a Jsonnet snippet mapping Patreon claims (`Subject`, `Email`, `Name`, `GivenName`, `FamilyName`, `Picture`) to your identity schema, base64-encode it. +3. Create a Jsonnet snippet mapping Patreon claims (`sub`, `email`, `name`, `given_name`, `family_name`, `picture`) to your identity schema, base64-encode it. 4. Patch your Ory identity-config to add `provider: patreon` with the credentials and the base64 mapper URL. ## License diff --git a/social-sign-in/patreon/registry.entry.yaml b/social-sign-in/patreon/registry.entry.yaml index 69ce6f4..2aa8340 100644 --- a/social-sign-in/patreon/registry.entry.yaml +++ b/social-sign-in/patreon/registry.entry.yaml @@ -8,14 +8,14 @@ category: social-sign-in type: config maintainedBy: Ory Engineering description: >- - Patreon as a social sign-in provider in Ory Network. Patreon's OAuth response includes the user's identity plus - their pledge / membership data, which downstream code can use to gate access on tier or campaign membership. + Patreon as a social sign-in provider in Ory Network. Ory maps the user's Patreon identity (user ID, name, email, + profile image); Ory doesn't fetch pledge or membership data. useCase: >- A creator-economy product or member-only platform wants sign-in via the OAuth provider its patrons already use. Application code can read the Patreon membership API after sign-in to gate content on pledge tier. coreFunctionality: |- - First-party Kratos OIDC provider (`provider: patreon`); CLI-only configuration. - - Supported claims: Subject, Email, Name, GivenName, FamilyName, LastName, Picture. + - Supported claims: sub, email, name, given_name, family_name, last_name, picture. - Default Jsonnet maps email; downstream apps typically call Patreon's membership API with the access_token to gate access on tier. - Configured via Patreon's OAuth client portal; consent screen is Patreon-managed. oryMechanism: diff --git a/social-sign-in/slack/README.md b/social-sign-in/slack/README.md index 637703a..2148972 100644 --- a/social-sign-in/slack/README.md +++ b/social-sign-in/slack/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Ory Engineering -Add Sign in with Slack as a social sign-in provider in Ory Network. Slack's "Sign in with Slack" OIDC flow returns the user's identity plus their Slack workspace (team) membership, which makes it a natural sign-in option for B2B products where workspace membership signals access. +Add Sign in with Slack as a social sign-in provider in Ory Network. The Slack provider uses Slack's OAuth 2.0 "Sign in with Slack" flow, which returns the user's identity plus the ID of their Slack workspace (team), which makes it a natural sign-in option for B2B products where workspace membership signals access. **Type:** config (Ory Console / CLI — no webhook code) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/slack](https://www.ory.com/docs/integrates-with/social-sign-in/slack) — full guide: [ory.com/docs/kratos/social-signin/slack](https://www.ory.com/docs/kratos/social-signin/slack) @@ -12,9 +12,9 @@ Add Sign in with Slack as a social sign-in provider in Ory Network. Slack's "Sig The full walkthrough (with screenshots and the Ory CLI alternative) lives in the [Ory docs page above](https://www.ory.com/docs/kratos/social-signin/slack). Short version: 1. In the [Slack API → Your Apps](https://api.slack.com/apps), create a new app. Under **OAuth & Permissions**, add the redirect URI from the Ory Console. -2. Enable **Sign in with Slack** under **User Token Scopes** and add `openid`, `email`, `profile` scopes. +2. Under **User Token Scopes**, add the `identity.basic` and `identity.email` scopes. Ory requests the scopes in the provider's `scope` list and rejects the sign-in if Slack doesn't grant all of them. 3. Install the app to your workspace. Copy the Client ID and Client Secret into the Ory Console's Slack form. -4. Add the Jsonnet data-mapping snippet from the docs page (default maps `email`, `name`, and Slack-specific `https://slack.com/team_id`). +4. Add the Jsonnet data-mapping snippet from the docs page. The claims include `sub`, `name`, `email`, `picture`, and the workspace ID as `team`. 5. Save and trigger a registration flow to test. ## License diff --git a/social-sign-in/slack/registry.entry.yaml b/social-sign-in/slack/registry.entry.yaml index 1763608..58a0321 100644 --- a/social-sign-in/slack/registry.entry.yaml +++ b/social-sign-in/slack/registry.entry.yaml @@ -8,15 +8,15 @@ category: social-sign-in type: config maintainedBy: Ory Engineering description: >- - Slack as a social sign-in provider in Ory Network. The "Sign in with Slack" OIDC flow returns the user's identity - plus their Slack workspace (team) membership, useful for B2B products where workspace membership signals access. + Slack as a social sign-in provider in Ory Network. The provider uses Slack's OAuth 2.0 "Sign in with Slack" flow, + which returns the user's identity plus the ID of their Slack workspace (team), useful for B2B products where workspace membership signals access. useCase: >- A B2B SaaS, internal tool, or productivity app wants single-sign-on via the workspace its users already share. Sign - in with Slack returns the team_id claim so the app can scope access by Slack workspace. + in with Slack returns the workspace ID as the `team` claim so the app can scope access by Slack workspace. coreFunctionality: |- - - First-party Kratos OIDC provider (`provider: slack`); discovery at https://slack.com/.well-known/openid-configuration. - - Slack-specific scopes (openid, email, profile) under "User Token Scopes" on the Slack app config. - - Default Jsonnet maps email + name; Slack adds team-specific claims (https://slack.com/team_id, https://slack.com/team_name) that map well into identity metadata for workspace-based policy. + - First-party Kratos provider (`provider: slack`) using Slack's OAuth 2.0 identity flow (slack.com/oauth/authorize and users.identity), not OIDC. + - Scopes identity.basic and identity.email under "User Token Scopes" on the Slack app config; the provider needs both client_id and client_secret. + - Claims: sub, name, email, picture, and the workspace ID as `team`, which maps well into identity metadata for workspace-based policy. - App must be Installed to each workspace before users can sign in. - Tokens are workspace-scoped — a user in two Slack workspaces will have two different (sub, team_id) tuples even with the same email. oryMechanism: diff --git a/social-sign-in/spotify/README.md b/social-sign-in/spotify/README.md index 6500c4e..8e36ef9 100644 --- a/social-sign-in/spotify/README.md +++ b/social-sign-in/spotify/README.md @@ -2,7 +2,7 @@ > **Maintained by:** Ory Engineering -Add Log in with Spotify as a social sign-in provider in Ory Network. Users sign in with their Spotify account; Ory maps Spotify's OAuth2 response (id, email, display name, country, product tier) to the identity schema. Common in music apps, entertainment platforms, and creator tools. +Add Log in with Spotify as a social sign-in provider in Ory Network. Users sign in with their Spotify account; Ory maps Spotify's profile (user ID, display name, email address, and profile image) to the identity schema. Ory doesn't fetch the user's country or subscription tier. Common in music apps, entertainment platforms, and creator tools. **Type:** config (Ory Console / CLI — no webhook code) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/spotify](https://www.ory.com/docs/integrates-with/social-sign-in/spotify) — full guide: [ory.com/docs/kratos/social-signin/spotify](https://www.ory.com/docs/kratos/social-signin/spotify) diff --git a/social-sign-in/spotify/registry.entry.yaml b/social-sign-in/spotify/registry.entry.yaml index af405c1..abf54b4 100644 --- a/social-sign-in/spotify/registry.entry.yaml +++ b/social-sign-in/spotify/registry.entry.yaml @@ -9,7 +9,7 @@ type: config maintainedBy: Ory Engineering description: >- Spotify as a social sign-in provider in Ory Network. Users sign in with their Spotify account; Ory maps Spotify's - OAuth2 response (id, email, display name, country, product tier) to the identity schema. Common in music, + profile (user ID, display name, email address, and profile image) to the identity schema. Common in music, entertainment, and creator-tool products. useCase: >- An entertainment or music-adjacent product wants sign-in via the OAuth provider its users already use to listen. @@ -17,7 +17,7 @@ useCase: >- coreFunctionality: |- - First-party Kratos OAuth2 provider (`provider: spotify`); Spotify is not OIDC, so Ory calls the Spotify API to populate the claims envelope. - Common scopes: user-read-email, user-read-private (basic identity); add music-data scopes for personalization. - - Default Jsonnet maps email + display_name; can extend to country, product (free/premium), or Spotify URI. + - Default Jsonnet maps email + display name; Ory doesn't fetch country or product (free/premium) — call the Spotify API with the access token if you need them. - Spotify apps start in Development mode with a 25-user whitelist; production requires Spotify approval. - Refresh tokens supported by default. oryMechanism: diff --git a/social-sign-in/steam/README.md b/social-sign-in/steam/README.md index eb8331c..ada0219 100644 --- a/social-sign-in/steam/README.md +++ b/social-sign-in/steam/README.md @@ -10,11 +10,9 @@ Steam by Valve uses **OpenID 2.0** (the legacy spec from 2007), not OAuth 2.0 or ## How to integrate Steam -Two viable approaches; pick based on whether you want to write a bridge or run one. +### OpenID 2.0 → OIDC proxy -### Option 1 — OpenID 2.0 → OIDC proxy (recommended) - -Deploy a small proxy that exposes an OIDC-compliant interface in front of Steam's OpenID 2.0 endpoint. Configure the proxy as a generic OIDC provider in Kratos. The proxy: +Deploy a small proxy that exposes an OIDC-compliant interface in front of Steam's OpenID 2.0 endpoint. Configure the proxy as a generic OIDC provider in Kratos. Ory doesn't provide this proxy: you build and operate it. The proxy: 1. Receives the standard OIDC authorization request from Kratos. 2. Translates to Steam's OpenID 2.0 flow (`https://steamcommunity.com/openid/login`). @@ -24,10 +22,6 @@ Deploy a small proxy that exposes an OIDC-compliant interface in front of Steam' Then configure Kratos against the proxy's issuer URL with the [generic provider docs](https://www.ory.com/docs/kratos/social-signin/generic). -### Option 2 — Bypass Kratos's social sign-in entirely - -Implement Steam OpenID 2.0 in your application backend, then create/look up the Ory identity via the [Kratos Admin API](https://www.ory.com/docs/kratos/reference/api) and mint an Ory session. This skips the social-signin subsystem but is more complex than Option 1. - ## Steam-specific quirks to expect - **No email is shared.** Design the identity schema to use `steam_id` as the credential identifier. diff --git a/social-sign-in/steam/registry.entry.yaml b/social-sign-in/steam/registry.entry.yaml index 19ac5af..d451b8d 100644 --- a/social-sign-in/steam/registry.entry.yaml +++ b/social-sign-in/steam/registry.entry.yaml @@ -17,7 +17,7 @@ useCase: >- coreFunctionality: |- - Steam is NOT natively supported by Kratos — it speaks OpenID 2.0 (2007 spec), not OAuth 2.0/OIDC. - Recommended pattern: deploy a small OpenID 2.0 → OIDC proxy that wraps Steam's `https://steamcommunity.com/openid/login` endpoint and exposes a normal OIDC issuer; configure Kratos against the proxy as a generic provider. - - Alternative: implement Steam OpenID 2.0 in your backend and create/lookup identities via the Kratos Admin API, bypassing the social-signin subsystem. + - Ory doesn't provide the proxy; you build and operate it. - Steam does NOT share email; design the identity schema to use the 64-bit Steam ID as the credential identifier. - A Steam Web API key (from steamcommunity.com/dev/apikey) is needed to fetch profile data via GetPlayerSummaries; profile visibility may be restricted. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/steam. diff --git a/social-sign-in/telegram/README.md b/social-sign-in/telegram/README.md index e2bc2c9..d00ac23 100644 --- a/social-sign-in/telegram/README.md +++ b/social-sign-in/telegram/README.md @@ -2,28 +2,44 @@ > **Maintained by:** Community contributors -[Telegram](https://core.telegram.org/widgets/login) does not implement OAuth 2.0 or OIDC. It provides a **Login Widget** that posts an HMAC-SHA256-signed payload to a customer-provided URL. This integration is a small bridge that validates the HMAC against the Telegram bot token and returns the verified profile so applications can call the Ory Admin API to upsert the matching identity and issue a session. +[Telegram Login](https://core.telegram.org/bots/telegram-login) supports the OpenID Connect authorization code flow, so you can connect it directly to Ory as a [generic provider](https://www.ory.com/docs/kratos/social-signin/generic) with no code. This directory also contains a validator for the [legacy Login Widget](https://core.telegram.org/widgets/login-legacy), which posts an HMAC-SHA256-signed payload instead of returning an authorization code. -**Type:** webhook (HTTP bridge called by your application) +**Type:** config (generic OIDC provider), plus an optional webhook for the legacy widget **Docs page:** [ory.com/docs/integrates-with/social-sign-in/telegram](https://www.ory.com/docs/integrates-with/social-sign-in/telegram) -## Use case +## Configure Telegram OpenID Connect (recommended) -A consumer app wants Telegram as a sign-in option but Telegram has no OIDC, so Ory's native social-sign-in providers don't apply. The bridge validates the Login Widget HMAC inline, returns the verified profile, and the application uses Ory's Admin API to upsert the identity and start a session. +1. Create or select a bot in [@BotFather](https://t.me/botfather). Open **Login Widget** and obtain the Client ID and Client Secret. +2. Add a generic social sign-in provider to Ory: -## How it works + ```yaml + id: telegram + provider: generic + client_id: "" + client_secret: "" + issuer_url: https://oauth.telegram.org + claims_source: id_token + pkce: force + mapper_url: base64:// + scope: + - openid + - profile + ``` -1. The browser loads the Telegram Login Widget and the user taps "Log in with Telegram". -2. Telegram returns a payload `{ id, first_name, last_name, username, photo_url, auth_date, hash }` to your application's callback. -3. Your application forwards the payload to this bridge: `POST /telegram/validate` with `X-Webhook-Secret`. -4. The bridge verifies `X-Webhook-Secret`, recomputes the HMAC-SHA256 over the sorted data-check-string with key `SHA256(bot_token)`, and rejects expired `auth_date`. -5. The bridge returns the verified profile + `suggested_identity_traits` so your application can call Ory Admin API `PUT /admin/identities` and bootstrap a session. +3. Add Ory's redirect URI to the bot's **Allowed URLs**. With `pkce: force`, it is `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback`. Use your project's custom domain if configured. +4. Map the claims in Jsonnet. Telegram supplies `sub`, plus profile claims such as `name`, `preferred_username`, and `picture`. Keep `claims_source: id_token`: Telegram has no UserInfo endpoint. Telegram doesn't provide an email address, so collect it separately if your schema requires one. To request a phone number with the user's consent, add the `phone` scope and map `phone_number`. + +## Legacy widget validator + +If you keep the legacy widget, its payload `{ id, first_name, last_name, username, photo_url, auth_date, hash }` must be verified before you trust it. The handler in `webhook/` does that: it checks `X-Webhook-Secret`, recomputes the HMAC-SHA256 over the sorted data-check-string with key `SHA256(bot_token)`, compares it in constant time, and rejects stale `auth_date` values. + +To turn a verified payload into an Ory sign-in, run an OIDC bridge whose login page embeds the widget, calls this validator, and completes OIDC with the Telegram user ID as `sub`. For example, an Ory Hydra Authorization [login app](https://www.ory.com/docs/oauth2-oidc/custom-login-consent/flow) can accept the login request with that subject. Configure the bridge in Ory as a generic provider using the bridge's issuer URL. Ory doesn't provide this bridge: you build and operate it. ## Prerequisites - A Telegram bot created via [@BotFather](https://t.me/botfather) — note the bot token. - A registered domain for the Login Widget (set via `/setdomain` in BotFather). -- An Ory Network project + admin API access (your application uses this; the bridge itself does not call Ory). +- An OIDC bridge that calls the validator (the validator itself does not call Ory). - A deployment target for the handler. ## Deploy the webhook handler @@ -41,11 +57,9 @@ The server listens on the port specified in `.env` (default 3000) and exposes: - `GET /health` — readiness check. - `POST /telegram/validate` — bridge endpoint your application calls with the widget payload. -## Configure Ory - -This integration runs **outside** the Ory Action webhook path; Telegram → your app → bridge → your app → Ory Admin API. There is no Ory Action hook to register — your application calls the bridge directly. +## Wire the validator -Embedding the Login Widget, identity-schema fields for Telegram traits, and session-bootstrap patterns: see the [docs page](https://ory.com/docs/integrates-with/social-sign-in/telegram). +The validator runs **outside** the Ory Action webhook path: Telegram widget → your bridge's login page → validator → your bridge → Ory. There is no Ory Action hook to register. ## Troubleshooting diff --git a/social-sign-in/telegram/registry.entry.yaml b/social-sign-in/telegram/registry.entry.yaml index b4f5139..932b480 100644 --- a/social-sign-in/telegram/registry.entry.yaml +++ b/social-sign-in/telegram/registry.entry.yaml @@ -8,21 +8,22 @@ category: social-sign-in type: webhook maintainedBy: Community contributors description: >- - Telegram does not implement OAuth 2.0 / OIDC; it provides a Login Widget that posts an HMAC-SHA256-signed payload to - a customer-provided URL. This integration is a small bridge that validates the HMAC against the Telegram bot token - and returns the verified profile so applications can call the Ory Admin API to upsert the matching identity and - issue a session. + Telegram Login supports the OpenID Connect authorization code flow, so it connects to Ory as a generic provider + (issuer https://oauth.telegram.org). This integration also ships a validator for the legacy Login Widget's + HMAC-SHA256-signed payload, for teams that keep the widget behind their own OIDC bridge. useCase: >- - A consumer app wants Telegram as a sign-in option but Telegram has no OIDC, so Ory's native social-sign-in providers - don't apply. The bridge validates the Login Widget HMAC inline, returns suggested identity traits, and the - application uses Ory's Admin API to upsert the identity and start a session. + A consumer app wants Telegram as a sign-in option. New integrations configure Telegram's OIDC flow as a generic + provider; apps that keep the legacy widget verify its payload with the validator inside an OIDC bridge that they + build and operate. coreFunctionality: |- - - POST /telegram/validate verifies X-Webhook-Secret, computes HMAC-SHA256 over the sorted data_check_string with key SHA256(bot_token), and rejects expired auth_date. - - Returns the verified profile plus suggested_identity_traits (telegram_id, name, username) for the application's Admin API upsert. - - Configurable TELEGRAM_AUTH_MAX_AGE_SECONDS for replay window (default 24h per Telegram's recommendation; tighten for stricter session creation). - - Stateless and read-only — does not touch Ory directly; the application owns the upsert and session-bootstrap. + - OIDC: provider generic, issuer_url https://oauth.telegram.org, claims_source id_token (no UserInfo endpoint), scopes openid + profile (optionally phone); with pkce force, register /self-service/methods/oidc/callback in the bot's Allowed URLs. + - Telegram supplies sub, name, preferred_username, picture, and phone_number with the phone scope; no email address. + - Legacy widget: POST /telegram/validate verifies X-Webhook-Secret, computes HMAC-SHA256 over the sorted data_check_string with key SHA256(bot_token), and rejects expired auth_date. + - Configurable TELEGRAM_AUTH_MAX_AGE_SECONDS for the replay window (default 24h). + - The validator is stateless and does not call Ory; the bridge completes OIDC with the Telegram user ID as sub. oryMechanism: - actions protocol: + - oidc - custom status: active diff --git a/social-sign-in/telegram/webhook/package.json b/social-sign-in/telegram/webhook/package.json index cf9329e..5440e89 100644 --- a/social-sign-in/telegram/webhook/package.json +++ b/social-sign-in/telegram/webhook/package.json @@ -1,7 +1,7 @@ { "name": "ory-telegram-webhook", "version": "1.0.0", - "description": "Reference webhook handler that validates Telegram Login Widget HMACs and returns the verified profile so applications can call the Ory Admin API.", + "description": "Reference handler that validates legacy Telegram Login Widget HMACs for an OIDC bridge.", "main": "server.ts", "scripts": { "start": "tsx server.ts", diff --git a/social-sign-in/telegram/webhook/server.ts b/social-sign-in/telegram/webhook/server.ts index 4dc70f2..ac18dc7 100644 --- a/social-sign-in/telegram/webhook/server.ts +++ b/social-sign-in/telegram/webhook/server.ts @@ -1,15 +1,15 @@ // SPDX-License-Identifier: Apache-2.0 // -// Reference handler that validates Telegram Login Widget payloads. +// Reference handler that validates legacy Telegram Login Widget payloads. // -// Telegram has no OIDC. The Login Widget posts an HMAC-SHA256-signed payload -// to a customer-provided URL. This handler: -// 1. Verifies the X-Webhook-Secret from the calling application. +// The legacy widget posts an HMAC-SHA256-signed payload instead of returning an +// OpenID Connect authorization code. An OIDC bridge calls this handler, which: +// 1. Verifies the X-Webhook-Secret from the calling bridge. // 2. Verifies the Telegram-side HMAC against the bot token. -// 3. Returns the validated profile so the application can call the Ory Admin -// API to upsert an identity matching telegram.id and start a session. +// 3. Returns the validated profile so the bridge can complete OIDC with the +// Telegram user ID as the subject. // -// Spec: https://core.telegram.org/widgets/login#checking-authorization +// Spec: https://core.telegram.org/widgets/login-legacy import "dotenv/config"; import crypto from "node:crypto"; diff --git a/social-sign-in/tiktok/README.md b/social-sign-in/tiktok/README.md index 0f1fcba..3d27c2a 100644 --- a/social-sign-in/tiktok/README.md +++ b/social-sign-in/tiktok/README.md @@ -4,25 +4,35 @@ Add Login with TikTok as a social sign-in provider in Ory Network. Useful for consumer media products, creator tools, and short-form video adjacent apps where TikTok is the audience graph. -**Type:** config (Ory Console / CLI — no webhook code) +**Type:** config (architectural pattern, not a turnkey provider) **Docs page:** [ory.com/docs/integrates-with/social-sign-in/tiktok](https://www.ory.com/docs/integrates-with/social-sign-in/tiktok) ## Setup -TikTok Login Kit uses a custom OAuth 2.0 flow (not OIDC). Configure as a generic provider with explicit endpoints. Short version: +TikTok Login Kit uses a custom OAuth 2.0 flow, not OpenID Connect. It publishes no discovery document, returns no ID token, and expects a `client_key` parameter instead of `client_id`. The profile comes from a separate user info API. -1. Register a TikTok Developer app at the [TikTok for Developers portal](https://developers.tiktok.com/) and add **Login Kit** as a product. -2. Configure the Ory redirect URI as a Redirect URI in the app settings. Note the Client Key (Client ID) and Client Secret. -3. TikTok endpoints: - - Authorization: `https://www.tiktok.com/v2/auth/authorize` - - Token: `https://open.tiktokapis.com/v2/oauth/token/` - - Profile: `https://open.tiktokapis.com/v2/user/info/?fields=open_id,union_id,avatar_url,display_name` -4. Configure as a generic provider via the Ory CLI (TikTok isn't OIDC so the Console wizard's discovery flow doesn't apply). Add Jsonnet mapping `data.user.open_id`, `data.user.display_name`, `data.user.email` if you've requested that scope. -5. TikTok requires explicit scope opt-in for `user.info.basic` and (separately) `user.info.email`. +Ory has no built-in TikTok provider, and the [generic provider](https://www.ory.com/docs/kratos/social-signin/generic) works only with OpenID Connect providers: it reads the endpoints from the provider's discovery document and the user's claims from the ID token. You can't configure TikTok in Ory directly. + +### OAuth 2.0 to OIDC bridge + +Run a bridge that acts as an OpenID Connect provider toward Ory, the same pattern as the [Steam](../steam/) and [WeChat](../wechat/) entries describe. Ory doesn't provide this bridge: you build and operate it. Then configure the bridge as a generic provider in Ory. + +The bridge receives the authorization request from Ory, sends the user to TikTok's authorization endpoint, exchanges the code at TikTok's token endpoint, calls TikTok's user info API, and returns an ID token built from the profile to Ory. Register the bridge's callback URL in the TikTok app, and register Ory's redirect URI with the bridge. + +TikTok endpoints the bridge calls: + +- Authorization: `https://www.tiktok.com/v2/auth/authorize/` +- Token: `https://open.tiktokapis.com/v2/oauth/token/` +- User info: `https://open.tiktokapis.com/v2/user/info/?fields=open_id,union_id,avatar_url,display_name` + +### TikTok-specific details + +- **Scopes.** The `user.info.basic` scope covers the user's open ID, avatar, and display name. Production scopes can require app review. +- **No email.** TikTok's scope list has no scope for the user's email address. Use `open_id` or `union_id` as the identifier in the identity schema. ## Status -Community/proposed — no dedicated Ory documentation yet. TikTok's app review may be required for production scopes. Contributions to ory/docs would be valued. +Community/proposed. Ory doesn't provide the bridge. Contributions to ory/docs would be valued. ## License diff --git a/social-sign-in/tiktok/registry.entry.yaml b/social-sign-in/tiktok/registry.entry.yaml index 717797c..d16f4ef 100644 --- a/social-sign-in/tiktok/registry.entry.yaml +++ b/social-sign-in/tiktok/registry.entry.yaml @@ -10,15 +10,15 @@ maintainedBy: Community contributors description: >- Add Login with TikTok as a social sign-in provider in Ory Network. Useful for consumer media products, creator tools, and short-form video adjacent apps where TikTok is the audience graph. TikTok Login Kit is OAuth 2.0 - (not OIDC) and is configured as a generic provider with explicit endpoints. + (not OIDC), so it connects to Ory through an OAuth 2.0 to OIDC bridge that you build and operate. useCase: >- A consumer media or creator product wants Login with TikTok in addition to Google/Facebook so users with strong TikTok presence can sign in with the account they actually use day to day. coreFunctionality: |- - - Configured via the Ory CLI as a generic provider — TikTok isn't OIDC so the Console wizard's discovery flow doesn't apply. - - Authorization endpoint: https://www.tiktok.com/v2/auth/authorize; Token: https://open.tiktokapis.com/v2/oauth/token/; Profile: https://open.tiktokapis.com/v2/user/info/?fields=open_id,union_id,avatar_url,display_name. - - Default Jsonnet maps data.user.open_id, display_name, and email (when the email scope is granted). - - Scopes opt-in: `user.info.basic` is base; `user.info.email` is a separately approved scope and may require TikTok app review. + - Ory has no built-in TikTok provider, and the generic provider requires OIDC discovery and an ID token, so TikTok can't be configured in Ory directly. + - The bridge calls TikTok's authorization (https://www.tiktok.com/v2/auth/authorize/), token (https://open.tiktokapis.com/v2/oauth/token/), and user info (https://open.tiktokapis.com/v2/user/info/) endpoints and returns an ID token to Ory; configure the bridge as a generic provider. + - Scope user.info.basic covers open_id, avatar, and display name; production scopes can require app review. + - TikTok has no email scope; use open_id or union_id as the identifier. - Status: community/proposed — documented at ory.com/docs/integrates-with/social-sign-in/tiktok; contributions welcome. oryMechanism: - standards diff --git a/social-sign-in/twitch/README.md b/social-sign-in/twitch/README.md index 91d26e9..a1b8679 100644 --- a/social-sign-in/twitch/README.md +++ b/social-sign-in/twitch/README.md @@ -16,7 +16,7 @@ The full walkthrough lives in the [Ory docs page above](https://www.ory.com/docs 3. Create a Jsonnet snippet mapping the desired claims (default returns email when `email_verified` is true), base64-encode it. 4. Patch your Ory identity-config to add the provider with the credentials, mapper URL, and required scopes. Twitch is **not** a first-party Kratos provider — configure it as `provider: generic` with `issuer_url: https://id.twitch.tv/oauth2`, and set `id: twitch` (the `id` is what appears in the callback URL above). -Twitch publishes an OIDC discovery URL but doesn't support the `openid` claim and returns only an `access_token` — Ory calls Twitch's `/me` API and surfaces the user info as claims for Jsonnet mapping. Because email and `email_verified` aren't returned by default, request them explicitly via `requested_claims.id_token` and the `user:read:email` scope. +Twitch supports OpenID Connect, so Ory uses the generic provider with Twitch's [discovery document](https://id.twitch.tv/oauth2/.well-known/openid-configuration) and reads the claims from the ID token. Twitch adds `email` and `email_verified` to the ID token only when the authorization request asks for them in the `claims` parameter and includes the `user:read:email` scope, so set both `requested_claims.id_token` and the `user:read:email` scope. ## License diff --git a/social-sign-in/twitch/registry.entry.yaml b/social-sign-in/twitch/registry.entry.yaml index aaea6ca..9ddc2d5 100644 --- a/social-sign-in/twitch/registry.entry.yaml +++ b/social-sign-in/twitch/registry.entry.yaml @@ -16,7 +16,7 @@ useCase: >- already use. Optional Twitch scopes (channel info, follows, subscriptions) enable feature gating on creator tier. coreFunctionality: |- - Configured as a generic OIDC provider (`provider: generic`, `id: twitch`, issuer https://id.twitch.tv/oauth2) — there is no first-party `twitch` provider in Kratos. CLI-only configuration. - - Twitch publishes /.well-known/openid-configuration but the `openid` claim isn't returned in the access_token; Ory hits Twitch's /me API to populate the claims envelope. + - Twitch supports OIDC: Ory reads the claims from the ID token. email and email_verified appear only when requested via requested_claims.id_token together with the user:read:email scope. - Default Jsonnet returns email gated on email_verified. - Configured via the Twitch Developer Portal; scopes follow the Twitch Helix scope catalog. oryMechanism: diff --git a/social-sign-in/uaepass/README.md b/social-sign-in/uaepass/README.md index d3ba662..6e01569 100644 --- a/social-sign-in/uaepass/README.md +++ b/social-sign-in/uaepass/README.md @@ -12,10 +12,10 @@ Add UAE PASS as a social sign-in provider in Ory Network. UAE PASS is the United The full walkthrough (with screenshots and the Ory CLI alternative) lives in the [Ory docs page above](https://www.ory.com/docs/kratos/social-signin/uaepass). Short version: 1. Register your application on the [UAE PASS partner portal](https://uaepass.ae/) and obtain a Client ID and Client Secret. UAE PASS onboarding is gated and requires partner approval. -2. In the Ory Console, enable **OpenID Connect** under Social Sign-In, click **Add new OpenID Connect provider**, choose UAE PASS, and copy the Redirect URI. +2. In the Ory Console, enable **OpenID Connect** under Social Sign-In, click **Add new OpenID Connect provider**, and choose UAE PASS. 3. Paste Client ID, Client Secret, and the **Issuer URL** (`https://id.uaepass.ae` for production, `https://stg-id.uaepass.ae` for staging) into the Ory Console form. 4. Add the Jsonnet data-mapping snippet from the docs page (default maps `sub` → `subject`, `email` → `email`, `fullnameEN` → `name`). -5. Paste the Ory redirect URI into UAE PASS's allowed redirect URIs in the partner portal. +5. Add `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback` to UAE PASS's allowed redirect URIs in the partner portal. Ory always uses PKCE with UAE PASS unless you set `pkce: never`, and with PKCE the redirect URI has no provider ID. With `pkce: never`, register `https://$PROJECT_SLUG.projects.oryapis.com/self-service/methods/oidc/callback/` instead. ## License diff --git a/social-sign-in/uaepass/registry.entry.yaml b/social-sign-in/uaepass/registry.entry.yaml index 5b1da16..98677e2 100644 --- a/social-sign-in/uaepass/registry.entry.yaml +++ b/social-sign-in/uaepass/registry.entry.yaml @@ -16,6 +16,7 @@ useCase: >- coreFunctionality: |- - First-party Kratos OIDC provider (`provider: uaepass`); both Console wizard and CLI configurations supported. - Issuer URL is environment-specific: https://id.uaepass.ae for production, https://stg-id.uaepass.ae for staging. + - Ory always uses PKCE with UAE PASS unless `pkce: never` is set, so register the redirect URI https://.projects.oryapis.com/self-service/methods/oidc/callback (no provider ID). - Default Jsonnet maps sub → subject, email → email, fullnameEN → name. - Onboarding is gated — applications must be registered with the UAE PASS partner portal and approved before going live. - Supports both web and mobile authentication flows; mobile-app handoff to the UAE PASS app is documented on the partner portal. diff --git a/social-sign-in/wechat/README.md b/social-sign-in/wechat/README.md index 4b06ba5..4e790fe 100644 --- a/social-sign-in/wechat/README.md +++ b/social-sign-in/wechat/README.md @@ -18,11 +18,11 @@ Stand up a small bridge in front of WeChat that: 2. Translates the parameters (`client_id` → `appid`, etc.) and forwards to WeChat's authorization endpoint. 3. Validates WeChat's response, calls `/sns/userinfo`, and returns a normal OIDC `id_token` to Kratos. -Then configure Kratos against the proxy as a [generic OIDC provider](https://www.ory.com/docs/kratos/social-signin/generic). +Then configure Kratos against the proxy as a [generic OIDC provider](https://www.ory.com/docs/kratos/social-signin/generic). Ory doesn't provide this proxy: you build and operate it. ### Without a proxy -You can configure Kratos's `provider: generic` against WeChat's URLs directly, but parameter renaming and the missing `id_token` mean you'll need to override Kratos's userinfo behavior — usually impractical without the proxy above. +Not possible. Kratos's `provider: generic` reads the endpoints from an OpenID Connect discovery document and the user's claims from the ID token, and it doesn't accept explicit authorization or token endpoints. WeChat publishes no discovery document and returns no `id_token`. ## WeChat-specific quirks to expect