AGENT-DRAFT: AM-6340 — SAML IdP Metadata Configuration [code+dev-draft]#1335
AGENT-DRAFT: AM-6340 — SAML IdP Metadata Configuration [code+dev-draft]#1335Lyd1aCla1r3 wants to merge 2 commits intomainfrom
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
vale
[vale] reported by reviewdog 🐶
Microsoft.SentenceLength:Try to keep sentences short (< 30 words).
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
[vale] reported by reviewdog 🐶
Microsoft.Contractions:Use 'that's' instead of 'that is'. (https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions)
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| [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): |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| SAML cannot currently be configured at the Organization level. | ||
| {% endhint %} | ||
|
|
||
| ### SAML IdP Metadata Endpoint |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ### SAML IdP Metadata Endpoint | ||
|
|
||
| The SAML IdP metadata endpoint exposes the provider domain's SAML configuration as an XML metadata document. The endpoint URL follows the pattern: |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| The SAML IdP metadata endpoint exposes the provider domain's SAML configuration as an XML metadata document. The endpoint URL follows the pattern: | ||
|
|
||
| ``` | ||
| {AM_GATEWAY_URL}/{domain_hrid}/saml2/idp/metadata |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'idp'.
| {AM_GATEWAY_URL}/{domain_hrid}/saml2/idp/metadata | ||
| ``` | ||
|
|
||
| The endpoint returns XML containing `IDPSSODescriptor` and `SingleSignOnService` elements. This endpoint is used by metadata URL mode configurations and by external service providers integrating with the IdP. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| * **Provider domain (acting as IdP)**: Requires a Java keystore certificate used by the `saml2-idp` plugin to sign SAML assertions. | ||
| * **Client domain (acting as SP)**: Requires a certificate for signing AuthnRequests when the IdP metadata specifies `WantAuthnRequestsSigned=true`, referenced via the `graviteeCertificate` property. | ||
| * **Service provider applications**: Provide their certificate as a PEM string, which the IdP uses to verify signed AuthnRequests. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ## Prerequisites | ||
|
|
||
| Before configuring SAML IdP metadata, ensure the following requirements are met: |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| Before configuring SAML IdP metadata, ensure the following requirements are met: | ||
|
|
||
| * Provider domain configured and started (for IdP role) |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| * Client domain configured (for SP role) | ||
| * Java keystore certificate created in provider domain (type: `javakeystore-am-certificate`) | ||
| * Certificate created in client domain when using metadata URL/file mode with `WantAuthnRequestsSigned=true` | ||
| * Valid SAML IdP metadata URL or metadata XML file |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| @@ -0,0 +1,5 @@ | |||
| # SAML IdP Plugin Version Upgrade Notes | |||
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
…step - Added 6-item Restrictions section (metadata mode exclusivity, XML validation, SyncManager timing, cert type, URL pattern) - Expanded connector step 6 with UI field names from dev draft (Entity ID SP/IdP, Metadata URL/File, Manual sub-steps) Coverage: 38/38 key data items verified present.
| 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. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ### Metadata URL Mode | ||
|
|
||
| To configure a SAML IdP using a metadata URL, create an identity provider of type `saml2-generic-am-idp` in the client domain. 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`). Specify the `entityId` to uniquely identify the IdP. If the IdP metadata indicates `WantAuthnRequestsSigned=true`, reference a certificate via `graviteeCertificate` and set `requestSigningAlgorithm` to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`. Configure `attributeMapping` to map SAML assertion attributes to user profile fields. The system fetches and parses the metadata XML, automatically extracting single sign-on and logout endpoints. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ### Metadata File Mode | ||
|
|
||
| To configure a SAML IdP using a metadata file, create an identity provider of type `saml2-generic-am-idp` in the client domain. Set `idpMetadataProvider` to `"METADATA_FILE"` and provide the complete IdP metadata XML document in `idpMetadataFile`. Specify the `entityId` to uniquely identify the IdP. If the IdP metadata indicates `WantAuthnRequestsSigned=true`, reference a certificate via `graviteeCertificate` and set `requestSigningAlgorithm` to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`. Configure `attributeMapping` to map SAML assertion attributes to user profile fields. The system parses the metadata XML, automatically extracting single sign-on and logout endpoints. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| |:---------|:------------|:--------| | ||
| | `idpMetadataProvider` | Metadata source type | `"METADATA_FILE"` | | ||
| | `entityId` | SAML entity identifier | `saml-idp-client-domain` | | ||
| | `idpMetadataFile` | Complete IdP metadata XML document | Full XML content | |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| | Property | Description | Example | | ||
| |:---------|:------------|:--------| | ||
| | `entityId` | SAML entity identifier | `saml-idp-client-domain` | | ||
| | `signInUrl` | IdP single sign-on endpoint | `https://gateway.example.com/client-domain/saml2/idp/SSO` | |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ## Related Changes | ||
|
|
||
| The `gravitee-am-idp-saml2` plugin was upgraded from version `4.0.3` to `5.0.0-alpha.3` to support metadata URL and metadata file configuration modes. The `gravitee-plugin-validator` dependency was updated from `2.0.2` to `2.3.0` to support validation of the new configuration properties. The SAML authentication flow remains unchanged—users initiate login via the client application, navigate to the SAML provider login page, submit credentials to the SAML IdP, and receive a SAML assertion that is validated and exchanged for an authorization code. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Microsoft.SentenceLength:Try to keep sentences short (< 30 words).
|
|
||
| ## Related Changes | ||
|
|
||
| The `gravitee-am-idp-saml2` plugin was upgraded from version `4.0.3` to `5.0.0-alpha.3` to support metadata URL and metadata file configuration modes. The `gravitee-plugin-validator` dependency was updated from `2.0.2` to `2.3.0` to support validation of the new configuration properties. The SAML authentication flow remains unchanged—users initiate login via the client application, navigate to the SAML provider login page, submit credentials to the SAML IdP, and receive a SAML assertion that is validated and exchanged for an authorization code. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| ## Related Changes | ||
|
|
||
| The `gravitee-am-idp-saml2` plugin was upgraded from version `4.0.3` to `5.0.0-alpha.3` to support metadata URL and metadata file configuration modes. The `gravitee-plugin-validator` dependency was updated from `2.0.2` to `2.3.0` to support validation of the new configuration properties. The SAML authentication flow remains unchanged—users initiate login via the client application, navigate to the SAML provider login page, submit credentials to the SAML IdP, and receive a SAML assertion that is validated and exchanged for an authorization code. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Microsoft.Contractions:Use 'that's' instead of 'that is'. (https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions)
|
|
||
|
|
||
| <!-- PIPELINE:AM-6340 --> | ||
| #### **SAML IdP Metadata Configuration** |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
|
|
||
| * Configure SAML 2.0 identity providers using metadata URLs or metadata files instead of manually entering individual SAML endpoints. | ||
| * Supports three configuration modes: manual endpoint entry, metadata URL fetching, and metadata file upload. | ||
| * Automatically extracts IdP configuration including sign-in URL, sign-out URL, and single logout service URL from metadata sources. |
There was a problem hiding this comment.
[vale] reported by reviewdog 🐶
Vale.Terms:Use 'IDP' instead of 'IdP'.
| The SAML IdP metadata endpoint exposes the provider domain's SAML configuration as an XML metadata document. The endpoint URL follows the pattern: | ||
|
|
||
| ``` | ||
| {AM_GATEWAY_URL}/{domain_hrid}/saml2/idp/metadata |
There was a problem hiding this comment.
minor: other endpoint examples use the format https://AM_GATEWAY/{domain}/.
| 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 |
There was a problem hiding this comment.
issue: this is out of date since it does not apply in all cases. See change request.
|
|
||
| SAML IdP configuration supports three mutually exclusive modes: | ||
|
|
||
| * **Manual mode**: Requires entering individual SAML endpoints (sign-in URL, sign-out URL, single logout service URL) and settings. |
There was a problem hiding this comment.
issue: sign out URL is not required.
|
|
||
| Each mode requires the same certificate and attribute mapping configuration but differs in how core SAML endpoints are specified. | ||
|
|
||
| | Mode | Property | Value Type | Use Case | |
There was a problem hiding this comment.
issue: typically we describe fields as seen on the UI. This describes the API.
|
|
||
| ### SAML Entity and Certificates | ||
|
|
||
| The SAML entity identifier (`entityId`) uniquely identifies the IdP in SAML exchanges, typically formatted as `saml-idp-{domainSuffix}`. Certificate configuration varies by domain role: |
There was a problem hiding this comment.
question: not sure where the typical format comes from. Again, maybe we shouldn't describe JSON properties at this level either?
|
|
||
| ### Metadata URL Mode | ||
|
|
||
| To configure a SAML IdP using a metadata URL, create an identity provider of type `saml2-generic-am-idp` in the client domain. 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`). Specify the `entityId` to uniquely identify the IdP. If the IdP metadata indicates `WantAuthnRequestsSigned=true`, reference a certificate via `graviteeCertificate` and set `requestSigningAlgorithm` to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`. Configure `attributeMapping` to map SAML assertion attributes to user profile fields. The system fetches and parses the metadata XML, automatically extracting single sign-on and logout endpoints. |
There was a problem hiding this comment.
suggestion: the steps here are for the API rather than the UI, which is inconsistent. They should also be numbered for readability IMO.
|
|
||
| To configure a SAML IdP using a metadata URL, create an identity provider of type `saml2-generic-am-idp` in the client domain. 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`). Specify the `entityId` to uniquely identify the IdP. If the IdP metadata indicates `WantAuthnRequestsSigned=true`, reference a certificate via `graviteeCertificate` and set `requestSigningAlgorithm` to `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`. Configure `attributeMapping` to map SAML assertion attributes to user profile fields. The system fetches and parses the metadata XML, automatically extracting single sign-on and logout endpoints. | ||
|
|
||
| | Property | Description | Example | |
There was a problem hiding this comment.
issue: the tables outline JSON properties for the API rather than field names from the UI. This does not match surrounding docs AFAICT and is a paradigm shift.
There was a problem hiding this comment.
thought: this feels like a fairly high level place for a feature improvement. I worry that a habit of adding pages here could become problematic.
We certainly shouldn't document specific alpha versions (5.0.0-alpha.3).
| 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". No newline at end of file | ||
| 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". | ||
|
|
||
| ## SAML 2.0 Identity Provider Configuration |
There was a problem hiding this comment.
issue: I don't see how this section is relevant to this page. For the most part I think users rely on the generated API specification and this is only for basic usage and historical gotchas.
2 participants
Automated update: am-6340
Product: am
Version: 4.11