feat(saml): implementation of saml for ZITADEL v2 (#3618)

docs/docs/apis/proto/app.md

@@ -33,6 +33,7 @@ title: zitadel/app.proto
 | name |  string | - |  |
 | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) config.oidc_config |  OIDCConfig | - |  |
 | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) config.api_config |  APIConfig | - |  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) config.saml_config |  SAMLConfig | - |  |
 
 
 
@@ -88,6 +89,18 @@ title: zitadel/app.proto
 
 
 
+### SAMLConfig
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_xml |  bytes | - |  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_url |  string | - |  |
+
+
+
+
 
 
 ## Enums

docs/docs/apis/proto/management.md

@@ -1254,6 +1254,19 @@ Returns a new generated secret if needed (Depending on the configuration)
     POST: /projects/{project_id}/apps/oidc
 
 
+### AddSAMLApp
+
+> **rpc** AddSAMLApp([AddSAMLAppRequest](#addsamlapprequest))
+[AddSAMLAppResponse](#addsamlappresponse)
+
+Adds a new saml service provider
+Returns a entityID
+
+
+
+    POST: /projects/{project_id}/apps/saml
+
+
 ### AddAPIApp
 
 > **rpc** AddAPIApp([AddAPIAppRequest](#addapiapprequest))
@@ -1292,6 +1305,18 @@ Changes the configuration of the oidc client
     PUT: /projects/{project_id}/apps/{app_id}/oidc_config
 
 
+### UpdateSAMLAppConfig
+
+> **rpc** UpdateSAMLAppConfig([UpdateSAMLAppConfigRequest](#updatesamlappconfigrequest))
+[UpdateSAMLAppConfigResponse](#updatesamlappconfigresponse)
+
+Changes the configuration of the saml application
+
+
+
+    PUT: /projects/{project_id}/apps/{app_id}/saml_config
+
+
 ### UpdateAPIAppConfig
 
 > **rpc** UpdateAPIAppConfig([UpdateAPIAppConfigRequest](#updateapiappconfigrequest))
@@ -2994,7 +3019,7 @@ This is an empty request
 | Field | Type | Description | Validation |
 | ----- | ---- | ----------- | ----------- |
 | primary_color |  string | - | string.max_len: 50<br />  |
-| hide_login_name_suffix |  bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this [scope in](../openidoauth/scopes) |  |
+| hide_login_name_suffix |  bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.com/concepts#Reserved_Scopes |  |
 | warn_color |  string | - | string.max_len: 50<br />  |
 | background_color |  string | - | string.max_len: 50<br />  |
 | font_color |  string | - | string.max_len: 50<br />  |
@@ -3670,6 +3695,32 @@ This is an empty request
 
 
 
+### AddSAMLAppRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| project_id |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| name |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_xml |  bytes | - | bytes.max_len: 500000<br />  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_url |  string | - | string.max_len: 200<br />  |
+
+
+
+
+### AddSAMLAppResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| app_id |  string | - |  |
+| details |  zitadel.v1.ObjectDetails | - |  |
+
+
+
+
 ### AddSecondFactorToLoginPolicyRequest
 
 
@@ -8309,6 +8360,31 @@ This is an empty request
 
 
 
+### UpdateSAMLAppConfigRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| project_id |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| app_id |  string | - | string.min_len: 1<br /> string.max_len: 200<br />  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_xml |  bytes | - | bytes.max_len: 500000<br />  |
+| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) metadata.metadata_url |  string | - | string.max_len: 200<br />  |
+
+
+
+
+### UpdateSAMLAppConfigResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| details |  zitadel.v1.ObjectDetails | - |  |
+
+
+
+
 ### UpdateUserGrantRequest
 
 

docs/docs/apis/proto/policy.md

@@ -33,7 +33,7 @@ title: zitadel/policy.proto
 | details |  zitadel.v1.ObjectDetails | - |  |
 | primary_color |  string | hex value for primary color |  |
 | is_default |  bool | defines if the organisation's admin changed the policy |  |
-| hide_login_name_suffix |  bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this [scope in](../openidoauth/scopes) |  |
+| hide_login_name_suffix |  bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.com/concepts#Reserved_Scopes |  |
 | warn_color |  string | hex value for secondary color |  |
 | background_color |  string | hex value for background color |  |
 | font_color |  string | hex value for font color |  |

docs/docs/apis/saml/endpoints.md

@@ -0,0 +1,60 @@
+---
+title: Endpoints
+---
+
+## SAML 2.0 Metadata
+
+The SAML Metadata is located within the issuer domain. This would give us {your_domain}/saml/v2/metadata.
+
+This metadata contains all the information defined in the spec.
+
+**Link to
+spec.** [Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite](https://www.oasis-open.org/committees/download.php/35391/sstc-saml-metadata-errata-2.0-wd-04-diff.pdf)
+
+## Certificate Endpoint
+
+{your_domain}/saml/v2/certificate
+
+The certificate endpoint provides the certificate which is used to sign the responses for download, for easier use with
+different service providers which want the certificate separately instead of inside the metadata.
+
+## SSO Endpoint
+
+{your_domain}/saml/v2/SSO
+
+The SSO endpoint is the starting point for all initial user authentications. The user agent (browser) will be redirected
+to this endpoint to authenticate the user.
+
+Supported on this endpoint or currently `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`
+or `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` bindings.
+
+**Link to
+spec.** [Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite](https://www.oasis-open.org/committees/download.php/35387/sstc-saml-bindings-errata-2.0-wd-05-diff.pdf)
+
+### Required request parameters
+
+| Parameter | Description                                                                                                                                                                         |
+|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| RelayState | ID to associate the exchange with the original request.                                                                                                                             |
+| SAMLRequest | The request made to the SAML IDP.  (base64 encoded)                                                                                                                                 |
+| SigAlg | Algorithm used to sign the request, only if binding is 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' as signature has to be provided es separate parameter. (base64 encoded) |
+| Signature | Signature of the request as parameter with 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' binding.  (base64 encoded)                                                                            |
+
+### Successful Response
+
+Depending on the content of the request the response comes back in the requested binding, but the content is the same.
+
+| Parameter | Description                                                                                                                                                          |
+|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| RelayState | ID to associate the exchange with the original request.                                                                                                              |
+| SAMLResponse | The response form the SAML IDP.  (base64 encoded)                                                                                                                    |
+| SigAlg | Algorithm used to sign the response, only if binding is 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' as signature has to be provided es separate parameter.  (base64 encoded)  |
+| Signature | Signature of the response as parameter with 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' binding.  (base64 encoded)                                                            |
+
+### Error Response
+
+Regardless of the error, the used http error code will be '200', which represents a successful request. Whereas the
+response will contain a StatusCode include a message which provides more information if an error occurred.
+
+**Link to
+spec** [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 – Errata Composite](https://www.oasis-open.org/committees/download.php/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf)

docs/docs/concepts/architecture/software.md

@@ -40,6 +40,7 @@ All APIs of ZITADEL are always available as gRCP, gRPC-web and REST service.
 The only exception is the [OpenID Connect & OAuth](/docs/apis/openidoauth/endpoints) and [Asset API](/docs/apis/introduction#assets) due their unique nature.
 
 - [OpenID Connect & OAuth](/docs/apis/openidoauth/endpoints) - allows to request authentication and authorization of ZITADEL
+- [SAML](/docs/apis/saml/endpoints) - allows to request authentication and authorization of ZITADEL through the SAML standard
 - [Authentication API](/docs/apis/introduction#authentication) - allow a user to do operation in its own context
 - [Management API](/docs/apis/introduction#management) - allows an admin or machine to manage the ZITADEL resources on an organization level
 - [Administration API](/docs/apis/introduction#administration) - allows an admin or machine to manage the ZITADEL resources on an instance level

docs/docs/guides/integrate/atlassian-saml.md

@@ -0,0 +1,96 @@
+---
+title: Connect with Atlassian through SAML 2.0
+---
+
+This guide shows how to enable login with ZITADEL on Atlassian.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in Atlassian Access
+
+Prerequisites:
+
+- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing Atlassian Access setup, including verified domain
+
+> We have to switch between ZITADEL and Atlassian. If the headings begin with "ZITADEL" switch to the ZITADEL
+> Console and
+> if the headings start with "Atlassian" please switch to the Atlassian Admin GUI.
+
+## **Atlassian**: Create a new external identity provider
+
+Please follow the instructions on [Atlassian's support page](https://support.atlassian.com/security-and-access-policies/docs/configure-saml-single-sign-on-with-an-identity-provider/) to configure a SAML identity provider for SSO.
+The following instructions give you a quick overview of the most important steps.
+
+Login to Atlassian's security center and select Identity providers.
+Select the option to Set up SAML single sign-on.
+![Security Center](/img/saml/atlassian/atlassian-01.png)
+
+For Identity Provider select "Other provider" and enter a Directory Name.
+![Add identity provider](/img/saml/atlassian/atlassian-02.png)
+
+Follow the wizard.
+Fill in the following information:
+
+- `Identity provider Entity ID`: {your_instance_domain}/saml/v2/metadata
+- `Identity provider SSO URL`: {your_instance_domain}/saml/v2/SSO
+- `Public x509 certificate`: You need to download and paste the value of the certificate from {your_instance_domain}/saml/v2/certificate
+
+![Add SAML details](/img/saml/atlassian/atlassian-03.png)
+
+Create a new .xml file with the following minimal SAML metadata contents:
+
+```xml
+<?xml version="1.0"?>
+<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${ENTITYID}">
+    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
+        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${ACSURL}" index="0"/>
+    </md:SPSSODescriptor>
+</md:EntityDescriptor>
+```
+
+Set or replace the variables with the values from the next screen as follows:
+
+- `${ENTITYID}`: Copy the value from "Service provider entity URL"
+- `${ACSURL}`: Copy the value from "Service provider assertion consumer service URL"
+
+![Copy URLs](/img/saml/atlassian/atlassian-04.png)
+
+## **ZITADEL**: Create the application
+
+In your existing project:
+
+Press the "+"-button to add an application
+![Project](/img/saml/zitadel/project.png)
+
+Fill in a name for the application and chose the SAML type, then click "Continue".
+![New Application](/img/saml/zitadel/application_saml.png)
+
+Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "Continue".
+![Add Metadata to Application](/img/saml/zitadel/application_saml_metadata.png)
+
+Check your application, if everything is correct, press "Create".
+![Create Application](/img/saml/zitadel/application_saml_create.png)
+
+## **Atlassian**: Setup authentication policies
+
+Under Authentication policies, select "Edit" on the directory that you have created.
+Then check the box "Enforce single sign-on" and confirm by clicking "Update".
+![Authentication policies](/img/saml/atlassian/atlassian-05.png)
+
+Add members to your policy.
+![Add Members](/img/saml/atlassian/atlassian-06.png)
+
+## Verify configuration
+
+Now you should be all set to verify your setup:
+
+- Create an user in ZITADEL with the same email address as a member in your authentication policy.
+- In a new browser session go to https://id.atlassian.com
+- Enter the user's email address
+- You should be redirected to ZITADEL's Login screen
+- Enter the email address and password
+- Continue and you should be redirected back to Atlassian

docs/docs/guides/integrate/auth0-oidc.md

@@ -1,5 +1,5 @@
 ---
-title: Connect with Auth0
+title: Connect with Auth0 through OIDC
 ---
 
 This guide shows how to enable login with ZITADEL on Auth0.
@@ -16,7 +16,7 @@ Prerequisites:
 - existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
 - existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants)
 
-> We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and if the headings start with Auth0 please switch to the Auth0 GUI.
+> We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and if the headings start with "Auth0" please switch to the Auth0 GUI.
 
 ## **Auth0**: Create a new connection
 

docs/docs/guides/integrate/auth0-saml.md

@@ -0,0 +1,78 @@
+---
+title: Connect with Auth0 through SAML 2.0
+---
+
+This guide shows how to enable login with ZITADEL on Auth0.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in your Auth0 tenant
+
+Prerequisites:
+
+- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants)
+
+> We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and
+> if the headings start with "Auth0" please switch to the Auth0 GUI.
+
+## **Auth0**: Create a new connection
+
+In Authentication -> Enterprise
+![Navigation Authentication Enterprise](/img/saml/auth0/auth_enterprise.png)
+
+1. Press the "+" button right to "SAML"  
+   ![Enterprise Connections](/img/saml/auth0/enterprise_connections.png)
+2. Fill out the fields as follows in the SAML Connection:
+   ![New SAML Connection](/img/saml/auth0/connection.png)
+
+This includes:
+
+- a unique "Connection name"
+- the "Sign In URL"
+- the "Sign Out URL"
+- used "User ID Attribute"
+- the definition how the request should be signed
+- which binding should be used to call ZITADEL
+
+All the information is filled out as an example, and to connect with any other environment you only have to change the
+used domain, for example "example.com" with "zitadel.cloud".
+Lastly, upload the certificate used to sign the reponses, provided for you under the
+URL {your_instance_domain}/saml/v2/certificate.
+
+Then just press the button "Create" and the connection on Auth0 is configured.
+
+## **ZITADEL**: Create the application
+
+You need to upload the SAML metadata to ZITADEL for it to recognize this newly created connection.
+[Under this link](https://auth0.com/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings) are
+all necessary information to correctly fill out the metadata or download the metadata-file directly under the
+URL https://YOUR_AUTH0_DOMAIN/samlp/metadata?connection=YOUR_CONNECTION_NAME, which in this example would
+be https://example.auth0.com/samlp/metadata?connection=SAML-ZITADEL.
+
+In your existing project:
+
+1. Press the "+"-button to add an application
+   ![Project](/img/saml/zitadel/project.png)
+2. Fill in a name for the application and chose the SAML type, then click "Continue".
+   ![New Application](/img/saml/zitadel/application_saml.png)
+3. Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "
+   Continue".
+   ![Add Metadata to Application](/img/saml/zitadel/application_saml_metadata.png)
+4. Check your application, if everything is correct, press "Create".
+   ![Create Application](/img/saml/zitadel/application_saml_create.png)
+
+Everything on the side of ZITADEL is done if the application is correctly created.
+
+## **Auth0**: Try the connection
+
+To then test the connection you only have to press "Try" on the created connection in the Authentication -> Enterprise
+screen.
+
+![Authentication Enterprise Try](/img/saml/auth0/auth_enterprise_try.png)
+
+To further customize the requests you can also customize the SAML communication as
+described [here](https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)

docs/docs/guides/integrate/aws-saml.md

@@ -0,0 +1,78 @@
+---
+title: Connect with AWS through SAML 2.0
+---
+
+This guide shows how to enable login with ZITADEL on AWS SSO.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in your AWS SSO external IDP
+
+Prerequisites:
+
+- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- prerequisites on AWS side [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/prereqs.html).
+- enabled AWS SSO [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/step1.html?icmpid=docs_sso_console)
+
+> We have to switch between ZITADEL and a AWS. If the headings begin with "ZITADEL" switch to the ZITADEL Console and if
+> the headings start with "AWS" please switch to the AWS GUI.
+
+## **AWS**: Change to external identity provider ZITADEL
+
+As you have activated SSO you still have the possibility to use AWS itself to manage the users, but you can also use a
+Microsoft AD or an external IDP.
+
+Described [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) how you
+can connect to ZITADEL as a SAML2 IDP.
+
+1. Chose the External identity provider:
+   ![Choose identity source](/img/saml/aws/change_idp.png)
+
+2. Download the metadata file, to provide ZITADEL with all the information it needs, and save the AWS SSO Sign-in URL,
+   which you use to login afterwards.
+
+3. Fill out the fields as follows, to provide AWS with all the information it needs:
+   ![Configure external identity provider](/img/saml/aws/configure_idp.png)
+
+   To connect to another environment, change the domains, for example if you would use ZITADEL under the domain "
+   example.com" you would have the URLs "https://accounts.example.com/saml/SSO"
+   and "https://accounts.exmaple.com/saml/metadata".
+
+4. Download the ZITADEL-used certificate to sign the responses, so that AWS can validation the signature.
+
+   You can download the certificate from following
+   URL: {your_instance_domain}/saml/v2/certificate
+
+5. Then upload the ".crt"-file to AWS and click "next".
+
+6. Lastly, accept to confirm the change and ZITADEL is used as the external identity provider for AWS SSO to provide
+   connectivity to your AWS Accounts.
+
+As for how the SSO users are then connected to the AWS accounts, you can find more information in the AWS documentation,
+for example [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/useraccess.html).
+
+## **ZITADEL**: Create the application
+
+The metadata used in this part is from "Change to external identity provider ZITADEL" step 2.
+
+In your existing project:
+
+1. Press the "+"-button to add an application
+   ![Project](/img/saml/zitadel/project.png)
+2. Fill in a name for the application and chose the SAML type, then click "Continue".
+   ![New Application](/img/saml/zitadel/application_saml.png)
+3. Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "
+   Continue".
+   ![Add Metadata to Application](/img/saml/zitadel/application_saml_metadata.png)
+4. Check your application, if everything is correct, press "Create".
+   ![Create Application](/img/saml/zitadel/application_saml_create.png)
+
+Everything on the side of ZITADEL is done if the application is correctly created.
+
+## **AWS**: Test the connection
+
+The result, you can now login to you AWS account through your ZITADEL-login with the AWS SSO Sign-in URL, which you
+should have saved in "Change to external identity provider ZITADEL" step 2.

docs/docs/guides/integrate/azuread-oidc.md

@@ -1,5 +1,5 @@
 ---
-title: Connect with AzureAD
+title: Connect with AzureAD through OIDC
 ---
 
 ## AzureAD Tenant as Identity Provider for ZITADEL

docs/docs/guides/integrate/gitlab-saml.md

@@ -0,0 +1,67 @@
+---
+title: Connect with Gitlab through SAML 2.0 
+---
+
+This guide shows how to enable login with ZITADEL on Gitlab.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in Gitlab SaaS
+
+Prerequisites:
+
+- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing Gitlab SaaS Setup in the premium tier
+
+> We have to switch between ZITADEL and Gitlab. If the headings begin with "ZITADEL" switch to the ZITADEL
+> Console and
+> if the headings start with "Gitlab" please switch to the Gitlab GUI.
+
+## **Gitlab**: Create a new external identity provider
+
+Please follow the instructions on [Gitlab docs](https://docs.gitlab.com/ee/user/group/saml_sso/index.html) to configure a SAML identity provider for SSO.
+The following instructions give you a quick overview of the most important steps.
+
+[Open the group](https://gitlab.com/dashboard/groups) to which you want to add the SSO configuration.
+Select on the menu Settings and then SAML SSO.  
+Copy `GitLab metadata URL` for the next step.
+![Add identity provider](/img/saml/gitlab/gitlab-01.png)
+
+## **ZITADEL**: Create the application
+
+In your existing project:
+
+Press the "+"-button to add an application
+![Project](/img/saml/zitadel/project.png)
+
+Fill in a name for the application and chose the SAML type, then click "Continue".
+![New Application](/img/saml/zitadel/application_saml.png)
+
+Enter the URL from before, then click "Continue".
+![Add Metadata to Application](/img/saml/zitadel/application_saml_metadata.png)
+
+Check your application, if everything is correct, press "Create".
+![Create Application](/img/saml/zitadel/application_saml_create.png)
+
+## **Gitlab**: Configuration
+
+Complete the configuration as follows:
+
+- `Identity provider single sign-on URL`: {your_instance_domain}/saml/v2/SSO
+- `Certificate fingerprint`: You need to download the certificate from {your_instance_domain}/saml/v2/certificate and create a SHA1 fingerprint
+
+Save the changes.
+
+![Filled in values](/img/saml/gitlab/gitlab-02.png)
+
+## **Gitlab**: Verify SAML configuration
+
+Once you saved the changes, click on the button "Verify SAML configuration".
+
+You should be redirected to ZITADEL.
+Login with your user. 
+After that you should be redirected back to GitLab and you can inspect the Response Output.
+![Validate Setup](/img/saml/gitlab/gitlab-03.png)

docs/docs/guides/integrate/pingidentity-saml.md

@@ -0,0 +1,84 @@
+---
+title: Connect with Ping Identity through SAML 2.0
+---
+
+This guide shows how to enable login with ZITADEL on Auth0.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in your Ping Identity tenant
+
+Prerequisites:
+
+- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart)
+- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations)
+- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
+- existing Pingidentity environment [here](https://docs.pingidentity.com/bundle/pingone/page/wqe1564020490538.html)
+
+> We have to switch between ZITADEL and Ping Identity. If the headings begin with "ZITADEL" switch to the ZITADEL
+> Console and
+> if the headings start with "Ping" please switch to the PingIdentity GUI.
+
+## **Ping**: Create a new external identity provider
+
+To add an
+additional [external identity provider](https://docs.pingidentity.com/bundle/pingone/page/jvz1567784210191.html), you
+can follow the instructions [here](https://docs.pingidentity.com/bundle/pingone/page/ovy1567784211297.html)
+
+1. As described you have to create a new provider, with a unique identifier:
+   ![Create IDP Profile](/img/saml/pingidentity/create_idp_profile.png)
+
+We recommend activating signing the auth request whenever possible:
+![Configure PingOne Connection](/img/saml/pingidentity/conf_connection.png)
+
+2. Manually enter the necessary information:
+
+- SSO Endpoint, for example https://accounts.example.com/saml/SSO
+- IDP EntityID, for example https://accounts.example.com/saml/metadata
+- Binding, which is a decision which you can take yourself, we recommend HTTP POST as it has fewer restrictions
+- Import certificate, provided from the certificate endpoint
+  ![Configure IDP Connection](/img/saml/pingidentity/conf_idp_connection.png)
+
+Everything you need to know about the attribute mapping you can find
+in [Ping Identity's documentation](https://docs.pingidentity.com/bundle/pingone/page/pwv1567784207915.html)
+
+3. With this you have defined to connection to ZITADEL as an external IDP, next is the policy to use ZITADEL as an IDP
+   to
+   connect to an application. The "How to" for that can be
+   found [here](https://docs.pingidentity.com/bundle/pingone/page/zqd1616600404402.html).
+
+## **ZITADEL**: Create the application
+
+To add the connection to ZITADEL you have to build the metadata, which should minimalistic look like this, the necessary
+information can be found on the External IDPs page under "P1Connection" and "IDP Configuration" :
+
+```xml
+ENTITYID="PINGONE (SP) ENTITY ID"
+        ACSURL="ACS ENDPOINT"
+        <?xml version="1.0"?>
+<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${ENTITYID}">
+    <md:SPSSODescriptor
+            protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
+        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${ACSURL}"
+                                     index="0"/>
+    </md:SPSSODescriptor>
+</md:EntityDescriptor>
+```
+
+![Identity Providers P1 Connection](/img/saml/pingidentity/idp_p1_connection.png)
+![Identity Providers IDP Configuration](/img/saml/pingidentity/idp_idp_configuration.png)
+
+In your existing project:
+
+1. Press the "+"-button to add an application
+   ![Project](/img/saml/zitadel/project.png)
+2. Fill in a name for the application and chose the SAML type, then click "Continue".
+   ![New Application](/img/saml/zitadel/application_saml.png)
+3. Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "
+   Continue".
+   ![Add Metadata to Application](/img/saml/zitadel/application_saml_metadata.png)
+4. Check your application, if everything is correct, press "Create".
+   ![Create Application](/img/saml/zitadel/application_saml_create.png)
+
+Everything on the side of ZITADEL is done if the application is correctly created.

docs/sidebars.js

@@ -115,17 +115,43 @@ module.exports = {
       label: "Integrate",
       collapsed: false,
       items: [
-        "guides/integrate/identity-brokering",
-        "guides/integrate/access-zitadel-apis",
-        "guides/integrate/access-zitadel-system-api",
-        "guides/integrate/authenticated-mongodb-charts",
-        "guides/integrate/auth0",
-        "guides/integrate/azuread",
-        "guides/integrate/gitlab-self-hosted",
         "guides/integrate/login-users",
-        "guides/integrate/serviceusers",
-        "guides/integrate/oauth-recommended-flows",
-        "guides/integrate/export-and-import"
+        "guides/integrate/identity-brokering",
+        {
+          type: "category",
+          label: "Access ZITADEL APIs",
+          collapsed: false,
+          items: [
+            "guides/integrate/serviceusers",
+            "guides/integrate/access-zitadel-apis",
+            "guides/integrate/access-zitadel-system-api",
+            "guides/integrate/export-and-import",
+          ],
+        },
+        {
+          type: "category",
+          label: "OpenID Connect 1.0 Clients",
+          collapsed: false,
+          items: [
+            "guides/integrate/oauth-recommended-flows",
+            "guides/integrate/auth0-oidc",
+            "guides/integrate/azuread-oidc",
+            "guides/integrate/authenticated-mongodb-charts",
+            "guides/integrate/gitlab-self-hosted",
+          ],
+        },
+        {
+          type: "category",
+          label: "SAML 2.0 Clients",
+          collapsed: false,
+          items: [
+            "guides/integrate/auth0-saml",
+            "guides/integrate/aws-saml",
+            "guides/integrate/pingidentity-saml",
+            "guides/integrate/atlassian-saml",
+            "guides/integrate/gitlab-saml",
+          ],
+        },
       ],
     },
     {
@@ -205,6 +231,14 @@ module.exports = {
         "apis/openidoauth/grant-types",
       ],
     },
+    {
+      type: "category",
+      label: "SAML",
+      collapsed: false,
+      items: [
+        "apis/saml/endpoints",
+      ],
+    },
     {
       type: "category",
       label: "Rate Limits",