Create relying party trusts in AD FS

10/12/2023 Contributors

You must use Active Directory Federation Services (AD FS) to create a relying party trust for each Admin Node in your system. You can create relying party trusts using PowerShell commands, by importing SAML metadata from StorageGRID, or by entering the data manually.

Before you begin

You have configured single sign-on for StorageGRID and you selected AD FS as the SSO type.
Sandbox mode is selected on the Single sign-on page in Grid Manager. See Use sandbox mode.

You know the fully qualified domain name (or the IP address) and the relying party identifier for each Admin Node in your system. You can find these values in the Admin Nodes detail table on the StorageGRID Single Sign-on page.

You must create a relying party trust for each Admin Node in your StorageGRID system. Having a relying party trust for each Admin Node ensures that users can securely sign in to and out of any Admin Node.

You have experience creating relying party trusts in AD FS, or you have access to the Microsoft AD FS documentation.
You are using the AD FS Management snap-in, and you belong to the Administrators group.
If you are creating the relying party trust manually, you have the custom certificate that was uploaded for the StorageGRID management interface, or you know how to log in to an Admin Node from the command shell.

About this task

These instructions apply to Windows Server 2016 AD FS. If you are using a different version of AD FS, you will notice slight differences in the procedure. See the Microsoft AD FS documentation if you have questions.

Create a relying party trust using Windows PowerShell

You can use Windows PowerShell to quickly create one or more relying party trusts.

Steps

From the Windows start menu, right-select the PowerShell icon, and select Run as Administrator.
At the PowerShell command prompt, enter the following command:

`Add-AdfsRelyingPartyTrust -Name "Admin_Node_Identifer" -MetadataURL "https://Admin_Node_FQDN/api/saml-metadata"
- For Admin_Node_Identifier, enter the Relying Party Identifier for the Admin Node, exactly as it appears on the Single Sign-on page. For example, SG-DC1-ADM1.
- For Admin_Node_FQDN, enter the fully qualified domain name for the same Admin Node. (If necessary, you can use the node's IP address instead. However, if you enter an IP address here, be aware that you must update or recreate this relying party trust if that IP address ever changes.)
From Windows Server Manager, select Tools > AD FS Management.

The AD FS management tool appears.
Select AD FS > Relying Party Trusts.

The list of relying party trusts appears.
Add an Access Control Policy to the newly created relying party trust:
1. Locate the relying party trust you just created.
2. Right-click the trust, and select Edit Access Control Policy.
3. Select an Access Control Policy.
4. Select Apply, and select OK
Add a Claim Issuance Policy to the newly created Relying Party Trust:
1. Locate the relying party trust you just created.
2. Right-click the trust, and select Edit claim issuance policy.
3. Select Add rule.
4. On the Select Rule Template page, select Send LDAP Attributes as Claims from the list, and select Next.
5. On the Configure Rule page, enter a display name for this rule.
  
  For example, ObjectGUID to Name ID or UPN to Name ID.
6. For the Attribute Store, select Active Directory.
7. In the LDAP Attribute column of the Mapping table, type objectGUID or select User-Principal-Name.
8. In the Outgoing Claim Type column of the Mapping table, select Name ID from the drop-down list.
9. Select Finish, and select OK.
Confirm that the metadata was imported successfully.
1. Right-click the relying party trust to open its properties.
2. Confirm that the fields on the Endpoints, Identifiers, and Signature tabs are populated.
  
  If the metadata is missing, confirm that the Federation metadata address is correct, or enter the values manually.
Repeat these steps to configure a relying party trust for all of the Admin Nodes in your StorageGRID system.
When you are done, return to StorageGRID and test all relying party trusts to confirm they are configured correctly. See Use Sandbox mode for instructions.

Create a relying party trust by importing federation metadata

You can import the values for each relying party trust by accessing the SAML metadata for each Admin Node.

Steps

In Windows Server Manager, select Tools, and then select AD FS Management.
Under Actions, select Add Relying Party Trust.
On the Welcome page, choose Claims aware, and select Start.
Select Import data about the relying party published online or on a local network.
In Federation metadata address (host name or URL), type the location of the SAML metadata for this Admin Node:

https://Admin_Node_FQDN/api/saml-metadata

For Admin_Node_FQDN, enter the fully qualified domain name for the same Admin Node. (If necessary, you can use the node's IP address instead. However, if you enter an IP address here, be aware that you must update or recreate this relying party trust if that IP address ever changes.)
Complete the Relying Party Trust wizard, save the relying party trust, and close the wizard.

When entering the display name, use the Relying Party Identifier for the Admin Node, exactly as it appears on the Single Sign-on page in the Grid Manager. For example, SG-DC1-ADM1.
Add a claim rule:
1. Right-click the trust, and select Edit claim issuance policy.
2. Select Add rule:
3. On the Select Rule Template page, select Send LDAP Attributes as Claims from the list, and select Next.
4. On the Configure Rule page, enter a display name for this rule.
  
  For example, ObjectGUID to Name ID or UPN to Name ID.
5. For the Attribute Store, select Active Directory.
6. In the LDAP Attribute column of the Mapping table, type objectGUID or select User-Principal-Name.
7. In the Outgoing Claim Type column of the Mapping table, select Name ID from the drop-down list.
8. Select Finish, and select OK.
Confirm that the metadata was imported successfully.
1. Right-click the relying party trust to open its properties.
2. Confirm that the fields on the Endpoints, Identifiers, and Signature tabs are populated.
  
  If the metadata is missing, confirm that the Federation metadata address is correct, or enter the values manually.
Repeat these steps to configure a relying party trust for all of the Admin Nodes in your StorageGRID system.
When you are done, return to StorageGRID and test all relying party trusts to confirm they are configured correctly. See Use Sandbox mode for instructions.

Create a relying party trust manually

If you choose not to import the data for the relying part trusts, you can enter the values manually.

Steps

In Windows Server Manager, select Tools, and then select AD FS Management.
Under Actions, select Add Relying Party Trust.
On the Welcome page, choose Claims aware, and select Start.
Select Enter data about the relying party manually, and select Next.
Complete the Relying Party Trust wizard:
1. Enter a display name for this Admin Node.
  
  For consistency, use the Relying Party Identifier for the Admin Node, exactly as it appears on the Single Sign-on page in the Grid Manager. For example, SG-DC1-ADM1.
2. Skip the step to configure an optional token encryption certificate.
3. On the Configure URL page, select the Enable support for the SAML 2.0 WebSSO protocol checkbox.
4. Type the SAML service endpoint URL for the Admin Node:
  
  https://Admin_Node_FQDN/api/saml-response
  
  For Admin_Node_FQDN, enter the fully qualified domain name for the Admin Node. (If necessary, you can use the node's IP address instead. However, if you enter an IP address here, be aware that you must update or recreate this relying party trust if that IP address ever changes.)
5. On the Configure Identifiers page, specify the Relying Party Identifier for the same Admin Node:
  
  Admin_Node_Identifier
  
  For Admin_Node_Identifier, enter the Relying Party Identifier for the Admin Node, exactly as it appears on the Single Sign-on page. For example, SG-DC1-ADM1.
6. Review the settings, save the relying party trust, and close the wizard.
  
  The Edit Claim Issuance Policy dialog box appears.
  
  If the dialog box does not appear, right-click the trust, and select Edit claim issuance policy.
To start the Claim Rule wizard, select Add rule:
1. On the Select Rule Template page, select Send LDAP Attributes as Claims from the list, and select Next.
2. On the Configure Rule page, enter a display name for this rule.
  
  For example, ObjectGUID to Name ID or UPN to Name ID.
3. For the Attribute Store, select Active Directory.
4. In the LDAP Attribute column of the Mapping table, type objectGUID or select User-Principal-Name.
5. In the Outgoing Claim Type column of the Mapping table, select Name ID from the drop-down list.
6. Select Finish, and select OK.
Right-click the relying party trust to open its properties.
On the Endpoints tab, configure the endpoint for single logout (SLO):
1. Select Add SAML.
2. Select Endpoint Type > SAML Logout.
3. Select Binding > Redirect.
4. In the Trusted URL field, enter the URL used for single logout (SLO) from this Admin Node:
  
  https://Admin_Node_FQDN/api/saml-logout
  
  For Admin_Node_FQDN, enter the Admin Node's fully qualified domain name. (If necessary, you can use the node's IP address instead. However, if you enter an IP address here, be aware that you must update or recreate this relying party trust if that IP address ever changes.)
5. Select OK.
On the Signature tab, specify the signature certificate for this relying party trust:
1. Add the custom certificate:
  - If you have the custom management certificate you uploaded to StorageGRID, select that certificate.
  - If you don't have the custom certificate, log in to the Admin Node, go the /var/local/mgmt-api directory of the Admin Node, and add the custom-server.crt certificate file.
    
    Note: Using the Admin Node's default certificate (server.crt) is not recommended. If the Admin Node fails, the default certificate will be regenerated when you recover the node, and you will need to update the relying party trust.
2. Select Apply, and select OK.
  
  The Relying Party properties are saved and closed.
Repeat these steps to configure a relying party trust for all of the Admin Nodes in your StorageGRID system.
When you are done, return to StorageGRID and test all relying party trusts to confirm they are configured correctly. See Use sandbox mode for instructions.

Create relying party trusts in AD FS

Creating your file...

Create a relying party trust using Windows PowerShell

Create a relying party trust by importing federation metadata

Create a relying party trust manually