From f3a3d0c598b56f26a0465ea545a59c7b7af459fd Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Tue, 10 Dec 2024 13:54:05 +0100 Subject: [PATCH 1/5] document native SAML --- docs/kratos/organizations/organizations.mdx | 43 +++++++++++++++------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index a8b994750..bd46eb045 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -247,28 +247,47 @@ organization. ## SAML SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data -between parties. -The SAML integration in Ory Network uses the B2B Organization feature. +between parties. The SAML integration in Ory Network uses the B2B Organization feature. -This guide will walk you through the steps required to set up SAML Single Sign-On (SSO) with Ory Network using BoxyHQ as your SAML -provider. +### SAML via Ory Network -### Prerequisites +This guide will walk you through the steps required to set up SAML Single Sign-On (SSO) with Ory Network. -Before proceeding, ensure you have the following: +#### Prerequisites -- Access to [Ory Network](https://console.ory.sh/) -- An active account with [BoxyHQ](https://app.eu.boxyhq.com/auth/join) -- [Ory CLI](../../guides/cli/installation) +Before proceeding, ensure you are on a plan that supports SAML SSO. SAML is available exclusively on select Enterprise plans. +[Contact us](https://www.ory.sh/contact/) if you need SAML support. + +1. Go to to create an organization. +2. Select "Add a new Enterprise SAML SSO connection" and follow the instructions to configure the SAML connection. Fill out the + following form fields: + + - **Label**: A descriptive name for the SAML connection. This will be displayed to users. + - **Data mapping**: A mapping from the SAML attributes to Ory's identity schema. + - **Raw IDP metadata XML**: The XML metadata file from your SAML Identity Provider (IdP). + +3. Navigate to your login screen to test the SAML connection. + +The SAML application callback URL to set at our SAML Identity Provider is: `https://api.console.ory.sh/saml/api/oauth/saml` + +### SAML via BoxyHQ :::note -If you need help with the integration or have any questions, please open a [support ticket](https://console.ory.sh/support) or -reach out to support@ory.sh. +Before Ory Network had native SAML support, BoxyHQ was the recommended way to set up SAML SSO. The integration is still supported, +although we recommend using the native SAML support in Ory Network for new projects. ::: -### Configuration +#### Prerequisites + +Before proceeding, ensure you have the following: + +- Access to [Ory Network](https://console.ory.sh/) +- An active account with [BoxyHQ](https://app.eu.boxyhq.com/auth/join) +- [Ory CLI](../../guides/cli/installation) + +#### Configuration To set up the integration, you'll need to get your Ory Network session token: From 7a08da944272e2f61d5d143f22358977d242c851 Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Tue, 10 Dec 2024 13:54:05 +0100 Subject: [PATCH 2/5] document native SAML --- docs/kratos/organizations/organizations.mdx | 43 +++++++++++++++------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index a8b994750..bd46eb045 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -247,28 +247,47 @@ organization. ## SAML SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data -between parties. -The SAML integration in Ory Network uses the B2B Organization feature. +between parties. The SAML integration in Ory Network uses the B2B Organization feature. -This guide will walk you through the steps required to set up SAML Single Sign-On (SSO) with Ory Network using BoxyHQ as your SAML -provider. +### SAML via Ory Network -### Prerequisites +This guide will walk you through the steps required to set up SAML Single Sign-On (SSO) with Ory Network. -Before proceeding, ensure you have the following: +#### Prerequisites -- Access to [Ory Network](https://console.ory.sh/) -- An active account with [BoxyHQ](https://app.eu.boxyhq.com/auth/join) -- [Ory CLI](../../guides/cli/installation) +Before proceeding, ensure you are on a plan that supports SAML SSO. SAML is available exclusively on select Enterprise plans. +[Contact us](https://www.ory.sh/contact/) if you need SAML support. + +1. Go to to create an organization. +2. Select "Add a new Enterprise SAML SSO connection" and follow the instructions to configure the SAML connection. Fill out the + following form fields: + + - **Label**: A descriptive name for the SAML connection. This will be displayed to users. + - **Data mapping**: A mapping from the SAML attributes to Ory's identity schema. + - **Raw IDP metadata XML**: The XML metadata file from your SAML Identity Provider (IdP). + +3. Navigate to your login screen to test the SAML connection. + +The SAML application callback URL to set at our SAML Identity Provider is: `https://api.console.ory.sh/saml/api/oauth/saml` + +### SAML via BoxyHQ :::note -If you need help with the integration or have any questions, please open a [support ticket](https://console.ory.sh/support) or -reach out to support@ory.sh. +Before Ory Network had native SAML support, BoxyHQ was the recommended way to set up SAML SSO. The integration is still supported, +although we recommend using the native SAML support in Ory Network for new projects. ::: -### Configuration +#### Prerequisites + +Before proceeding, ensure you have the following: + +- Access to [Ory Network](https://console.ory.sh/) +- An active account with [BoxyHQ](https://app.eu.boxyhq.com/auth/join) +- [Ory CLI](../../guides/cli/installation) + +#### Configuration To set up the integration, you'll need to get your Ory Network session token: From 6662096b213746b648cbdbcc5e356830d5d191ff Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Wed, 11 Dec 2024 11:24:10 +0100 Subject: [PATCH 3/5] Update docs/kratos/organizations/organizations.mdx Co-authored-by: Vincent --- docs/kratos/organizations/organizations.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index bd46eb045..f71e2e5f3 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -274,8 +274,7 @@ The SAML application callback URL to set at our SAML Identity Provider is: `http :::note -Before Ory Network had native SAML support, BoxyHQ was the recommended way to set up SAML SSO. The integration is still supported, -although we recommend using the native SAML support in Ory Network for new projects. +Previously a third party integration provided SAML SSO in Ory Network. The third party BoxyHQ integration is still supported for backwards compatibility, but the native SAML support in Ory Network is recommended for new projects. Please contact us [Ory Support](mailto:support@ory.sh) for any questions. ::: From f4bc99817a1180920044d15351ea69df64505be0 Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Wed, 11 Dec 2024 11:24:52 +0100 Subject: [PATCH 4/5] merge --- docs/kratos/organizations/organizations.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index f71e2e5f3..e5a176955 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -274,7 +274,9 @@ The SAML application callback URL to set at our SAML Identity Provider is: `http :::note -Previously a third party integration provided SAML SSO in Ory Network. The third party BoxyHQ integration is still supported for backwards compatibility, but the native SAML support in Ory Network is recommended for new projects. Please contact us [Ory Support](mailto:support@ory.sh) for any questions. +Previously a third party integration provided SAML SSO in Ory Network. The third party BoxyHQ integration is still supported for +backwards compatibility, but the native SAML support in Ory Network is recommended for new projects. Please contact us +[Ory Support](mailto:support@ory.sh) for any questions. ::: From 97b55c893eaeddd3e3d397bbc8eec05153c8b15f Mon Sep 17 00:00:00 2001 From: Henning Perl Date: Fri, 20 Dec 2024 10:18:20 +0100 Subject: [PATCH 5/5] add API examples --- docs/kratos/organizations/organizations.mdx | 82 +++++++++++++++++++-- 1 file changed, 76 insertions(+), 6 deletions(-) diff --git a/docs/kratos/organizations/organizations.mdx b/docs/kratos/organizations/organizations.mdx index e5a176955..dede38f97 100644 --- a/docs/kratos/organizations/organizations.mdx +++ b/docs/kratos/organizations/organizations.mdx @@ -55,9 +55,10 @@ graph LR ``` -

-To create, update, or delete organizations via the Ory Console, go to{" "}. -

+To create, update, or delete organizations via the Ory Console, go to + +. + ```mdx-code-block @@ -258,16 +259,85 @@ This guide will walk you through the steps required to set up SAML Single Sign-O Before proceeding, ensure you are on a plan that supports SAML SSO. SAML is available exclusively on select Enterprise plans. [Contact us](https://www.ory.sh/contact/) if you need SAML support. +```mdx-code-block + + +``` + 1. Go to to create an organization. 2. Select "Add a new Enterprise SAML SSO connection" and follow the instructions to configure the SAML connection. Fill out the following form fields: - - **Label**: A descriptive name for the SAML connection. This will be displayed to users. - - **Data mapping**: A mapping from the SAML attributes to Ory's identity schema. - - **Raw IDP metadata XML**: The XML metadata file from your SAML Identity Provider (IdP). +- **Label**: A descriptive name for the SAML connection. This will be displayed to users. +- **Data mapping**: A mapping from the SAML attributes to Ory's identity schema. +- **Raw IDP metadata XML**: The XML metadata file from your SAML Identity Provider (IdP). 3. Navigate to your login screen to test the SAML connection. +```mdx-code-block + + +``` + +#### Create an organization + +```shell +curl -X POST --location "https://api.console.ory.sh/projects/$PROJECT_ID/organizations" \ + -H "Authorization: Bearer $WORKSPACE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "label": "SAML organzation", + "domains": ["example.com"] + }' +``` + +#### Enable SAML authentication + +```shell +curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \ + -H "Authorization: Bearer $WORKSPACE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "replace", + "path": "/services/identity/config/selfservice/methods/saml/enabled", + "value": true + } + ]' \ + | jq ".project.services.identity.config.selfservice.methods.saml" +``` + +#### Create a SAML connection + +```shell +curl -X PATCH --location "https://api.console.ory.sh/projects/$PROJECT_ID" \ + -H "Authorization: Bearer $WORKSPACE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '[ + { + "op": "add", + "path": "/services/identity/config/selfservice/methods/saml/config/providers/-", + "value": { + "id": "some-provider-id", + "label": "My SAML provider", + "mapper_url": "base64://...", + "raw_idp_metadata_xml": "base64://...", + "organization_id": "$ORGANIZATION_ID" + } + } + ]' \ + | jq ".project.services.identity.config.selfservice.methods.saml" +``` + +- **label**: A descriptive name for the SAML connection. This will be displayed to users. +- **mapper_url**: A mapping from the SAML attributes to Ory's identity schema. +- **raw_idp_metadata_xml**: The XML metadata file from your SAML Identity Provider (IdP). + +```mdx-code-block + + +``` + The SAML application callback URL to set at our SAML Identity Provider is: `https://api.console.ory.sh/saml/api/oauth/saml` ### SAML via BoxyHQ