gravitee-io · Lyd1aCla1r3 · Mar 28, 2026
@@ -17,3 +17,6 @@ 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/auth-protocols/saml-2.0.md
+guides/identity-providers/enterprise-identity-providers/saml-2.0.md
+guides/identity-providers/enterprise-identity-providers/saml-identity-provider-configuration-reference.md
@@ -83,6 +83,7 @@
     * [Kerberos](guides/identity-providers/enterprise-identity-providers/kerberos.md)
     * [SAML 2.0](guides/identity-providers/enterprise-identity-providers/saml-2.0.md)
     * [CAS](guides/identity-providers/enterprise-identity-providers/cas.md)
+    * [SAML Identity Provider Configuration](guides/identity-providers/enterprise-identity-providers/saml-identity-provider-configuration-reference.md)
   * [Social Identity Providers](guides/identity-providers/social-identity-providers/README.md)
     * [OpenID Connect](guides/identity-providers/social-identity-providers/openid-connect.md)
     * [Azure AD](guides/identity-providers/social-identity-providers/azure-ad.md)

@@ -74,6 +74,8 @@ To connect your applications to the AM SAML 2.0 IdP, you need at least the follo
 SAML IdP metadata information can be found here: `https://AM_GATEWAY/{domain}/saml2/idp/metadata`
 {% endhint %}
 
+When configuring a SAML identity provider for a client application, you can use metadata-based configuration to automatically extract signing certificates and service endpoints. Set `idpMetadataProvider` to `METADATA_URL` and provide the metadata endpoint URL (e.g., `https://AM_GATEWAY/{provider-domain}/saml2/idp/metadata`), or set it to `METADATA_FILE` and upload the metadata XML directly. The client application can sign outbound SAML AuthnRequests using a certificate from the AM certificate repository by referencing its ID in the `graviteeCertificate` property.
+
 You can test your SAML 2.0 connection using a web application created in AM.
 
 1. In AM Console, create a new web application.

@@ -24,18 +24,42 @@ To connect your applications to a SAML 2.0 IdP, you need at least the following
 * **Signing certificate**: the public signing certificate (encoded in PEM) provided by the identity provider
 
 {% hint style="info" %}
-Before you begin, obtain this information from your SAML IdP administrator and make a note of it for later use.
+Before you begin, obtain this information from your SAML IdP administrator and make a note of it for later use. Alternatively, if your IdP publishes metadata at a stable URL or provides metadata as a downloadable XML file, you can use metadata-based configuration to automatically extract signing certificates, SSO endpoints, and protocol bindings.
 {% endhint %}
 
+## Prerequisites
+
+Before configuring a SAML identity provider, complete the following steps:
+
+* Configure an Access Management domain with a client application
+* Upload a certificate to the Access Management certificate repository (for signing AuthnRequests when using metadata-based modes) and note its ID
+* Ensure SAML identity provider metadata is accessible via HTTPS URL or available as an XML file (for metadata-based modes)
+* Verify network connectivity from Access Management gateway to the IdP metadata endpoint (for `METADATA_URL` mode)
+
+## Certificate roles
+
+Two certificate types are used in SAML flows:
+
+* **Gravitee certificate** (`graviteeCertificate` property): A certificate stored in Access Management's certificate repository, referenced by ID, and used by the client application to sign outbound SAML AuthnRequests when the IdP's metadata indicates `WantAuthnRequestsSigned=true`.
+* **IdP signing certificate**: Extracted from metadata (in metadata-based modes) or manually configured via the `signingCertificate` property (in manual mode), and used to verify signed SAML assertions and responses from the identity provider.
+
+Certificate synchronization between the client application and the provider domain is required when using metadata-based configuration.
+
 ## 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).
-7. Click **Create**.
+6. Select the metadata provider mode:
+   * If using metadata URL mode, set `idpMetadataProvider` to `METADATA_URL` and provide the `idpMetadataUrl` pointing to the IdP's metadata endpoint (for example, `https://gateway.example.com/provider-domain/saml2/idp/metadata`). Metadata URL must match pattern `^https?://.+/saml2/idp/metadata$`.
+   * If using metadata file mode, set `idpMetadataProvider` to `METADATA_FILE` and paste the IdP's metadata XML into `idpMetadataFile`. Metadata XML must match pattern `^<[?]?xml|^<[A-Za-z]` (starts with XML declaration or element tag).
+   * If using manual mode, configure the settings (EntityID, Sign In URL, Sign Out URL, Signing certificate).
+7. Set `graviteeCertificate` to the certificate ID from the prerequisites.
+8. Configure `entityId` to match the SAML entity identifier (for example, `saml-idp-provider-domain`).
+9. Optionally customize `requestSigningAlgorithm` and `attributeMapping`.
+10. Click **Create**.
 
 {% hint style="info" %}
 The connector includes some advanced settings such as protocol binding (HTTP-REDIRECT or HTTP-POST), NameId format and Request Signing options to connect to your SAML 2.0 IdP. If you need more information on how to configure these settings, check with your SAML IdP administrator.
@@ -47,6 +71,27 @@ 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 %}
 
+## Attribute mapping
+
+SAML attribute URIs from IdP assertions are mapped to user profile fields using the `attributeMapping` object. Default mappings include:
+
+* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` → `email`
+* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` → `firstname`
+* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` → `lastname`
+
+Administrators can override these mappings to align with their IdP's attribute schema.
+
+## Authenticating users
+
+Users authenticate via SAML by initiating login at the client application, which redirects to `/{clientDomain.hrid}/login/callback` with the SAML provider selected.
+
+1. The client generates a signed SAML AuthnRequest using the certificate referenced in `graviteeCertificate` and the algorithm specified in `requestSigningAlgorithm`.
+2. The user is redirected to the IdP (provider domain) and authenticates using inline identity provider credentials.
+3. The IdP generates a SAML Response with assertions, signing them if `wantAssertionsSigned=true` in the client's service provider configuration.
+4. The client validates the SAML Response using the IdP's signing certificate (extracted from metadata or manually configured).
+5. User attributes are mapped to profile fields using `attributeMapping`, and an OAuth 2.0 authorization code matching pattern `^[a-zA-Z0-9_-]+$` is issued.
+6. The user is redirected to the client application with the authorization code.
+
 ## Test the connection
 
 You can test your SAML 2.0 connection using a web application created in AM.
@@ -68,3 +113,11 @@ update the `http.maxFormAttributeSize` value in the `gravitee.yml` config file (
 
 [Learn more about updating the Gateway configuration file](../../../getting-started/configuration/configure-am-gateway/)
 {% endhint %}
+
+## Restrictions
+
+* SAML metadata URL must be publicly accessible from the Access Management gateway at configuration time. Firewall rules or network segmentation may prevent metadata retrieval when using `idpMetadataProvider=METADATA_URL`.
+* Metadata URL must match pattern `^https?://.+/saml2/idp/metadata$`.
+* Metadata XML must match pattern `^<[?]?xml|^<[A-Za-z]` (starts with XML declaration or element tag).
+* Certificate synchronization between client application and provider domain is required when using metadata-based configuration.
+
@@ -0,0 +1,51 @@
+# SAML Identity Provider Configuration Reference
+
+## Gateway Configuration
+
+### SAML Identity Provider Properties (Metadata URL Mode)
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `idpMetadataProvider` | Metadata source type; set to `METADATA_URL` | `METADATA_URL` |
+| `idpMetadataUrl` | URL endpoint serving IdP metadata XML; must match pattern `^https?://.+/saml2/idp/metadata$` | `https://gateway.example.com/provider-domain/saml2/idp/metadata` |
+| `entityId` | SAML entity identifier for the identity provider | `saml-idp-provider-domain` |
+| `graviteeCertificate` | Certificate ID from Access Management repository; used to sign AuthnRequests | `cert-abc123` |
+| `requestSigningAlgorithm` | XML signature algorithm URI for signing SAML requests | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` |
+| `attributeMapping` | Maps SAML attribute URIs to user profile fields | `{"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email"}` |
+
+### SAML Identity Provider Properties (Metadata File Mode)
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `idpMetadataProvider` | Metadata source type; set to `METADATA_FILE` | `METADATA_FILE` |
+| `idpMetadataFile` | Inline XML metadata document; must contain `IDPSSODescriptor` and `SingleSignOnService` elements; must match pattern `^<[?]?xml|^<[A-Za-z]` | `<EntityDescriptor>...</EntityDescriptor>` |
+| `entityId` | SAML entity identifier for the identity provider | `saml-idp-provider-domain` |
+| `graviteeCertificate` | Certificate ID from Access Management repository; used to sign AuthnRequests | `cert-abc123` |
+| `requestSigningAlgorithm` | XML signature algorithm URI for signing SAML requests | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` |
+| `attributeMapping` | Maps SAML attribute URIs to user profile fields | `{"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email"}` |
+
+### SAML Identity Provider Properties (Manual Mode)
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `entityId` | SAML entity identifier for the identity provider | `saml-idp-provider-domain` |
+| `signInUrl` | Single Sign-On service endpoint | `https://gateway.example.com/domain/saml2/idp/SSO` |
+| `signOutUrl` | Single Logout service endpoint | `https://gateway.example.com/domain/saml2/idp/logout` |
+| `singleLogoutServiceUrl` | Single Logout service URL | `https://gateway.example.com/domain/saml2/idp/logout` |
+| `signingCertificate` | X.509 PEM certificate of the IdP for verifying signed assertions | `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----` |
+| `wantAssertionsSigned` | Whether the SP requires signed SAML assertions | `false` |
+| `wantResponsesSigned` | Whether the SP requires signed SAML responses | `false` |
+| `protocolBinding` | SAML protocol binding for authentication requests | `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect` |
+| `signatureAlgorithm` | Signature algorithm for SAML assertions | `RSA_SHA256` |
+| `digestAlgorithm` | Digest algorithm for SAML signatures | `SHA256` |
+| `nameIDFormat` | SAML NameID format | `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` |
+| `attributeMapping` | Maps SAML attribute URIs to user profile fields | `{"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email"}` |
+
+### Certificate Configuration
+
+| Property | Description | Example |
+|:---------|:------------|:--------|
+| `type` | Certificate type for SAML signing | `javakeystore-am-certificate` |
+| `jks` | Java KeyStore configuration object containing base64-encoded content, store password, key alias, and key password | `{"content": "...", "storepass": "letmein", "alias": "mytestkey", "keypass": "changeme"}` |
+
+
@@ -20,7 +20,7 @@ Use the following HTTP Authorization request header to call the API: `Authorizat
 
 ### Token endpoint
 
-You can use the `token` endpoint to retrieve the `AM Management API token` . To retrieve the token, present the user credentials in the `Basic authentication scheme`.
+You can use the `token` endpoint to retrieve the `AM Management API token`. To retrieve the token, present the user credentials in the `Basic authentication scheme`.
 
 The following example exchanges default admin account credentials (`admin/adminadmin`) for a token:
 
@@ -76,4 +76,4 @@ POST http(s)://AM_MANAGEMENT_API/management/auth/login
 
 For user migrations from an alternative OIDC provider to Access Management, you can define the `lastPasswordReset` attribute. This attribute ensures that a password policy with password expiry requests a password reset according to the value provided during the migration.
 
-In Management REST API, `lastPasswordReset` attribute in the User definition is a long value representing the number of milliseconds since the standard base time known as "the epoch".
+In Management REST API, `lastPasswordReset` attribute in the User definition is a long value representing the number of milliseconds since the standard base time known as "the epoch".
@@ -52,6 +52,17 @@
 * Impersonation is enabled by default; delegation requires explicit configuration via `allowDelegation` setting.
 <!-- /PIPELINE:AM-6297 -->
 
+
+<!-- PIPELINE:AM-6340 -->
+#### **SAML Identity Provider Metadata Configuration**
+
+* SAML identity providers can now be configured using metadata URLs or inline XML files, eliminating manual endpoint and certificate configuration.
+* The system automatically extracts signing certificates, SSO endpoints, and protocol bindings from IdP metadata, reducing configuration errors.
+* Three configuration modes are supported: metadata URL (fetch from remote endpoint), metadata file (upload XML directly), and manual (legacy explicit configuration).
+* Certificate synchronization between client applications and provider domains is required when using metadata-based configuration.
+* Attribute mappings default to standard SAML claim URIs and can be customized to align with specific IdP schemas.
+<!-- /PIPELINE:AM-6340 -->
+
 ## Improvements
 
 ## Bug Fixes