diff --git a/docs/am/4.11/.version-overrides b/docs/am/4.11/.version-overrides index 70632b1aa..fdfdf13ac 100644 --- a/docs/am/4.11/.version-overrides +++ b/docs/am/4.11/.version-overrides @@ -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/README.md +guides/identity-providers/enterprise-identity-providers/saml-2.0.md diff --git a/docs/am/4.11/guides/auth-protocols/saml-2.0.md b/docs/am/4.11/guides/auth-protocols/saml-2.0.md index c9058f8a1..9ed197ab5 100644 --- a/docs/am/4.11/guides/auth-protocols/saml-2.0.md +++ b/docs/am/4.11/guides/auth-protocols/saml-2.0.md @@ -4,7 +4,7 @@ [The Security Assertion Markup Language (SAML)](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) standard defines an XML-based framework for describing and exchanging security information between online business partners. -Gravitee Access Management (AM) supports the SAML protocol and can serve both as Identity Provider (IdP) and Service Provider (SP) : +Gravitee Access Management (AM) supports the SAML protocol and can serve both as Identity Provider (IdP) and Service Provider (SP): * [Configure AM as SAML Identity Provider](saml-2.0.md#enable-saml-2.0-identity-provider-support) * [Configure AM as SAML Service Provider](../identity-providers/enterprise-identity-providers/saml-2.0.md) @@ -25,12 +25,12 @@ An entity that authenticates users and provides to service providers (SP) an aut ## Enable SAML 2.0 Identity Provider support -Currently, AM supports the following SAML bindings : +Currently, AM supports the following SAML bindings: * HTTP-Redirect * HTTP-POST -and the following options : +and the following options: * Web Browser SSO Profile * Single Logout Profile @@ -66,8 +66,8 @@ SAML cannot currently be configured at the Organization level. To connect your applications to the AM SAML 2.0 IdP, you need at least the following information: -* **SingleSignOnService**, the SAML IdP Sign In URL : `https://AM_GATEWAY/{domain}/saml2/idp/SSO` -* **SingleLogoutService**, the SAML IdP Sign Out URL : `https://AM_GATEWAY/{domain}/saml2/idp/logout` +* **SingleSignOnService**, the SAML IdP Sign In URL: `https://AM_GATEWAY/{domain}/saml2/idp/SSO` +* **SingleLogoutService**, the SAML IdP Sign Out URL: `https://AM_GATEWAY/{domain}/saml2/idp/logout` * **Signing certificate**, the public signing certificate (encoded in PEM) {% hint style="info" %} @@ -85,5 +85,104 @@ You can test your SAML 2.0 connection using a web application created in AM. 7. If everything is OK, your user will be redirected to the application **attribute consume service URL** with the SAML Response assertion as a parameter. {% hint style="info" %} -SAML 2.0 IdP protocol is compatible out of the box with all the existing features of AM just like the OAuth 2.0/OpenId Connect protocol, such as passwordless, MFA, social login, etc. +SAML 2.0 IdP protocol is compatible out of the box with all the existing features of AM just like the OAuth 2.0/OpenID Connect protocol, such as passwordless, MFA, social login, etc. {% endhint %} + +## SAML Identity Provider Configuration + +SAML Identity Provider configuration supports automated metadata retrieval via URL or inline XML file, eliminating manual entry of IdP endpoints and certificates. Administrators can configure SAML IdPs by referencing a metadata endpoint or uploading metadata XML directly. + +### Metadata Provider Types + +SAML IdP metadata can be supplied through three methods: manual configuration (legacy), metadata URL, or metadata file. Manual configuration requires explicit entry of all IdP endpoints, certificates, and protocol bindings. Metadata URL retrieves IdP configuration from an HTTP(S) endpoint serving SAML metadata XML. Metadata file accepts inline XML content containing the IdP's SAML metadata descriptor. + +| Provider Type | Property | Description | +|:--------------|:---------|:------------| +| Manual | N/A | Legacy method requiring explicit endpoint and certificate configuration | +| Metadata URL | `idpMetadataUrl` | HTTP(S) endpoint serving IdP metadata XML (e.g., `https://.../saml2/idp/metadata`) | +| Metadata File | `idpMetadataFile` | Inline XML document containing IdP metadata descriptor | + +### Certificate References + +When using metadata URL or metadata file providers, the `graviteeCertificate` property references a certificate ID used to sign SAML AuthnRequests. The certificate must be pre-configured in the domain's certificate store using Java Keystore format. The IdP's signing certificate is extracted from the metadata XML and used to validate SAML assertions and responses. + +### Attribute Mapping + +SAML attributes returned in assertions are mapped to user profile fields using the `attributeMapping` configuration object. Keys are SAML attribute URNs (e.g., `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`) and values are target user profile field names (e.g., `email`, `firstname`, `lastname`). Mappings apply regardless of metadata provider type. + +### Prerequisites + +* Access Management domain with SAML 2.0 IdP plugin installed (`gravitee-am-idp-saml2` version 5.0.0-alpha.3 or later) +* Valid certificate configured in domain certificate store (Java Keystore format) when using metadata URL or metadata file providers +* IdP metadata endpoint accessible via HTTP(S) when using metadata URL provider +* IdP metadata XML containing `IDPSSODescriptor` and `SingleSignOnService` elements + +### Gateway Configuration + +#### SAML IdP Metadata Provider + +| Property | Description | Example | +|:---------|:------------|:--------| +| `idpMetadataProvider` | Metadata source type: `METADATA_URL` or `METADATA_FILE` | `METADATA_URL` | +| `idpMetadataUrl` | HTTP(S) endpoint serving IdP metadata XML (required when provider is `METADATA_URL`) | `https://am.example.com/domain-hrid/saml2/idp/metadata` | +| `idpMetadataFile` | Inline XML metadata content (required when provider is `METADATA_FILE`) | `Active Directory/LDAPactive-directory-ldap.mdHTTP (web service)http-web-service.mdKerberoskerberos.mdSAML 2.0saml-2.0.mdCAScas.md +SAML 2.0 supports metadata-based configuration via metadata URL or metadata file, enabling automated retrieval of IdP endpoints and certificates. + + Identity provider definitions apply at the _security domain_ level. diff --git a/docs/am/4.11/guides/identity-providers/enterprise-identity-providers/saml-2.0.md b/docs/am/4.11/guides/identity-providers/enterprise-identity-providers/saml-2.0.md index 6a2d93e7e..ea9b0fab9 100644 --- a/docs/am/4.11/guides/identity-providers/enterprise-identity-providers/saml-2.0.md +++ b/docs/am/4.11/guides/identity-providers/enterprise-identity-providers/saml-2.0.md @@ -4,10 +4,10 @@ SAML 2.0 stands for Security Assertion Markup Language 2.0. It is an XML-based open standard for transferring identity data between two parties: -* a SAML authority named an Identity Provider (IdP) -* a SAML consumer named a Service Provider (SP) +* A SAML authority named an Identity Provider (IdP) +* A SAML consumer named a Service Provider (SP) -SAML 2.0 specifies a web browser SSO profile involving an identity provider (IdP), a service provider (SP), and a principal wielding an HTTP user agent (a browser) which is used by AM to create a bridge between your applications and a SAML 2.0 IdP (Microsoft ADFS, for example). +SAML 2.0 specifies a web browser SSO profile involving an identity provider (IdP), a service provider (SP), and a principal wielding an HTTP user agent (a browser). AM uses this profile to create a bridge between your applications and a SAML 2.0 IdP (for example, Microsoft ADFS). {% hint style="info" %} In this scenario, the AM SAML 2.0 identity provider acts as the Service Provider (SP) via the SP-Initiated SSO flow. @@ -17,13 +17,18 @@ In this scenario, the AM SAML 2.0 identity provider acts as the Service Provider ## Get your SAML 2.0 identity provider (IdP) metadata -To connect your applications to a SAML 2.0 IdP, you need at least the following information: +Metadata for a SAML 2.0 identity provider (IdP) can be provided in one of three ways: -* **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 +* **Metadata URL**: Configuration is supplied by a remote SAML 2.0 metadata XML endpoint. This allows for the dynamic exchange of metadata while reducing the likelihood of configuration errors. Fetching and updating configuration of the IdP occurs at startup of AM and its plugins. +* **Metadata File**: Metadata is imported from an XML file. This is an alternative approach to hosting the metadata where security and versioning can be strictly controlled by static files, without a network dependency on startup. +* **Manual**: Metadata values are supplied individually to AM. {% hint style="info" %} +To connect your applications to a SAML 2.0 IdP manually, you need at least the following information: + +* **SingleSignOnService**: The SAML IdP Sign-In URL +* **Signing certificate**: The public signing certificate (encoded in PEM) provided by the identity provider + Before you begin, obtain this information from your SAML IdP administrator and make a note of it for later use. {% endhint %} @@ -34,37 +39,40 @@ Before you begin, obtain this information from your SAML IdP administrator and m 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. Select **IdP Metadata Provider**: + 1. For **Metadata URL**, enter **Entity ID (SP)** and **Metadata URL** values. If the metadata contains multiple entities, then **Entity ID (IdP)** is also required to select the right one. + 2. For **Metadata File**, enter **Entity ID (SP)** and paste the metadata XML in **Metadata File**. If the metadata contains multiple entities, then **Entity ID (IdP)** is also required to select the right one. + 3. For **Manual**, configure the required settings: **Entity ID (SP)**, **Sign In URL**, and **Signing Certificate**. 7. 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. +The connector includes advanced settings such as protocol binding (`HTTP-REDIRECT` or `HTTP-POST`), **Name ID 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. Make a note of the URL in **1. Configure the Redirect URI** on the right-hand side of the page. This is the SAML 2.0 Assertion Consumer Service URL you need to provide to the SAML 2.0 IdP to register your Access Management instance. From AM version 3.7, SAML IdP servers may ask you to share the SAML SP Metadata endpoint to register your AM instance. This endpoint can be found at: `https://AM_GW_HOST/:domain/saml2/sp/metadata/:providerId`. -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. +From SAML IdP plugin v1.4.0, encrypted assertion responses can be handled and decrypted. `KeyDescriptor` elements with `use="encryption"` are only published if the **wantAssertionsEncrypted** option is enabled. {% endhint %} ## Test the connection You can test your SAML 2.0 connection using a web application created in AM. -1. In AM Console, click **Applications > App > Identity Providers** and select your SAML 2.0 connector. +1. In AM Console, click **Applications > App > Identity Providers** and select your SAML 2.0 connector.

Select SAML 2.0 IdP

-2. Call the Login page (the `/oauth/authorize` endpoint). If the connection is working you will see a **Sign in with SAML 2.0** button. + +2. Call the Login page (the `/oauth/authorize` endpoint). If the connection is working you will see a **Sign in with SAML 2.0** button. If the button is not visible, there may be a problem with the identity provider settings. Check the AM Gateway log for more information. -3. Click **Sign in with SAML 2.0**. You will be redirected your SAML 2.0 IdP login page to authenticate your user. + +3. Click **Sign in with SAML 2.0**. You will be redirected to your SAML 2.0 IdP login page to authenticate your user. If your user is already connected (SSO session), the user will be automatically redirected to your application with an OAuth 2.0 access token and Open ID Connect ID token, if requested. {% hint style="info" %} -SAML responses can be very large. If you see an error message in the Gateway logs like this one: `Size exceeds allowed maximum capacity` - -update the `http.maxFormAttributeSize` value in the `gravitee.yml` config file (set it to `-1` for infinite). +SAML responses can be very large. If you see an error message in the Gateway logs like this one: `Size exceeds allowed maximum capacity`, 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/) +For more information, see [Configure AM Gateway](../../../getting-started/configuration/configure-am-gateway/). {% endhint %} diff --git a/docs/am/4.11/release-information/release-notes/am-4.11.md b/docs/am/4.11/release-information/release-notes/am-4.11.md index 044151276..1fcaffcdf 100644 --- a/docs/am/4.11/release-information/release-notes/am-4.11.md +++ b/docs/am/4.11/release-information/release-notes/am-4.11.md @@ -54,4 +54,15 @@ ## Improvements + + +#### **Enhanced SAML 2.0 Identity Provider Configuration Options** + +* SAML 2.0 identity providers can now be configured using three metadata provisioning methods: remote metadata URL, local metadata file upload, or manual entry of individual values. +* Metadata URL configuration enables dynamic metadata exchange and automatic updates at startup, reducing configuration errors and maintenance overhead. +* Metadata file upload provides an alternative for environments requiring strict security controls and version management without network dependencies. +* The SAML 2.0 SP metadata endpoint is now available at `https://AM_GW_HOST/:domain/saml2/sp/metadata/:providerId` for sharing with SAML IdP servers during registration. +* Encrypted assertion responses are supported when the **wantAssertionsEncrypted** option is enabled (requires SAML IdP plugin v1.4.0 or later). + + ## Bug Fixes