Date: Tue, 23 Jul 2024 10:31:26 +0200
Subject: [PATCH 07/12] feat: manage organizations and SSO connections through
the console (#1801)
manage organizations and SSO connections through the API
---
.../sign-in/social-sign-in/redirect-url.mdx | 15 +-
docs/kratos/organizations/organizations.mdx | 154 +++++++++++++++++-
2 files changed, 156 insertions(+), 13 deletions(-)
diff --git a/docs/identities/sign-in/social-sign-in/redirect-url.mdx b/docs/identities/sign-in/social-sign-in/redirect-url.mdx
index 43f18ca0f..4ebb247b6 100644
--- a/docs/identities/sign-in/social-sign-in/redirect-url.mdx
+++ b/docs/identities/sign-in/social-sign-in/redirect-url.mdx
@@ -22,14 +22,18 @@ will initiate the OIDC flow with the new redirect URL.
:::
+```mdx-code-block
+```
To use a custom domain as the redirect URL, go to and add the domain to the **Base
Redirect URI**.
+```mdx-code-block
+```
To change the redirect URL to your custom domain, you need to update the `base_redirect_uri`:
@@ -42,18 +46,19 @@ ory patch identity-config \
--add '/selfservice/methods/oidc/config/base_redirect_uri="https://ory.example.org"'
```
+```mdx-code-block
-````
+```
After changing the base redirect URI you need to update the redirect URL of social sign-in providers you want to use. This is done
in the configuration of the social sign-in provider. To update an existing social sign in provider, follow these steps:
1. Open the Ory Console and navigate to the social sign-in configuration screen.
-1. Choose the provider you want to fix and click on the configuration button.
-1. Copy the **Redirect URI** from the form.
-1. Replace the Ory Network URL `{project-slug}.projects.oryapis.com` with your custom hostname, such as `ory.example.org`.
-1. Update the Redirect URI - also called Authorization callback URL - in the social sign-in provider configuration.
+2. Choose the provider you want to fix and click on the configuration button.
+3. Copy the **Redirect URI** from the form.
+4. Replace the Ory Network URL `{project-slug}.projects.oryapis.com` with your custom hostname, such as `ory.example.org`.
+5. Update the Redirect URI - also called Authorization callback URL - in the social sign-in provider configuration.
:::info
diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx
index c9253ea07..6955d7563 100644
--- a/docs/kratos/organizations/organizations.mdx
+++ b/docs/kratos/organizations/organizations.mdx
@@ -3,6 +3,14 @@ id: organizations
title: Organizations and B2B Single Sign-On
---
+:::info
+
+Organizations are only available in Ory Network and are not supported in self-hosted Ory Kratos. If you have any questions, or if
+you would like more information about transitioning to Ory Network, please don't hesitate to
+[reach out](https://www.ory.sh/contact/).
+
+:::
+
```mdx-code-block
import webm from './_static/organizations-ory-network.webm'
import VideoEmbed from '@site/src/components/VideoEmbed'
@@ -40,6 +48,8 @@ graph LR
## Manage organizations
+### Manage organizations through the Ory Console
+
Organizations can be managed using the Ory Console.
@@ -47,18 +57,146 @@ Organizations can be managed using the Ory Console.
.
+### Manage organizations through the API
+
+Organizations can also be managed using the Ory API. To authenticate your requests, create a
+[workspace API key](/concepts/personal-access-token#authorizing-ory-network-workspace-admin-apis).
+
+All examples below use [curl](https://curl.se/) to make HTTP requests. You can use any HTTP client to make these requests.
+
+#### List organizations
+
+```shell
+curl -X GET --location "https://api.console.ory.sh/projects/{{project_id}}/organizations" \
+ -H "Authorization: Bearer ory_wak_..."
+```
+
+#### Create an organization
+
+```shell
+curl -X POST --location "https://api.console.ory.sh/projects/{{project_id}}/organizations" \
+ -H "Authorization: Bearer ory_wak_..." \
+ -H "Content-Type: application/json" \
+ -d '{
+ "label": "Hello demo",
+ "domains": ["test.example.com"]
+ }'
+```
+
+#### Get an organization
+
+```shell
+curl -X GET --location "https://api.console.ory.sh/projects/{{project_id}}/organizations/{{organization_id}}" \
+ -H "Authorization: Bearer ory_wak_..."
+```
+
+#### Delete an organization
+
+```shell
+curl -X DELETE --location "https://api.console.ory.sh/projects/{{project_id}}/organizations/{{organization_id}}" \
+ -H "Authorization: Bearer ory_wak_..."
+```
+
## Create SSO connections for an organization
After creating an organization, continue by adding one or more SSO OIDC connections.
-Next, go to your registration page. Entering an email that ends with the organization's domain, such as `@my.example.com` from the
-example above, shows a **Sign in with SSO** button instead of the password field. Clicking it will take you to sign in with the
-SSO connection. The SSO connection is not visible for email addresses that are not managed by the organization.
+### Manage SSO connections through the Ory Console
-:::info
+Go to and continue by configuring the selected organization.
-Organizations are only available in Ory Network and are not supported in self-hosted Ory Kratos. If you have any questions, or if
-you would like more information about transitioning to Ory Network, please don't hesitate to
-[reach out](https://www.ory.sh/contact/).
+### Manage SSO connections through the API
-:::
+The SSO connections are part of the project configuration. To authenticate, use the same workspace API key as for managing
+organizations. The examples use [curl](https://curl.se/) to make HTTP requests and [jq](https://jqlang.github.io/jq/) to parse
+JSON response.
+
+#### Create an SSO connections
+
+```shell
+curl -X PATCH --location "https://api.console.ory.sh/projects/{{project_id}}" \
+ -H "Authorization: Bearer ory_wak_..." \
+ -H "Content-Type: application/json" \
+ -d '[
+ {
+ "op": "add",
+ "path": "/services/identity/config/selfservice/methods/oidc/config/providers/-",
+ "value": {
+ "client_id": "...",
+ "client_secret": "...",
+ "id": "ory-GPx1yPH4",
+ "issuer_url": "https://example.org",
+ "label": "My OIDC provider",
+ "mapper_url": "base64://ZnVuY3Rpb24oY3R4KSBjdHg=",
+ "organization_id": "6bb1c7d1-3b3e-4995-9e09-35649dc45a2b",
+ "provider": "generic",
+ "scope": ["openid", "offline_access", "email"]
+ }
+ }
+ ]' \
+ | jq ".project.services.identity.config.selfservice.methods.oidc.config.providers"
+```
+
+Some notes on the fields of the JSON payload:
+
+- `client_id` and `client_secret` are the credentials of the OIDC provider.
+- `id` is a unique identifier for the connection, and part of the redirect URL.
+- `organization_id` is the ID of the organization to which the connection belongs, and part of the redirect URL.
+- `mapper_url` is the URL to a JSONnet file that maps the OIDC provider's claims to Ory's identity schema. You can use the
+ `base64` scheme to embed the JSONnet file directly in the JSON payload.
+
+The redirect URL to be set in the OIDC provider configuration is
+`https://{{project slug}}.projects.oryapis.com/self-service/methods/oidc/organization/{{organization ID}}/callback/{{provider ID}}`.
+
+#### List SSO connections
+
+```shell
+curl -X GET --location "https://api.console.ory.sh/projects/{{project_id}}" \
+ -H "Authorization: Bearer ory_wak_..." \
+ | jq ".services.identity.config.selfservice.methods.oidc.config.providers"
+```
+
+Result:
+
+```json
+[
+ {
+ "client_id": "...",
+ "client_secret": "...",
+ "id": "ory-GPx1yPH4",
+ "issuer_url": "https://example.org",
+ "label": "My OIDC provider",
+ "mapper_url": "https://storage.googleapis.com/bac-gcs-production/94292215dbabe405bebff988b5356663fcf5cba35b10fc6ca2cfea7bc7049e906e01d271a3daeb844203efdfbf2cff356274daa63d5afc2a379bbe93b8b40e63.jsonnet",
+ "organization_id": "6bb1c7d1-3b3e-4995-9e09-35649dc45a2b",
+ "provider": "generic",
+ "scope": ["openid", "offline_access", "email"]
+ }
+]
+```
+
+#### Delete an SSO connection
+
+To delete an organization, you need to specify the index of the connection in the `path` field. The index is the position of the
+SSO connection in the list of connections.
+
+```shell
+curl -X PATCH --location "https://api.console.ory.sh/projects/{{project_id}}" \
+ -H "Authorization: Bearer ory_wak_..." \
+ -H "Content-Type: application/json" \
+ -d '[
+ {
+ "op": "remove",
+ "path": "/services/identity/config/selfservice/methods/oidc/config/providers/0"
+ }
+ ]' \
+ | jq ".project.services.identity.config.selfservice.methods.oidc.config.providers"
+```
+
+Note that the `organization_id` field contains the organization ID to which the connection belongs.
+
+## See it live
+
+After having set up everything, go to your registration page. Entering an email that ends with the organization's domain, such as
+`@my.example.com` from the example above, shows a **Sign in with SSO** button instead of the password field. Clicking it will take
+you to sign in with the SSO connection. The SSO connection is not visible for email addresses that are not managed by the
+organization.
From 72c1cee35d64668f18831f5ccabda38c7cbae790 Mon Sep 17 00:00:00 2001
From: Martin
Date: Tue, 23 Jul 2024 12:51:50 +0200
Subject: [PATCH 08/12] Update 30_apple.mdx (#1800)
* Update 30_apple.mdx
Add a note about the CSRF middleware exemption for the Apple OIDC webbrowser flow.
* chore: text
---------
Co-authored-by: vinckr
---
docs/kratos/social-signin/30_apple.mdx | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/docs/kratos/social-signin/30_apple.mdx b/docs/kratos/social-signin/30_apple.mdx
index e69395dda..41ec38bb3 100644
--- a/docs/kratos/social-signin/30_apple.mdx
+++ b/docs/kratos/social-signin/30_apple.mdx
@@ -93,6 +93,13 @@ Follow these steps to add Apple as a social sign-in provider to your project usi
}
```
+:::note
+
+The provider ID for the web browser flow must be `apple`. This makes sure that the resulting callback URL will be exempt from CSRF
+middleware, as Apple uses a POST form request that does not include the CSRF cookie.
+
+:::
+
```mdx-code-block
```
From 164c08dbcf6fdd4a388e6afde4af39847936af0d Mon Sep 17 00:00:00 2001
From: Vincent
Date: Wed, 24 Jul 2024 15:08:55 +0200
Subject: [PATCH 09/12] fix: add Ory Actions to welcome (#1803)
* fix: add Ory Actions to welcome
* chore: format
---
docs/welcome.mdx | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/docs/welcome.mdx b/docs/welcome.mdx
index a205e684f..3390059e2 100644
--- a/docs/welcome.mdx
+++ b/docs/welcome.mdx
@@ -104,6 +104,12 @@ Contrary to other vendors, Ory allows you to implement your own (login, registra
Use the open-source [Ory Elements](https://github.com/ory/elements) components library for fast integration with frameworks like
ExpressJS, React, or Preact.
+### Ory Actions
+
+[Ory Actions](https://www.ory.sh/docs/kratos/hooks/configure-hooks) provide a flexible way to extend the capabilities of the Ory
+Network by defining custom business logic, automating system behavior in response to events, and integrating with third-party
+services such as CRM platforms, payment gateways, business analytics tools, and integration platforms.
+
## Ory Open Source
Ory is the largest open-source ecosystem in the area of authentication, authorization, access control, and zero-trust networking
From 795e7e1831fed5ed63be7ea12dc06ec4bed8657c Mon Sep 17 00:00:00 2001
From: Vincent
Date: Wed, 24 Jul 2024 15:09:05 +0200
Subject: [PATCH 10/12] chore: indent list (#1802)
---
docs/welcome.mdx | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/welcome.mdx b/docs/welcome.mdx
index 3390059e2..fdb3e81a1 100644
--- a/docs/welcome.mdx
+++ b/docs/welcome.mdx
@@ -42,11 +42,11 @@ Ory differentiates from other vendors in the following key areas:
- From designing Identity Schemas using JSON Schema, to webhooks, to advanced configuration options - Ory is the most customizable
platform out there.
- Ory spans the whole authentication and authorization universe with well-designed products and APIs:
-- Identity Management with session management, flows for login, registration, account recovery & verification, MFA, and many more.
-- Permission and Role Management.
-- Delegation via OAuth2 and OpenID Connect.
-- Zero Trust Networking.
-- Modern API design with partial support for gRPC.
+ - Identity Management with session management & flows for login, registration, recovery, verification, MFA, and more.
+ - Permission and Role Management.
+ - Delegation via OAuth2 and OpenID Connect.
+ - Zero Trust Networking.
+ - Modern API design with partial support for gRPC.
## Ory Network
From 5ca1bcf057486a982247c8c569c4aefd61daeeee Mon Sep 17 00:00:00 2001
From: Henning Perl
Date: Thu, 25 Jul 2024 08:21:30 +0200
Subject: [PATCH 11/12] feat: document webhook header allow list (#1790)
fix: document webhook header allowlist
---
...egrate-with-ory-cloud-through-webhooks.mdx | 33 +++++++++++++++++--
1 file changed, 30 insertions(+), 3 deletions(-)
diff --git a/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx b/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx
index df01d5ebe..6ddfe1e5d 100644
--- a/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx
+++ b/docs/guides/integrate-with-ory-cloud-through-webhooks.mdx
@@ -85,9 +85,36 @@ Webhooks trigger HTTP requests to the webhook URL. You can configure the request
### Customizing request body with Jsonnet
Webhooks bind the `flow`, as well as request headers (`request_headers`), request method (`request_method`), and the request URL
-(`request_url`) of the flow into the Jsonnet template for all methods and execution paths (before and after). For the `after`
-execution path of all flows, it binds the `identity` and the `transient_payload` object into the Jsonnet template as well. These
-objects are available through a `ctx` object.
+(`request_url`) of the flow into the [Jsonnet](https://jsonnet.org) template for all methods and execution paths (before and
+after). For the `after` execution path of all flows, it binds the `identity` and the `transient_payload` object into the Jsonnet
+template as well. These objects are available through a `ctx` object.
+
+:::info
+
+After August 1st, 2024, we will remove all headers from `ctx.request_headers` of the webhook request context that do not match the
+following allow-list:
+
+```
+Accept
+Accept-Encoding
+Accept-Language
+Content-Length
+Content-Type
+Origin
+Priority
+Referer
+Sec-Ch-Ua
+Sec-Ch-Ua-Mobile
+Sec-Ch-Ua-Platform
+Sec-Fetch-Dest
+Sec-Fetch-Mode
+Sec-Fetch-Site
+Sec-Fetch-User
+True-Client-Ip
+User-Agent
+```
+
+:::
To send `{ user_id: {some-id} }` in the request body, create the following the [Jsonnet](https://jsonnet.org) template:
From 0b31c94defbcfb322b2df041ac5558e2b76de0bb Mon Sep 17 00:00:00 2001
From: aeneasr <3372410+aeneasr@users.noreply.github.com>
Date: Fri, 26 Jul 2024 11:56:49 +0000
Subject: [PATCH 12/12] docs: bump to 2a08e7fbc36f998bc7df8a6c15946a651228e369