Merge pull request #987 from logto-io/yemq-add-saml-app-docs

feat: add SAML app docs

docs/integrate-logto/README.mdx

@@ -54,7 +54,7 @@ Or try a no-code integration solution via Protected App when you’re using Logt
 
 When you want to enable third-party applications to authenticate with your Logto identity system, you can configure Logto as an [Identity Provider (IdP)](https://auth.wiki/identity-provider).
 
-Logto can be used as an IdP through standard protocols like OAuth, OIDC, or SAML (coming soon), and external services can implement "Sign in with Logto" just like "Sign in with Google", allowing their users to authenticate using your Logto user system.
+Logto can be used as an IdP through standard protocols like OAuth, OIDC, and external services can implement "Sign in with Logto" just like "Sign in with Google", allowing their users to authenticate using your Logto user system.
 
 By creating third-party applications in Logto, you establish secure connections between your identity system and external services.
 

docs/integrate-logto/application-data-structure.mdx

@@ -1,6 +1,6 @@
 ---
 description: Refer to key application parameters for OIDC authentication integration, including redirect URIs, endpoints, refresh tokens, backchannel logout, etc.
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Application data structure

docs/integrate-logto/integrate-logto-into-your-application/understand-authentication-flow.mdx

@@ -41,6 +41,7 @@ Logto provides [machine-to-machine (M2M) application](/quick-starts/m2m) type to
 
 ```mermaid
 sequenceDiagram
+    autonumber
     participant Service A
     participant Logto
     participant Service B
@@ -57,6 +58,41 @@ This machine-to-machine (M2M) authentication flow is designed for applications t
 
 In this flow, services authenticate using client credentials - a combination of [Application ID](/integrate-logto/application-data-structure/#application-id) and [Application Secret](/integrate-logto/application-data-structure/#application-secret) that uniquely identifies and authenticates the service. These credentials serve as the service's identity when requesting [access tokens](https://auth.wiki/access-token) from Logto.
 
+### SAML authentication flow \{#saml-authentication-flow}
+
+Besides OAuth 2.0 and OIDC, Logto also supports SAML (Security Assertion Markup Language) authentication, acting as an Identity Provider (IdP) to enable integration with enterprise applications. Currently, Logto supports SP-initiated authentication flow:
+
+#### SP-initiated flow \{#saml-authentication-flow-sp-init}
+
+In SP-initiated flow, the authentication process starts from the Service Provider (your application):
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User
+    participant Application
+    participant Logto
+
+    User->>Application: Click sign-in button
+    Application->>Logto: Send SAML authentication request
+    User->>Logto: Authenticate with Logto
+    Logto->>Application: Send SAML response with user info
+    Application->>User: Sign-in successful
+```
+
+In this flow:
+
+- The user starts the authentication process from your application (Service Provider)
+- Your application generates a SAML request and redirects the user to Logto (Identity Provider)
+- After successful authentication at Logto, a SAML response is sent back to your application
+- Your application processes the SAML response and completes the authentication
+
+#### IdP-initiated flow \{#saml-authentication-flow-idp-init}
+
+Logto will support IdP-initiated flow in future releases, enabling users to start the authentication process directly from Logto's portal. Stay tuned for updates on this feature.
+
+This SAML integration enables enterprise applications to leverage Logto as their identity provider, supporting both modern and legacy SAML-based service providers.
+
 ## Related resources \{#related-resources}
 
 <Url href="https://blog.logto.io/secure-cloud-apps-with-oauth-and-openid-connect">

docs/integrate-logto/interact-with-management-api/README.md

@@ -1,6 +1,6 @@
 ---
 description: Utilize Management APIs to access Logto’s backend services, scaling your CIAM system with user management, account settings, identity verification, and multi-tenant architecture.
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 import logtoManagementApiResourceSrc from './assets/logto-management-api-resource.webp';

docs/integrate-logto/saml-app/README.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 3
+---
+
+# SAML App
+
+Logto supports integration as an [Identity Provider (IdP)](https://auth.wiki/identity-provider) with SAML protocol-based applications [Service Provider, SP](https://auth.wiki/service-provider). Through SAML app integration, you can provide enterprise users with a secure, standardized Single Sign-On (SSO) experience.
+
+## Introduction \{#introduction}
+
+SAML (Security Assertion Markup Language) is an XML-based open standard for exchanging authentication and authorization data between parties. In a SAML integration:
+
+- **Logto as IdP**: Acts as the central authentication authority, managing user identities and issuing SAML assertions
+- **Your Application as SP**: Relies on Logto to authenticate users and consumes SAML assertions for access control
+
+### How SAML authentication works \{#how-saml-authentication-works}
+
+SAML authentication in Logto primarily follows the SP-initiated flow, where the authentication process starts from your application (Service Provider). Here's a brief overview:
+
+1. User attempts to access your application
+2. Your application generates a SAML request and redirects the user to Logto
+3. User authenticates with Logto
+4. Logto generates a SAML response containing user information
+5. Your application validates the response and grants access
+
+For a more detailed explanation of SAML authentication flows and comparison with other protocols, check out our [authentication flow guide](/integrate-logto/integrate-logto-into-your-application/understand-authentication-flow.mdx#saml-authentication-flow).
+
+### Benefits of SAML integration \{#benefits-of-saml-integration}
+
+- **Enhanced Security**: Encrypted communication and digital signatures ensure secure data exchange
+- **Simplified User Experience**: Users only need to sign in once to access multiple applications
+- **Reduced Administrative Overhead**: Centralized user management and access control
+- **Enterprise Readiness**: Widely adopted by organizations for secure identity federation
+
+## Key Features \{#key-features}
+
+- **Standardized Integration**: Full support for SAML 2.0 protocol, ensuring compatibility with various service providers
+- **Flexible Attribute Mapping**: Support for custom user attribute mapping to meet different application data requirements
+- **Secure and Reliable**: Support for signing and encryption to protect the authentication process
+- **Automatic Configuration**: Support for quick SAML integration setup via metadata URL or file
+
+## Use Cases \{#use-cases}
+
+SAML app integration is suitable for the following scenarios:
+
+- Enterprise application systems requiring Single Sign-On (SSO)
+- Integration with third-party services supporting SAML protocol
+- Requirements for high security and standardized authentication processes
+
+## Create an SAML application in Logto \{#create-an-saml-application-in-logto}
+
+1. Go to <CloudLink to="/applications">Console > Applications</CloudLink>
+2. Select "My apps" as the application type and choose the following integration protocol "SAML"
+3. Enter a name and description for your application and click on the “Create” button. A new SAML application will be created.
+
+## Configuration Guide \{#configuration-guide}
+
+To start using SAML app integration, you need to complete the following steps:
+
+1. [Configure SAML App](/integrate-logto/saml-app/setup.mdx): Set up basic SAML integration parameters
+2. [Configure Attribute Mapping](/integrate-logto/saml-app/attribute-mapping.mdx): Define how to map Logto user attributes to SAML assertions
+
+After completing the configuration, your application can securely authenticate and exchange data with Logto through the SAML protocol.

docs/integrate-logto/saml-app/attribute-mapping.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+---
+
+# Configure SAML assertion attributes
+
+SAML attributes are key components of SAML assertions that carry specific information about the authenticated user. These attributes can include user identifiers, roles, permissions, and other relevant user data that the Service Provider (SP) may need for authorization and personalization purposes.
+
+## Understanding SAML attributes \{#understanding-saml-attributes}
+
+In SAML authentication:
+
+- Attributes are name-value pairs that contain user information
+- They are included in the SAML assertion sent from the Identity Provider (Logto) to the Service Provider
+- They help Service Providers make informed decisions about user access and personalization
+
+![SAML app attribute mapping](./assets/attribute-mapping.png)
+
+## Attribute mapping in Logto \{#attribute-mapping-in-logto}
+
+Attribute mapping allows you to define how user information from Logto should be mapped to specific attributes in the SAML assertion. This mapping ensures that your Service Provider receives the user information in the expected format and under the expected attribute names.
+
+When you configure attribute mapping:
+
+1. You specify which user properties from Logto should be included in the SAML assertion
+2. You define custom attribute names that your Service Provider expects
+3. The mapped attributes are automatically included in the SAML assertion during authentication
+
+### Common attributes \{#common-attributes}
+
+Some commonly used SAML attributes include:
+
+- Sub (User ID)
+- Email
+- Organizations
+- Name
+- Preferred username
+
+By properly configuring attribute mapping, you ensure that your Service Provider receives all the necessary user information to provide appropriate access and personalization for your users.
+
+You can map all Logto available user information to your SP's expected attributes using the attribute mapping settings.

docs/integrate-logto/saml-app/setup.mdx

@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+---
+
+# Basic SAML integration setup
+
+This guide will help you configure your SAML application in Logto. Follow these steps to set up the basic SAML integration.
+
+## Application settings \{#application-settings}
+
+### Basic information \{#basic-information}
+
+- **Application name** (Required): Enter a name for your SAML application. This name will help you identify the application in Logto.
+- **Description**: Add an optional description to provide more details about your application.
+
+### SAML service provider configuration \{#saml-service-provider-configuration}
+
+- **Assertion consumer service URL (Reply URL)** (Required): Enter the URL where Logto should send the SAML assertion after successful authentication. This URL should match the ACS URL provided in your Service Provider (SP) application.
+
+- **Service Provider (SP) Entity ID** (Required): Enter the unique identifier for your Service Provider. This value should match the Entity ID found in your SP application. The SP Entity ID is a string input that typically follows a URI format (but not necessary).
+  - Common formats include:
+    - `urn:your-domain.com:sp:saml:{serviceProviderId}`
+    - `https://your-domain/saml/{serviceProviderId}`
+
+## SAML IdP metadata \{#saml-idp-metadata}
+
+After configuring the basic settings, Logto will provide you with important SAML Identity Provider (IdP) metadata that you'll need to configure in your Service Provider:
+
+### IdP metadata URL \{#idp-metadata-url}
+
+Use this URL to configure your SP with the IdP metadata. The metadata contains all necessary information for SAML integration.
+
+### Single sign-on service URL \{#single-sign-on-service-url}
+
+This is the URL where your SP should send SAML authentication requests.
+
+### IdP entity ID \{#idp-entity-id}
+
+The unique identifier for the Identity Provider.
+
+:::note
+"Single sign-on service URL" and "IdP entity ID" have already been included in IdP metadata, so you don't need to configure it separately if your SP can handle metadata URL.
+:::
+
+### SAML signing certificate \{#saml-signing-certificate}
+
+Logto uses this certificate to sign SAML assertions. You'll need to configure this in your SP to verify the signatures:
+
+- **Expires at**: The certificate's expiration date
+- **Fingerprint**: The certificate's unique fingerprint for verification
+- **Status**: The current status of the certificate (Active or Inactive)
+
+![SAML application certificates](./assets/certificates.png)
+
+:::note Important certificate management rules
+
+- Only one certificate can be active at a time. The active certificate will be used in the IdP metadata URL.
+- The IdP metadata URL will not be available if there is no active certificate.
+- You cannot delete an active certificate. To delete a certificate, you must first deactivate it.
+- When you activate an inactive certificate, the currently active certificate will be automatically deactivated.
+
+:::
+
+### Additional settings \{#additional-settings}
+
+#### Name ID format \{#name-id-format}
+
+Select how you want the user identifier to be formatted in the SAML assertion. The default is "Persistent" which uses the Logto user ID as the Name ID.
+
+![SAML name ID format](./assets/name-id-format.png)
+
+You can find there are four available formats provided by Logto:
+
+- **Persistent** (Use Logto user ID as Name ID): Creates a permanent, non-reusable identifier that remains consistent across sessions. This is ideal for maintaining a stable user identity across multiple sign-ins and is recommended for most enterprise applications.
+
+- **Email address** (Use email address as Name ID): Uses the user's email address as the identifier. This is useful when your Service Provider relies on email addresses for user identification or when you need human-readable identifiers.
+
+- **Transient** (Use one-time user ID as Name ID): Generates a temporary, one-time identifier that changes with each authentication request. This provides enhanced privacy and is suitable for applications where persistent user tracking is not desired.
+
+- **Unspecified** (Use Logto user ID as Name ID for now): Similar to Persistent format but indicates that no specific format is required. This offers flexibility while still using the stable Logto user ID as the identifier.
+
+#### Encrypt SAML assertion \{#encrypt-saml-assertion}
+
+Toggle this option if you want to encrypt the SAML assertion for enhanced security. When enabled, the SAML assertion will be encrypted before being sent to your SP.
+
+![SAML assertion encryption](./assets/encryption.png)
+
+:::note
+When you enable SAML assertion encryption, you must provide your Service Provider's signing certificate. This certificate will be used to encrypt the SAML assertion, ensuring that only your SP can decrypt and read the assertion content.
+:::

docs/integrate-logto/third-party-applications/README.mdx

@@ -1,10 +1,9 @@
 ---
 description: Use Logto to create your own Identity Provider and enable SSO for third-party applications. Effortlessly integrate OIDC, OAuth, or SAML application.
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 import OidcIcon from '@site/src/assets/oidc.svg';
-import SamlIcon from '@site/src/assets/saml.svg';
 
 # Third-party applications
 
@@ -21,7 +20,6 @@ This integration approach is well-suited for common business scenarios. You can
 1. Go to <CloudLink to="/applications">Console > Applications</CloudLink>
 2. Select "Third-party app" as the application type and choose one of the following integration protocols:
    - OIDC / OAuth
-   - SAML (Coming soon)
 3. Enter a name and description for your application and click on the “Create” button. A new third-party application will be created.
 
 All created third-party applications will be catalogued on the Applications page under the "Third-party apps" tab. This arrangement helps you distinguish them from your own applications, making it easier to manage all your applications in one place.
@@ -42,15 +40,5 @@ Based on the protocol type you selected when creating the third-party applicatio
         icon: <OidcIcon />,
       },
     },
-    {
-      type: 'link',
-      label: 'SAML (Coming soon)',
-      href: '/integrate-logto/third-party-applications/#setup-the-third-party-application-configurations',
-      description:
-        'Set up SAML configurations for your third-party application to integrate with Logto.',
-      customProps: {
-        icon: <SamlIcon />,
-      },
-    },
   ]}
 />

i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx

@@ -3,7 +3,7 @@ description: Erfahren Sie, wie Sie die Account API zur Verwaltung von Benutzern
 sidebar_position: 2
 ---
 
-# Kontoeinstellungen über die Account API
+# Kontoeinstellungen durch Account API
 
 ## Was ist die Logto Account API \{#what-is-logto-account-api}
 
@@ -44,7 +44,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \
   --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'
 ```
 
-Das `enabled`-Feld wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das `fields`-Feld wird verwendet, um die Felder anzupassen. Der Wert kann `Off`, `Edit`, `ReadOnly` sein. Der Standardwert ist `Off`. Die Liste der Felder:
+Das Feld `enabled` wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das Feld `fields` wird verwendet, um die Felder anzupassen. Der Wert kann `Off`, `Edit`, `ReadOnly` sein. Der Standardwert ist `Off`. Die Liste der Felder:
 
 - `name`: Das Namensfeld.
 - `avatar`: Das Avatar-Feld.
@@ -223,7 +223,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \
   --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'
 ```
 
-### E-Mail des Benutzers entfernen \{#remove-the-users-email}
+### Die E-Mail des Benutzers entfernen \{#remove-the-users-email}
 
 Um die E-Mail des Benutzers zu entfernen, können Sie den Endpunkt `DELETE /api/my-account/primary-email` verwenden.
 

i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/mfa/README.mdx

@@ -6,14 +6,14 @@ sidebar_position: 3
 
 ## Was ist MFA? \{#what-is-mfa}
 
-[Multi-Faktor-Authentifizierung (MFA)](https://auth.wiki/mfa) ist eine Sicherheitsmethode, die während des Anmeldeprozesses eine zusätzliche Schutzschicht hinzufügt. Sie erfordert, dass Benutzer mehrere Anmeldedaten bereitstellen, um ihre digitale Identität zu bestätigen.
+[Multi-Faktor-Authentifizierung (MFA)](https://auth.wiki/mfa) ist eine Sicherheitsmethode, die während des Anmeldeprozesses eine zusätzliche Schutzschicht hinzufügt. Sie erfordert von den Benutzern, mehrere Anmeldedaten bereitzustellen, um ihre digitale Identität zu bestätigen.
 
 Es gibt zwei Haupttypen der Authentifizierung:
 
 - **SFA/1FA (Single-Factor Authentication)**: Dies ist die anfängliche Anmeldemethode, die typischerweise einen [Benutzernamen / E-Mail / Telefon und Passwort](/end-user-flows/sign-up-and-sign-in/sign-in) oder [soziale Anmeldung](/end-user-flows/sign-up-and-sign-in/social-sign-in) erfordert.
 - **MFA/2FA (Multi-Faktor-Authentifizierung / Zwei-Faktor-Authentifizierung)**: MFA verlangt mindestens zwei verschiedene Verifizierungsmethoden, um auf dein Konto zuzugreifen, und stärkt so effektiv den Schutz gegen unbefugten Zugriff.
 
-Authentifizierungsfaktoren sind die Maßnahmen, die deine Identität überprüfen. Es gibt verschiedene Faktoren, die nach Attributen kategorisiert sind:
+Authentifizierungsfaktoren sind die Maßnahmen, die deine Identität überprüfen. Es gibt verschiedene Faktoren, die nach Attributen kategorisiert sind, aus denen du wählen kannst:
 
 | Typen    | Was es bedeutet     | Verifizierungsfaktoren (von Logto unterstützt)                                     |
 | -------- | ------------------- | ---------------------------------------------------------------------------------- |
@@ -33,7 +33,7 @@ MFA ist eine wichtige Sicherheitsmaßnahme, insbesondere für B2B- und B2E-Diens
 
 ## Logto-Unterstützung \{#logto-support}
 
-Logto vereinfacht den MFA-Aktivierungsprozess mit einem Ein-Klick-Umschalter und beseitigt die Notwendigkeit für komplexe Konfigurationen. Beginne mit unserem Schnellleitfaden zum [Aktivieren von Verifizierungsfaktoren](/end-user-flows/mfa/configure-mfa).
+Logto vereinfacht den MFA-Aktivierungsprozess mit einem Ein-Klick-Umschalter, der die Notwendigkeit komplexer Konfigurationen beseitigt. Beginne mit unserem Schnellleitfaden zum [Aktivieren von Verifizierungsfaktoren](/end-user-flows/mfa/configure-mfa).
 
 **Unterstützte MFA-Faktoren**: