gravitee-io · Lyd1aCla1r3 · Mar 27, 2026
@@ -17,3 +17,4 @@ guides/oauth-2.0-token-exchange-api-reference.md
 guides/oauth-2.0-token-exchange-concepts.md
 guides/oauth-2.0-token-exchange-configuration-reference.md
 guides/using-oauth-2.0-token-exchange.md
+guides/identity-providers/enterprise-identity-providers/saml-2.0.md
@@ -15,26 +15,62 @@ In this scenario, the AM SAML 2.0 identity provider acts as the Service Provider
 
 <figure><img src="https://docs.gravitee.io/images/am/current/graviteeio-am-userguide-social-idp-saml2.png" alt=""><figcaption><p>AM SAML flow</p></figcaption></figure>
 
-## Get your SAML 2.0 identity provider (IdP) metadata
+SAML 2.0 identity provider configuration supports metadata-based setup through URL endpoints or inline XML files, simplifying integration with external IdPs. This feature includes enhanced JSON schema validation for oneOf constructs with improved default value handling.
+
+## Metadata Provider Modes
+
+SAML IdP configuration supports three metadata provider modes:
+
+| Mode | Required Fields | Use Case |
+|:-----|:----------------|:---------|
+| `METADATA_URL` | `idpMetadataUrl`, `graviteeCertificate` | Dynamic metadata retrieval from IdP endpoint |
+| `METADATA_FILE` | `idpMetadataFile`, `graviteeCertificate` | Static metadata embedded in configuration |
+| Manual | `signInUrl`, `signOutUrl`, `signingCertificate` | Full manual endpoint and certificate setup |
+
+**METADATA_URL** fetches IdP metadata from a runtime endpoint, requiring only the metadata URL and a Gravitee certificate reference. **METADATA_FILE** uses inline XML metadata provided directly in the configuration, also requiring a Gravitee certificate. **Manual configuration** (when `idpMetadataProvider` is not set) requires explicit specification of all IdP endpoints and the signing certificate in PEM format.
+
+## Get your SAML 2.0 identity provider metadata
 
 To connect your applications to a SAML 2.0 IdP, you need at least the following information:
 
 * **SingleSignOnService**: the SAML IdP Sign-In URL
 * **SingleLogoutService**: the SAML IdP Sign Out URL
 * **Signing certificate**: the public signing certificate (encoded in PEM) provided by the identity provider
 
+Alternatively, you can use metadata-based configuration by obtaining:
+
+* **IdP Metadata URL**: the endpoint where the IdP publishes its SAML metadata
+* **IdP Metadata File**: the complete XML metadata document from your IdP
+* **Gravitee Certificate**: a valid X.509 certificate uploaded to the Gravitee certificate store
+
 {% hint style="info" %}
 Before you begin, obtain this information from your SAML IdP administrator and make a note of it for later use.
 {% endhint %}
 
+## Prerequisites
+
+Before configuring SAML 2.0 identity provider integration:
+
+* Gravitee Access Management domain configured and running
+* SAML IdP metadata URL accessible from the client domain (for `METADATA_URL` mode)
+* Valid X.509 certificate uploaded to Gravitee certificate store (for metadata-based modes)
+* Java Keystore (JKS) file with signing certificate (for manual configuration in test environments)
+
+{% hint style="warning" %}
+Domain start operations include a 10-30 second synchronization delay to ensure the DEPLOY event is processed and the certificate provider is fully loaded before certificate PEM retrieval.
+{% endhint %}
+
 ## Create a SAML 2.0 connector
 
 1. Log in to AM Console.
 2. Click **Settings > Providers**.
 3. Click the plus icon ![plus icon](https://docs.gravitee.io/images/icons/plus-icon.png).
 4. Select **SAML 2.0** as your identity provider type and click **Next**.
 5. Give your identity provider a name.
-6. Configure the settings (EntityID, Sign In URL, Sign Out URL, Signing certificate).
+6. Configure the settings using one of the following methods:
+   * **Metadata URL mode**: Set **IdP Metadata Provider** to `METADATA_URL`, enter the IdP metadata URL (e.g., `https://gateway.example.com/domain/saml2/idp/metadata`), and select a certificate from the **Gravitee Certificate** dropdown.
+   * **Metadata File mode**: Set **IdP Metadata Provider** to `METADATA_FILE`, paste the XML metadata content into the **IdP Metadata File** textarea, and select a certificate from the **Gravitee Certificate** dropdown.
+   * **Manual mode**: Leave **IdP Metadata Provider** unset and configure EntityID, Sign In URL, Sign Out URL, and Signing certificate manually.
 7. Click **Create**.
 
 {% hint style="info" %}
@@ -47,6 +83,58 @@ From AM version 3.7, SAML IdP servers may ask you to share the SAML SP Metadata
 From SAML IdP plugin v1.4.0, encrypted assertion responses can be handled and decrypted. We decided to only publish KeyDescriptor with use="encryption" if the 'wantAssertionsEncrypted' option is enabled.
 {% endhint %}
 
+## Configuration Reference
+
+### SAML Identity Provider Properties
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `idpMetadataProvider` | Metadata source mode: `METADATA_URL`, `METADATA_FILE`, or omit for manual | `METADATA_URL` |
+| `idpMetadataUrl` | URL endpoint for fetching IdP metadata (required when `idpMetadataProvider=METADATA_URL`) | `https://gateway.example.com/domain/saml2/idp/metadata` |
+| `idpMetadataFile` | Inline XML metadata content (required when `idpMetadataProvider=METADATA_FILE`) | `<?xml version="1.0"?>\n<EntityDescriptor ...>` |
+| `graviteeCertificate` | Certificate ID from Gravitee certificate store (required for metadata modes) | `cert-id-123` |
+| `requestSigningAlgorithm` | Algorithm URI for signing AuthnRequests | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` |
+| `entityId` | SAML entity identifier for the IdP | `saml-idp-example` |
+| `signInUrl` | SAML SSO endpoint URL (manual mode only) | `https://gateway.example.com/domain/saml2/idp/SSO` |
+| `signOutUrl` | SAML logout endpoint URL (manual mode only) | `https://gateway.example.com/domain/saml2/idp/logout` |
+| `singleLogoutServiceUrl` | SAML single logout service URL (manual mode only) | `https://gateway.example.com/domain/saml2/idp/logout` |
+| `signingCertificate` | X.509 PEM certificate for verifying IdP signatures (manual mode only) | `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----` |
+| `wantAssertionsSigned` | Whether SAML assertions must be signed | `false` |
+| `wantResponsesSigned` | Whether SAML responses must be signed | `false` |
+| `protocolBinding` | SAML protocol binding URN | `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` |
+| `signatureAlgorithm` | Signature algorithm for SAML messages | `RSA_SHA256` |
+| `digestAlgorithm` | Digest algorithm for SAML signatures | `SHA256` |
+| `nameIDFormat` | SAML NameID format URN | `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` |
+
+### SAML Service Provider Properties
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `singleLogoutServiceUrl` | SP logout service URL | `https://gateway.example.com/domain/logout` |
+| `entityId` | SAML entity identifier for the SP (typically client ID) | `client-app-123` |
+| `wantResponseSigned` | Whether SP requires signed SAML responses | `false` |
+| `wantAssertionsSigned` | Whether SP requires signed SAML assertions | `true` |
+| `responseBinding` | SAML response binding method | `HTTP-POST` |
+| `certificate` | X.509 PEM certificate used by IdP to verify signed AuthnRequests from SP | `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----` |
+
+### Attribute Mapping
+
+| SAML Claim URI | Mapped Attribute | Description |
+|:---------------|:-----------------|:------------|
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `email` | User email address |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `firstname` | User first name |
+| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `lastname` | User last name |
+
+## Restrictions
+
+* SAML metadata URL must be accessible from the client domain at both configuration time and runtime
+* Metadata URL must match the pattern `^https?:\/\/.+\/saml2\/idp\/metadata$`
+* Metadata file XML must contain `IDPSSODescriptor` and `SingleSignOnService` elements
+* Metadata file must start with `<?xml` or `<[A-Za-z]`
+* Java Keystore (JKS) format is the only supported certificate format in test configurations
+* JSON schema validation with `useDefaults` enabled mutates the original `JSONObject` instance in-place rather than creating a defensive copy
+* everit validator processes all `allOf` subschemas regardless of intermediate failures, ensuring defaults are always injected
+
 ## Test the connection
 
 You can test your SAML 2.0 connection using a web application created in AM.
@@ -66,5 +154,15 @@ SAML responses can be very large. If you see an error message in the Gateway log
 
 update the `http.maxFormAttributeSize` value in the `gravitee.yml` config file (set it to `-1` for infinite).
 
-[Learn more about updating the Gateway configuration file](../../../getting-started/configuration/configure-am-gateway/)
+[Learn more about updating the Gateway configuration file](../../../getting-started/configuration/configure-am-gateway)
 {% endhint %}
+
+## Troubleshooting
+
+### Missing 'Sign in with SAML 2.0' button
+
+If the **Sign in with SAML 2.0** button does not appear on the login page, check the AM Gateway logs for identity provider configuration errors. Common issues include invalid metadata URLs, missing certificates, or incorrect endpoint configurations.
+
+## Related Changes
+
+The SAML 2.0 identity provider plugin (`gravitee-am-idp-saml2`) has been upgraded from version 4.0.3 to 5.0.0-alpha.3, introducing metadata provider selection in the configuration form. When **METADATA_URL** or **METADATA_FILE** is selected, the form hides manual endpoint fields (`signInUrl`, `signOutUrl`, `singleLogoutServiceUrl`, `signingCertificate`) and displays metadata-specific fields (**IdP Metadata URL** or **IdP Metadata File**, and **Gravitee Certificate** dropdown). Attribute mapping fields now include default mappings for common SAML claims (email, firstname, lastname). Existing manual configurations remain compatible but can be migrated to metadata-based modes by setting `idpMetadataProvider` and providing either `idpMetadataUrl` or `idpMetadataFile` along with a `graviteeCertificate` reference.
@@ -54,4 +54,15 @@
 
 ## Improvements
 
+
+<!-- PIPELINE:AM-6340 -->
+#### **SAML 2.0 Identity Provider Metadata Configuration Options**
+
+* SAML 2.0 identity providers can now be configured using three metadata provisioning methods: Metadata URL (remote endpoint), Metadata File (static XML import), or Manual (individual field entry).
+* Metadata URL and Metadata File options support multi-entity metadata documents by requiring an Entity ID (IdP) parameter to select the correct entity.
+* The Metadata URL option automatically fetches and updates IdP configuration at AM startup, reducing configuration errors and eliminating manual updates.
+* SAML SP Metadata endpoint is available at `https://AM_GW_HOST/:domain/saml2/sp/metadata/:providerId` for IdP registration (AM 3.7+).
+* Encrypted assertion responses are supported when the **wantAssertionsEncrypted** option is enabled (SAML IdP plugin v1.4.0+).
+<!-- /PIPELINE:AM-6340 -->
+
 ## Bug Fixes