Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document SAML assertion encryption as SP #3441

Merged
merged 11 commits into from
Dec 26, 2024
+104 −42
Merged

Document SAML assertion encryption as SP #3441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e35cb95
add SAML assertion decryption configuration to identity provider APIs…
spwitt Dec 23, 2024
eb472a5
document SAML IdP decryption ENG-1973
spwitt Dec 23, 2024
5416480
add missing username claim field ENG-1973
spwitt Dec 23, 2024
84a7f8d
document SAML IdP-initiated decryption ENG-1973
spwitt Dec 23, 2024
5aac62f
comma ENG-1973
spwitt Dec 26, 2024
e87671e
Merge branch 'main' into spencer/eng-1973/saml-sp-encryption
spwitt Dec 26, 2024
d2fc1d8
resolve linter errors ENG-1973
spwitt Dec 26, 2024
1f59d93
Shrink images
spwitt Dec 26, 2024
1381c62
Apply grammar/formatting suggestions
spwitt Dec 26, 2024
5cf1950
add key requirements for decryption ENG-1973
spwitt Dec 26, 2024
8be83ad
Merge branch 'spencer/eng-1973/saml-sp-encryption' of github.com:Fusi…
spwitt Dec 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified ...ity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified ...rs/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified .../authenticate-users/identity-providers/identity-provider-samlv2-add-options.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 14 additions & 4 deletions astro/src/content/docs/apis/identity-providers/_samlv2-request-body.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
</APIField>
<APIField name="identityProvider.assertionDecryptionConfiguration.enabled" type="Boolean" optional defaults="false" since="1.55.1">
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.
</APIField>
<APIField name="identityProvider.assertionDecryptionConfiguration.keyTransportDecryptionKeyId" type="UUID" optional since="1.55.1">
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 <InlineField>identityProvider.assertionDecryptionConfiguration.enabled</InlineField> is `true`.
</APIField>
<APIField name="identityProvider.buttonImageURL" type="String" optional renderif={!props.samlv2_idp_initiated}>
The top-level button image (URL) to use on the FusionAuth login page for this Identity Provider.
</APIField>
Expand Down Expand Up @@ -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.
</APIField>
<APIField name="identityProvider.keyId" type="UUID" required>
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).
</APIField>
<APIField name="identityProvider.lambdaConfiguration.reconcileId" type="UUID" optional>
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`.
</APIField>
Expand Down Expand Up @@ -143,6 +153,6 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap
</APIField>
</APIBlock>

{ props.samlv2_idp_initiated && <JSON title="Example SAML v2 Request JSON" src="identity-providers/samlv2-request.json" /> }
{ !props.samlv2_idp_initiated && <JSON title="Example SAML v2 Request JSON" src="identity-providers/samlv2-request.json" /> }

{ !props.samlv2_idp_initiated && <JSON title="Example SAML v2 IdP Initiated Request JSON" src="identity-providers/samlv2-idp-initiated-request.json" /> }
{ props.samlv2_idp_initiated && <JSON title="Example SAML v2 IdP Initiated Request JSON" src="identity-providers/samlv2-idp-initiated-request.json" /> }
14 changes: 11 additions & 3 deletions astro/src/content/docs/apis/identity-providers/_samlv2-response-body.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
</APIField>
<APIField name="identityProvider.assertionDecryptionConfiguration.enabled" type="Boolean" since="1.55.1">
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.
</APIField>
<APIField name="identityProvider.assertionDecryptionConfiguration.keyTransportDecryptionKeyId" type="UUID" since="1.55.1">
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.
</APIField>
<APIField name="identityProvider.buttonImageURL" type="String" renderif={!props.samlv2_idp_initiated}>
The top-level button image (URL) to use on the FusionAuth login page for this Identity Provider.
</APIField>
Expand Down Expand Up @@ -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.
</APIField>
<APIField name="identityProvider.keyId" type="UUID">
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).
</APIField>
<APIField name="identityProvider.lambdaConfiguration.reconcileId">
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.
</APIField>

<IdentityProviderLinkingStrategyResponseParameter idp_linking_strategy={props.idp_linking_strategy}
Expand Down Expand Up @@ -137,4 +145,4 @@ import Xmlsignaturec14nmethodValues from 'src/content/docs/_shared/_xmlSignature

{ !props.samlv2_idp_initiated && <JSON title="Example SAML v2 Response JSON" src="identity-providers/samlv2-response.json" /> }

{ props.samlv2_idp_initiated && <JSON title="Example SAML v2 IdP Initiated Response JSON" src="identity-providers/samlv2-idp-initiated-response.json" /> }
{ props.samlv2_idp_initiated && <JSON title="Example SAML v2 IdP Initiated Response JSON" src="identity-providers/samlv2-idp-initiated-response.json" /> }
63 changes: 40 additions & 23 deletions ...cycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@

## Create a SAML v2 IdP Initiated Identity Provider

To create an Identity Provider navigate to <strong>Settings -> Identity Providers</strong> and click <strong>Add provider</strong> and select <strong>SAML v2 IdP Initiated</strong>.
To create an Identity Provider navigate to **Settings -> Identity Providers**, click **Add provider**, and select **SAML v2 IdP Initiated**.

Check failure on line 52 in astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.", "location": {"path": "astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx", "range": {"start": {"line": 52, "column": 125}}}, "severity": "ERROR"}

This will take you to the <strong>Add SAML v2 IdP Initiated</strong> 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.

Check failure on line 54 in astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.", "location": {"path": "astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx", "range": {"start": {"line": 54, "column": 41}}}, "severity": "ERROR"}

<img src="/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png" alt="Add SAML v2 IdP Initiated" width="1200" role="bottom-cropped" />
![Add SAML v2 IdP Initiated](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add.png)

Check failure on line 56 in astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.", "location": {"path": "astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx", "range": {"start": {"line": 56, "column": 15}}}, "severity": "ERROR"}

### Form Fields

Expand All @@ -70,60 +70,77 @@
<APIField name="Issuer" required>
The EntityId (unique identifier) of the SAML v2 identity provider. This value should be provided to you.
</APIField>
<APIField name="Use NameId for email" optional>
If this is enabled, FusionAuth will assume that the `NameID` in the SAML response contains the email address of the user.
<APIField name="Verification key" required>
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.
</APIField>
<APIField name="Email claim" required>
The name of the email claim returned in the SAML response.
<APIField name="Linking strategy" optional since="1.28.0">
The linking strategy for the SAML v2 identity provider. See [Linking Strategies](/docs/lifecycle/authenticate-users/identity-providers/#linking-strategies) for more information.
</APIField>
<APIField name="Reconcile lambda" optional>
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 <InlineField>Use NameId for email</InlineField> is enabled this field will not be displayed and will not be required.
To configure a lambda, navigate to **Settings -> Lambdas**.
</APIField>
<APIField name="Verification key" required>
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.
<APIField name="Debug enabled" optional>
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**.
</APIField>
</APIBlock>

### Options

<img src="/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png" alt="Add SAML v2 Options section" width="1200" role="bottom-cropped" />
![Add SAML v2 Options section](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-add-options.png)

#### Form Fields

<APIBlock>
<APIField name="Reconcile lambda" optional>
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).
<APIField name="Unique Id claim" optional>
The name of the claim that is returned in the SAML response that contains the unique Id of the user.
</APIField>
<APIField name="Use NameId for email" optional>
If this is enabled, FusionAuth will assume that the `NameID` in the SAML response contains the email address of the user.
</APIField>
<APIField name="Email claim" required>
The name of the email claim returned in the SAML response.

To configure a lambda, navigate to <strong>Settings -> Lambdas</strong>.
When <InlineField>Use NameId for email</InlineField> is enabled, this field will not be displayed and will not be required.
</APIField>
<APIField name="Username claim" optional>
The name of the username claim returned in the SAML response.
</APIField>
<APIField name="Require encrypted assertions" optional since="1.55.1">
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.
spwitt marked this conversation as resolved.
Show resolved Hide resolved
</APIField>
<APIField name="Debug" optional>
Some identity providers are not compliant with the SAML and XML signing specifications. This makes it challenging to get them working with FusionAuth.
<APIField name="Assertion decryption key" optional since="1.55.1">
The key used to decrypt SAML responses. Required when <InlineField>Require encrypted assertions</InlineField> 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 <strong>System -> Event Log</strong>.
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.
</APIField>
</APIBlock>

## 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 <strong>Settings -> Identity Providers</strong> 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.

<img src="/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-view-list.png" alt="View the identity provider list" width="1200" role="bottom-cropped" />
![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 <strong>SAML v2 Integration details</strong> 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.

Check failure on line 128 in astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.", "location": {"path": "astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx", "range": {"start": {"line": 128, "column": 165}}}, "severity": "ERROR"}

### SAML v2 Integration Details

<img src="/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-view-details.png" alt="View the SAMLv2 identity provider details" width="1200" role="bottom-cropped" />
![View the SAMLv2 identity provider details](/img/docs/lifecycle/authenticate-users/identity-providers/enterprise/identity-provider-samlv2-idp-initiated-view-details.png)

#### Fields

<Fields idp_init />

## 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 <strong>Settings -> System -> CORS</strong> and add the SAML IdP origin as an <InlineField>Allowed Origin</InlineField> 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 <InlineField>Allowed Origin</InlineField> the CORS configuration.

Check failure on line 140 in astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'idp|IDP' instead of 'IdP'.", "location": {"path": "astro/src/content/docs/lifecycle/authenticate-users/identity-providers/enterprise/samlv2-idp-initiated.mdx", "range": {"start": {"line": 140, "column": 271}}}, "severity": "ERROR"}

## Troubleshooting

To troubleshoot, turn on the <InlineField>Debug</InlineField> option and then navigate to <strong>System -> Event Log</strong>.
To troubleshoot, turn on the <InlineField>Debug</InlineField> 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.
Loading
Loading