Example of Configuring Microsoft Active Directory Federation Services 3.0 to Connect to Software AG Cloud as the SAML Identity Provider

[Sreejesh_Pulukool]

This article describes how Active Directory Federation Services 3.0 can be configured as a SAML based External-Identity provider that can authenticate Software AG Cloud users. Software AG Cloud supports only Service Provider Initiated SSO.

Submitted by: Sreejesh Pulukool, Software AG, January 2020

Applicable From: January 2020.

Basic Preparation for Configuring Software AG Cloud and AD FS

1. Install and deploy Microsoft  Active Directory Federation Services (AD FS). The following link provides all the information you need to deploy ADFS:

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/windows-server-2012-ad-fs-deployment-guide

1. Log on to AD FS as a user with Administrator privileges.
2. Assign Software AG Cloud roles to Active Directory users.
   1. For each Software AG Cloud role, create an Active Directory user group, and make note of the relationship between the two for later use.
      You might want to use an easily identifiable naming convention for the groups (for example, SAG_Cloud_super_admin), so you can easily filter the Software AG related user groups.
   2. Add the Active Directory users to the appropriate new Active Directory group.

Software AG Cloud Configuration for Microsoft Active Directory Federation Directory Services Connection

1. In your browser’s address bar, type the following URL to download the AD FS federation metadata URL:

https://<host_name>/FederationMetadata/2007-06/FederationMetadata.xml

<host_name> is the host name where you installed AD FS.

Note: Alternatively, make note of the URL for use when adding an identity provider in AD FS.

1. Log on to Software AG Cloud as a user with Administrator privileges.
2. Navigate to Administration > Single sign-on.

1. Add the identity provider with all the necessary identity provider details, keeping in mind the following:

• The Identity provider configuration selection allows one of these three options:
  • Import configuration from URL: If you did not download the federationmetadata.xml file in step 4, then you can now use the following URL for Software AG Cloud to directly download the federationmetadata.xml file.

https://<host_name>/FederationMetadata/2007-06/FederationMetadata.xml

• Import configuration from file: If you downloaded federationmetadata.xml file in step 4, provide the location where you saved the file.

When you click Next, the SAML basic and advanced settings attributes are set automatically as described for the option Import configuration from URL.

• Create configuration from scratch: If you choose this option, do the following:

1. In Single sign-on service URL, open the federationmetadata.xml file and use the value in the fed:PassiveRequestorEndpoint tag.
2. Click Next and set the SAML basic and advanced settings attributes manually.

1. Unlike for the other options, here you can:
   • Modify the default setting for Assertions signed
   • Add the Validating X509 certificates from the value in the X509Certificate tag in the federationmetadata.xml file.

• Make note of the user attributes as you will need to use the exact user attributes configured in Software AG Cloud for configurations in AD FS. Email, First name, and Last name are minimum attributes required, but you can add other attributes as well.
• Software AG Cloud provides two ways in which you can assign roles:
  • Assign default Software AG Cloud roles to users option assigns the default Software AG Cloud user roles to all AD FS users.
  • Assign Software AG Cloud roles to users by mapping to identity provider roles option allows you to map Software AG Cloud user roles to AD FS user groups that you created in step 3. Software AG recommends that you use this option.

1. When the identity provider you created appears click on the name and navigate to the SAML advanced settings page.
2. Note down the value of Service Provider Descriptor. Alternatively, you could open the URL in the browser and save the content to an XML file, for example, myCloudDescriptor.xml.

Your Software AG Cloud configuration for AD FS is complete. The SAML advanced setting attributes in the Software AG Cloud configuration affects the following in AD FS:

• Assertions Signed is selected by default in AD FS and does not require any change.
• The Service Provider Descriptor includes the Software AG Cloud certificate. When you import this descriptor into AD FS, Assertions Encrypted and Validate Signature are automatically populated in AD FS.

Configuring Microsoft Active Directory Federation Services

1. Log on to AD FS as a user with Administrator privileges and configure the Relying party and claim rules.

Configuring Microsoft Active Directory Federation Services for setting relying party and claim rules.

1. From Server Manager, access Tools > AD FS Management.

1. In Trust relationships > Relying Party Trusts, add a new relying party trust.

1. In Select data source, select Import data about the relying party from a file and upload the myCloudDescriptor.xml file.

1. Specify a display name for the relying party trust and follow the wizard to adjust the settings where appropriate. Here, we use only the default settings.
2. Under the relying party trust, click Edit Claim Rules.

Set a minimum of Name ID, email, first name and last name claims. If you opted for dynamic role selection (that is, the Assign Software AG Cloud roles to users by mapping to identity provider roles option) in Software AG Cloud, the roles claim is also required for dynamic role allocation to log in users, create groups, and allocate users in Active Directory. 

1. Set the Name ID.

1. Click Add Rule and, in the Add Transform Claim Rule window, select the Transform an incoming claim rule type.
2. Set Claim rule name as “Name ID.”
3. Set Incoming claim type as the Windows account name.
4. Set Outgoing claim type as “Name ID” from the list.
5. Set Outgoing Name ID format as the Windows qualified domain name.
6. Click OK.

1. Set the user attributes as configured in Software AG Cloud.

Here we have assumed the Software AG Cloud user attributes as “email,” “firstName,” and “lastName”.

Email

1. Click Add Rule and, in the Add Transform Claim Rule window, select Send LDAP Attribute as Claim.
2. Set Claim rule name as “email.”
3. Select Attribute Store to Active Directory.
4. In LDAP Attribute, select E-Mail-Address.
5. In Outgoing claim type, type “email.”
6. Click OK.

First Name

1. Click Add Rule and, in the Add Transform Claim Rule window, select Send LDAP Attribute as Claim.
2. Set Claim rule name as “firstName.”
3. Select Attribute Store to Active Directory.
4. In LDAP Attribute, select Given Name.
5. In Outgoing claim type, type “firstName.”
6. Click OK.

Last Name

1. Click Add Rule and, in the Add Transform Claim Rule window, select Send LDAP Attribute as Claim.
2. Set Claim rule name as “lastName.”
3. Select Attribute Store to Active Directory.
4. In LDAP Attribute, select Surname.
5. In Outgoing claim type, type “lastName.”
6. Click OK.

Role

1. Click Add Rule and, in the Add Transform Claim Rule window, select Send Claims Using a Custom Rule.
2. Set Claim rule name as “roles.”
3. In Custom Rule, place the following:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]

 => issue(store = "Active Directory", types = ("roles"), query = ";tokenGroups;{0}", param = c.Value);

Here:

• C is the condition and issue is the roles selected. Values can be queried using different filters.
• issue section types value of types must be roles.

1. Click OK.

Example of the final user attributes in AD FS

Your AD FS configuration is complete. Now, when users access the Software AG Cloud login page, a link appears for AD FS, which will route users to a page where they need to provide their AD FS credentials.