Integrating AD FS

This documentation is a detailed guide for setting up single sign-on (SSO) through Active Directory Federation Services (AD FS) leveraging SAML 2.0.

You do not need to configure both OIDC and SAML applications for your integration. Depending on your organization's infrastructure and preferences, you can choose either OIDC or SAML.

The following procedures require copying and pasting information between AD FS and the Delinea Platform. We recommend opening both applications before you begin, and keeping both open until you are finished.

Prerequisites

On the Delinea Platform, you need to be an Admin with federation privileges.

Setting Up AD FS with SAML

Retrieve AD FS metadata

1. Connect to your AD FS server using the following URL:
   https://{FQDN}/FederationMetadata/2007-06/FederationMetadata.xml

Note: If your metadata file is not available at the URL above, open your AD FS management console, and under AD FS > Service > Endpoints, ensure that the Federation Metadata endpoint is enabled.

2. Save the FederationMetadata.xml file to a known location.

If your metadata file is not available at this URL, open your AD FS management console, and under AD FS > Service > Endpoints, ensure that the Federation Metadata endpoint is enabled.

Add the Provider to the platform

1. Log on to the platform.

2. Click Settings from the left navigation menu and select Federation providers.

3. On the Federation Providers page, click Add Provider and select SAML from the drop-down menu.

4. On the Add Provider page next to SAML provider configuration, click Select file.

5. Find and select the AD FS metadata file you downloaded, then click Upload SAML configuration.

6. On the SAML Provider Settings page, click Edit to update the data that was auto-generated from metadata.

7. Update the Name field with a meaningful name.

8. Optionally, select the Enabled box next to Status.

9. In the Advanced Settings section:

   1. Select the box next to Customize Issuer Sent To IDP (you can leave the field as is, but the option must be enabled).

   2. Select the box next to Sign Request.

   3. Next to Request signing certificate, click Select file.

   4. Browse to and select a valid pfx file.

   5. Enter your pfx password in the Password field.

10. In the Domains section, add one or more domains that should be managed by this SAML provider.

11. Click Save.

Initial AD FS Setup

1. Open the AD FS Management console.

2. From the left tree view, select Relying Party Trusts.
   

3. From the right panel, click Add Relying Party Trust...
   

4. Select Claims aware.
   
   

5. Click Start.

6. Select Import data about the relying party from a file.

7. Click Browse to select the xml file you downloaded from the platform.

8. Click Next.
   
   

9. Enter a meaningful Display name.
   

10. Click Next.

11. Choose an access control policy such as Permit Everyone, and click Next.
    

12. On the Ready to Add Trust screen, click Next.

13. Ensure that the box is selected next to Configure claims issuance policy for this application.

14. Click Finish.

Configure assertion attributes

1. Right click the newly created Relying Party Trust, and click Edit Claim Issuance Policy.
   

2. From the Claim Issuance Policy editor, click Add Rule.

3. Select Send LDAP attributes as Claims.

4. Click Next.

5. Enter a meaningful rule name (e.g. Delinea Platform Claims).

6. For Attribute Store, select Active Directory (or any LDAP server you may use).

7. Map attributes from your directory to the claim names expected by the platform.
   
   By default, the platform expects the following claims:

   • sub: nameidentifier. The user's unique identifier.

   • upn: upn. User Principal Name. The user account logon name.

   • email: EmailAddress. The user's email address.

   • displayname: Name. The user's name for display purposes (optional, but recommended).

   Attribute Mappings

   You can add or modify expected claims from the platform federation settings, under Attribute Mappings.

   If you want to leverage the group mapping feature and give different permissions to the authenticated user based on the user's groups, you can also add a groups claim or similar and map it to the Token Groups - Unqualified Names AD attribute. From the platform, go into your Federation settings and configure Group Mappings.

8. Below is an example that grants Delinea Platform admin rights to any user belonging to the PAM-ADMIN group:
   

9. Click OK, then click OK again.

Add the Provider to the Platform

1. Log on to the platform.

2. Click Settings from the left navigation menu and select Federation providers.

3. On the Federation Providers page, click Add Provider and select SAML from the drop-down menu. The Add Provider page opens.
   

Settings

In the Settings section, the first fields are automatically populated when you select the SAML provider configuration file and click Apply.

1. Next to SAML provider configuration, click Select file.

2. Find and select the AD FS metadata file you downloaded.

3. Click Upload SAML configuration. The word, Apply appears above the right end of the SAML provider configuration field.then

4. Click Apply. The words Uploaded successfully will appear next to SAML provider configuration, and the empty fields below will be auto-populated:

   • Name: Auto-generated from metadata

   • Protocol: SAML (auto-filled)

   • Status: Disabled

   • Entity ID [example: https://sts.windows.net/808444af-4011-40d5-9b0a-a9a5c95f88e9/]

   • IDP Certificate: Click Select File, then navigate to and select the Signing Certificate file you downloaded, to populate the following fields:

     • Signature

     • Algorithm

     • Thumbprint

     • Not valid before

     • Not valid after

     • Issuer

5. IDP Login URL: Paste in the Login URL from your new IdP SAML application.

6. IDP Logout URL: Paste in the Logout URL from new IdP SAML application.

7. Platform Callback URL: https://[HOST-NAME].delinea.app/identity-federation/saml/assertion-consumer Copy the Platform Callback URL to paste into the appropriate field in your new IdP SAML application.

8. Platform Logout URL: https://[HOST-NAME].delinea.app/identity-federation/saml/logout-consumer

9. Status: Select the box next to Enabled.

Advanced Settings

1. Select the box next to Customize Issuer Sent To IDP (you can leave the field as is, but the option must be enabled).

2. Select the box next to Sign Request.

3. Next to Request signing certificate, click Select file.

4. Browse to and select a valid pfx file.

5. Enter your pfx password in the Password field.

Also see Advanced Settings (SAML only) under Federation Management.

Attribute Mappings

See Attribute Mappings under Federation Management.

Group Mappings

See Group Mapping under Federation Management.

User Mappings

See User Mappings under Federation Management.

Domains

1. Click Add Domain and enter the domain from the email addresses of the users you are including in this federation.

2. Optionally enable the Status of the provider.

3. When all required fields are populated, click Add Provider.