diff --git a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png index 43eb332359..585ca944be 100644 Binary files a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png and b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png differ diff --git a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png index 47c620a32a..0f39dcbf94 100644 Binary files a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png and b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png differ diff --git a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-add-options.png b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-add-options.png index edd8fd0353..f9ecc67902 100644 Binary files a/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-add-options.png and b/astro/public/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-add-options.png differ diff --git a/astro/src/content/docs/apis/identity-providers/_samlv2-request-body.mdx b/astro/src/content/docs/apis/identity-providers/_samlv2-request-body.mdx index 934a51a3aa..f0b7fa712c 100644 --- a/astro/src/content/docs/apis/identity-providers/_samlv2-request-body.mdx +++ b/astro/src/content/docs/apis/identity-providers/_samlv2-request-body.mdx @@ -41,6 +41,16 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap * `Disabled` - Do not validate the Destination attribute. This is not recommended, please use with caution. * `AllowAlternates` - Verifies the Destination attribute is either the expected FusionAuth ACS, or one of the configured alternate values. This option is intended to assist with migrations from third-party IdPs and should be used with caution. + + Determines if FusionAuth requires encrypted assertions in SAML responses from the identity provider. + + When `true`, SAML responses from the identity provider containing unencrypted assertions will be rejected by FusionAuth. + + + The Id of the key stored in Key Master that is used to decrypt the symmetric key on the SAML response sent to FusionAuth from the identity provider. The selected Key must contain an RSA private key. + + Required when identityProvider.assertionDecryptionConfiguration.enabled is `true`. + The top-level button image (URL) to use on the FusionAuth login page for this Identity Provider. @@ -78,10 +88,10 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap The EntityId (unique identifier) of the SAML v2 identity provider. This value should be provided to you. Prior to 1.27.1 this value was required to be a URL. - The id of the key stored in Key Master that is used to verify the SAML response sent back to FusionAuth from the identity provider. This key must be a verification only key or certificate (meaning that it only has a public key component). + The Id of the key stored in Key Master that is used to verify the SAML response sent back to FusionAuth from the identity provider. This key must be a verification only key or certificate (meaning that it only has a public key component). - The id of a SAML reconcile lambda that is applied when the identity provider sends back a successful SAML response. + The Id of a SAML reconcile lambda that is applied when the identity provider sends back a successful SAML response. The specified Lambda Id must be of type `SAMLv2Reconcile`. @@ -143,6 +153,6 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap -{ props.samlv2_idp_initiated && } +{ !props.samlv2_idp_initiated && } -{ !props.samlv2_idp_initiated && } +{ props.samlv2_idp_initiated && } diff --git a/astro/src/content/docs/apis/identity-providers/_samlv2-response-body.mdx b/astro/src/content/docs/apis/identity-providers/_samlv2-response-body.mdx index 50615d3729..85f5e9ddea 100644 --- a/astro/src/content/docs/apis/identity-providers/_samlv2-response-body.mdx +++ b/astro/src/content/docs/apis/identity-providers/_samlv2-response-body.mdx @@ -39,6 +39,14 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature * `Disabled` - Do not validate the Destination attribute. This is not recommended, please use with caution. * `AllowAlternates` - Verifies the Destination attribute is either the expected FusionAuth ACS, or one of the configured alternate values. This option is intended to assist with migrations from third-party IdPs and should be used with caution. + + Determines if FusionAuth requires encrypted assertions in SAML responses from the identity provider. + + When `true`, SAML responses from the identity provider containing unencrypted assertions will be rejected by FusionAuth. + + + The Id of the key stored in Key Master that is used to decrypt the symmetric key on the SAML response sent back to FusionAuth from the identity provider. The selected Key must contain an RSA private key. + The top-level button image (URL) to use on the FusionAuth login page for this Identity Provider. @@ -79,10 +87,10 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature The [instant](/docs/reference/data-types#instants) that the provider was updated in the FusionAuth database. - The id of the key stored in KeyMaster that is used to verify the SAML response sent back to FusionAuth from the identity provider. This key must be a verification only key or certificate (meaning that it only has a public key component). + The Id of the key stored in KeyMaster that is used to verify the SAML response sent back to FusionAuth from the identity provider. This key must be a verification only key or certificate (meaning that it only has a public key component). - The id of a SAML reconcile lambda that is applied when the identity provider sends back a successful SAML response. + The Id of a SAML reconcile lambda that is applied when the identity provider sends back a successful SAML response. } -{ props.samlv2_idp_initiated && } \ No newline at end of file +{ props.samlv2_idp_initiated && } diff --git a/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx b/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx index c78d5a8da6..a6ac85063b 100644 --- a/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx +++ b/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx @@ -49,11 +49,11 @@ Once you have completed this configuration you will be able to log in to FusionA ## Create a SAML v2 IdP Initiated Identity Provider -To create an Identity Provider navigate to Settings -> Identity Providers and click Add provider and select SAML v2 IdP Initiated. +To create an Identity Provider navigate to **Settings -> Identity Providers**, click **Add provider**, and select **SAML v2 IdP Initiated**. -This will take you to the Add SAML v2 IdP Initiated panel. Here you will need to fill out the required fields. +This will take you to the **Add SAML v2 IdP Initiated** panel. Here you will need to fill out the required fields. -Add SAML v2 IdP Initiated +![Add SAML v2 IdP Initiated](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png) ### Form Fields @@ -70,49 +70,66 @@ This will take you to the Add SAML v2 IdP Initiated panel. Here The EntityId (unique identifier) of the SAML v2 identity provider. This value should be provided to you. - - If this is enabled, FusionAuth will assume that the `NameID` in the SAML response contains the email address of the user. + + The public key or certificate that you must import into FusionAuth's KeyMaster. This is the public key provided to you by the identity provider. - - The name of the email claim returned in the SAML response. + + The linking strategy for the SAML v2 identity provider. See [Linking Strategies](/docs/lifecycle/authenticate-users/identity-providers/#linking-strategies) for more information. + + + A lambda maps custom claims returned from the SAML response into the FusionAuth `User` and `Registration`. To learn more about creating a lambda, view the [SAML v2 Reconcile lambda documentation](/docs/extend/code/lambdas/samlv2-response-reconcile). - When Use NameId for email is enabled this field will not be displayed and will not be required. + To configure a lambda, navigate to **Settings -> Lambdas**. - - The public key or certificate that you must import into FusionAuth's KeyMaster. This is the public key provided to you by the identity provider. + + Some identity providers are not compliant with the SAML and XML signing specifications. This can make it challenging to integrate with them. + + If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in **System -> Event Log**. ### Options -Add SAML v2 Options section +![Add SAML v2 Options section](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png) #### Form Fields - - A lambda maps custom claims returned from the SAML response into the FusionAuth `User` and `Registration`. To learn more about creating a lambda, view the [SAML v2 Reconcile lambda documentation](/docs/extend/code/lambdas/samlv2-response-reconcile). + + The name of the claim that is returned in the SAML response that contains the unique Id of the user. + + + If this is enabled, FusionAuth will assume that the `NameID` in the SAML response contains the email address of the user. + + + The name of the email claim returned in the SAML response. - To configure a lambda, navigate to Settings -> Lambdas. + When Use NameId for email is enabled, this field will not be displayed and will not be required. + + + The name of the username claim returned in the SAML response. + + + When enabled FusionAuth requires encrypted assertions in SAML responses from the identity provider. SAML responses from the identity provider containing unencrypted assertions will be rejected by FusionAuth. - - Some identity providers are not compliant with the SAML and XML signing specifications. This makes it challenging to get them working with FusionAuth. + + The key used to decrypt SAML responses. Required when Require encrypted assertions is enabled. To create, manage or import a key, navigate to **Settings -> Key Master**. - If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in System -> Event Log. + The selected Key must contain an RSA private key. The associated public key or certificate should be provided to the SAML Identity Provider to encrypt assertions. ## Integration Details -After configuring the Identity Provider, FusionAuth will display values likely required by your SAML v2 Identity Provider to trust FusionAuth as a relying party. Do so by navigating to Settings -> Identity Providers and click the green magnifying glass on your SAML provider. +After configuring the Identity Provider, FusionAuth will display values likely required by your SAML v2 Identity Provider to trust FusionAuth as a relying party. Do so by navigating to **Settings -> Identity Providers** and click the green magnifying glass on your SAML provider. -View the identity provider list +![View the identity provider list](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-view-list.png) -When viewing the details, scroll to the SAML v2 Integration details section. There you will find the necessary values to configure an integration with a SAMLv2 IdP. +When viewing the details, scroll to the **SAML v2 Integration details** section. There you will find the necessary values to configure an integration with a SAMLv2 IdP. ### SAML v2 Integration Details -View the SAMLv2 identity provider details +![View the SAMLv2 identity provider details](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-view-details.png) #### Fields @@ -120,10 +137,10 @@ When viewing the details, scroll to the SAML v2 Integration detailsSettings -> System -> CORS and add the SAML IdP origin as an Allowed Origin the CORS configuration. +To complete the login request, the SAML v2 identity provider will make an HTTP `POST` request to the callback URL in FusionAuth. In order for this request to be allowed through the CORS filter you will need to navigate to **Settings -> System -> CORS** and add the SAML IdP origin as an Allowed Origin the CORS configuration. ## Troubleshooting -To troubleshoot, turn on the Debug option and then navigate to System -> Event Log. +To troubleshoot, turn on the Debug option and then navigate to **System -> Event Log**. Proceed through the SAML flow and review the Event log entries to see if there are any configuration issues. diff --git a/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2.mdx b/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2.mdx index b05ea4f196..118add4ff3 100644 --- a/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2.mdx +++ b/astro/src/content/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2.mdx @@ -42,7 +42,7 @@ Once you have completed this configuration you will be able to enable the SAML v ## Create a SAML v2 Identity Provider -To create an Identity Provider navigate to Settings -> Identity Providers and click `Add provider` and select `SAML v2` from the dialog. +To create an Identity Provider navigate to **Settings -> Identity Providers**, click `Add provider`, and select `SAML v2` from the dialog. This will take you to the `Add SAML v2` screen. Here you will need to fill out the required fields. If you do not know the IdP endpoint of your SAML v2 provider, you will need to contact the identity provider owner to get the URL. @@ -92,12 +92,12 @@ This will take you to the `Add SAML v2` screen. Here you will need to fill out t A lambda maps custom claims returned from the SAML Response to the FusionAuth User or Registration. - To create or configure a lambda, navigate to Settings -> Lambdas. [See the lambda documentation for more](/docs/extend/code/lambdas/). + To create or configure a lambda, navigate to **Settings -> Lambdas**. See the [lambda documentation](/docs/extend/code/lambdas/) for more information on using lambdas. Some identity providers are not compliant with the SAML and XML signing specifications. This makes it challenging to get them working with FusionAuth. - If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in System -> Event Log. + If you are running into integration issues, toggle this setting on and FusionAuth will output debugging information into the Event Log during a SAML login. You can find the event log in **System -> Event Log**. @@ -119,6 +119,9 @@ This will take you to the `Add SAML v2` screen. Here you will need to fill out t When Use NameId for email is enabled this field will not be displayed and will not be required. + + The name of the username claim returned in the SAML response. + When enabled the authentication request will use the HTTP POST binding with the identity provider instead of the default Redirect binding which uses the HTTP GET method. @@ -126,7 +129,7 @@ This will take you to the `Add SAML v2` screen. Here you will need to fill out t When enabled authentication requests sent to the Identity Provider will be signed. - The key used to sign the SAML request. Required when Sign request is enabled. To create, manage or import a key, navigate to Settings -> Key Master. + The key used to sign the SAML request. Required when Sign request is enabled. To create, manage, or import a key, navigate to **Settings -> Key Master**. The XML signature canonicalization method used when digesting and signing the SAML request. Required when Use POST method and Sign request are enabled. @@ -149,6 +152,14 @@ This will take you to the `Add SAML v2` screen. Here you will need to fill out t The array of URLs that FusionAuth will accept as SAML login destinations if the Destination Assertion Policy is `Allow alternates`. + + When enabled FusionAuth requires encrypted assertions in SAML responses from the identity provider. SAML responses from the identity provider containing unencrypted assertions will be rejected by FusionAuth. + + + The key used to decrypt SAML responses. Required when Require encrypted assertions is enabled. To create, manage or import a key, navigate to **Settings -> Key Master**. + + The selected Key must contain an RSA private key. The associated public key or certificate should be provided to the SAML Identity Provider to encrypt assertions. + ### Managed domains @@ -165,11 +176,11 @@ This will take you to the `Add SAML v2` screen. Here you will need to fill out t ## Integration Details -After configuring the Identity Provider, FusionAuth will display values likely required by your SAML v2 Identity Provider to trust FusionAuth as a relying party. Do so by navigating to Settings -> Identity Providers and click the green magnifying glass on your SAML provider. +After configuring the Identity Provider, FusionAuth will display values likely required by your SAML v2 Identity Provider to trust FusionAuth as a relying party. Do so by navigating to **Settings -> Identity Providers** and click the green magnifying glass on your SAML provider. ![View the identity provider list](/img/docs/lifecycle/authenticate-users/identity-providers/identity-provider-samlv2-view-list.png) -When viewing the details, scroll to the SAML v2 Integration details section. There you will find the necessary values to configure an integration with a SAMLv2 IdP. +When viewing the details, scroll to the **SAML v2 Integration details** section. There you will find the necessary values to configure an integration with a SAMLv2 IdP. ### SAML v2 Integration Details @@ -181,7 +192,7 @@ When viewing the details, scroll to the SAML v2 Integration detailsSettings -> System -> CORS and add the SAML IdP origin as an Allowed Origin the CORS configuration. +To complete the login request, the SAML v2 Identity Provider will make an HTTP `POST` request to the callback URL in FusionAuth. In order for this request to be allowed through the CORS filter you will need to navigate to **Settings -> System -> CORS** and add the SAML IdP origin as an Allowed Origin the CORS configuration. Once you complete your SAML v2 Identity Provider configuration, if your CORS configuration is not yet configured to allow the login request to complete you will be shown the following warning prompting you to complete the CORS configuration. See [CORS Filter reference](/docs/operate/secure-and-monitor/cors) for additional details on modifying the CORS configuration. @@ -210,7 +221,7 @@ While you can configure a lambda to be executed when a user logs in to FusionAut ### Troubleshooting SAML Flows -To troubleshoot, turn on the Debug option and then navigate to System -> Event Log. +To troubleshoot, turn on the Debug option and then navigate to **System -> Event Log**. Proceed through the SAML flow and review the Event log entries to see if there are any configuration issues. diff --git a/astro/src/content/json/identity-providers/samlv2-idp-initiated-request.json b/astro/src/content/json/identity-providers/samlv2-idp-initiated-request.json index 7235ea24fe..82e774531e 100644 --- a/astro/src/content/json/identity-providers/samlv2-idp-initiated-request.json +++ b/astro/src/content/json/identity-providers/samlv2-idp-initiated-request.json @@ -6,6 +6,10 @@ "enabled": true } }, + "assertionDecryptionConfiguration": { + "enabled": true, + "keyTransportDecryptionKeyId": "ce0ca33d-3555-4b89-9777-0ef1276f7b26" + }, "debug": false, "emailClaim": "email", "enabled": true, @@ -29,4 +33,4 @@ "useNameIdForEmail": true, "usernameClaim": "username" } -} \ No newline at end of file +} diff --git a/astro/src/content/json/identity-providers/samlv2-idp-initiated-response.json b/astro/src/content/json/identity-providers/samlv2-idp-initiated-response.json index a981e81b39..22ffdd1949 100644 --- a/astro/src/content/json/identity-providers/samlv2-idp-initiated-response.json +++ b/astro/src/content/json/identity-providers/samlv2-idp-initiated-response.json @@ -6,6 +6,10 @@ "enabled": true } }, + "assertionDecryptionConfiguration": { + "enabled": true, + "keyTransportDecryptionKeyId": "ce0ca33d-3555-4b89-9777-0ef1276f7b26" + }, "debug": false, "emailClaim": "email", "enabled": true, @@ -32,4 +36,4 @@ "useNameIdForEmail": true, "usernameClaim": "username" } -} \ No newline at end of file +} diff --git a/astro/src/content/json/identity-providers/samlv2-request.json b/astro/src/content/json/identity-providers/samlv2-request.json index f40901bece..4576a13526 100644 --- a/astro/src/content/json/identity-providers/samlv2-request.json +++ b/astro/src/content/json/identity-providers/samlv2-request.json @@ -13,6 +13,10 @@ "policy": "Enabled" } }, + "assertionDecryptionConfiguration": { + "enabled": true, + "keyTransportDecryptionKeyId": "ce0ca33d-3555-4b89-9777-0ef1276f7b26" + }, "buttonText": "Login with SAML", "debug": false, "emailClaim": "email", @@ -50,4 +54,4 @@ "useNameIdForEmail": true, "usernameClaim": "username" } -} \ No newline at end of file +} diff --git a/astro/src/content/json/identity-providers/samlv2-response.json b/astro/src/content/json/identity-providers/samlv2-response.json index d7b2cc3308..15f16880e2 100644 --- a/astro/src/content/json/identity-providers/samlv2-response.json +++ b/astro/src/content/json/identity-providers/samlv2-response.json @@ -13,6 +13,10 @@ "policy": "Enabled" } }, + "assertionDecryptionConfiguration": { + "enabled": true, + "keyTransportDecryptionKeyId": "ce0ca33d-3555-4b89-9777-0ef1276f7b26" + }, "buttonText": "Login with SAML", "emailClaim": "email", "debug" : false, @@ -54,4 +58,4 @@ "useNameIdForEmail": true, "usernameClaim": "username" } -} \ No newline at end of file +}