Overview

These instructions describe the steps necessary to integrate the Application Portal with your instance of Microsoft's Active Directory Federation Services (ADFS).

ADFS SUPPORT MATRIX

Prerequisites

ACTIVE DIRECTORY AND ADFS

This document assumes that your Active Directory instance is already generally available and that it simply needs additional configuration to integrate with the Application Portal. It is important to note that the Application Portal only supports SP-Initiated single sign-on.

Installing ADFS and configuring it to synchronize with or federate to your on-premise identity management systems (e.g. traditional Active Directory) is not within the scope of this document.

ACTIVE DIRECTORY ADMINISTRATOR ACCESS

The integration procedure requires involvement from an existing, authorized user within your Active Directory instance that has the necessary administrative permissions to configure ADFS.

CONGA LOGIN ADMINISTRATOR SECURITY GROUP

As a part of setting up the Application Portal to integrate with your ADFS instance, the Application Portal requires at least one Active Directory security group to represent those users who shall be granted administrative rights to the Application Portal. The selected security group(s) may already exist and need not be specific to Conga, for instance, if you have an existing group that represents its security/domain administrators; however, some organizations may wish to create a separate security group specific to the Conga integration. This document does not cover how to create a new group, or how to add a user to such a group. These actions are performed directly in the Active Directory instance (or other back-end user management system).

To ensure that the user performing the initial configuration has and retains access to administrative functions within the Application Portal, the user must select the administrative group(s) from one or more of his/her own group memberships. This means that the initial configuration user must already be an existing member of at least one of the desired administrator security groups.

ADFS Required Information

For the integration, you will need to get the:

• Entity ID
• Single Sign-On Service URL
• Single Logout Service URL
• Token Signing Certificate.

Please go to FederationMetadata.xml to get this information. You can retrieve it by downloading the XML file from https://hostname/FederationMetadata/2007-06/FederationMetadata.xml.

Detailed steps are shown below. Note that the screenshot is taken from ADFS v3; the steps are the same for any version.

Entity ID from "entityID" attribute.

<EntityDescriptor ID="_747a86da-0595-413c-b6bc-a43f2c2d40b2" entityID="http://adfs.contoso.com/adfs/services/trust"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata">

• SingleSignOnService URL from "SingleSignOnService" in IDPSSODescriptor with "HTTP-POST" binding. In the example, it is "https://adfs.contoso.com/adfs/ls/".

  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
  <KeyDescriptor use="encryption">
  ...
  </KeyDescriptor>
  <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://adfs.contoso.com/adfs/ls/" />
  <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  Location="https://adfs.contoso.com/adfs/ls/" />

  <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
  <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
  <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
  <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://adfs.contoso.com/adfs/ls/"/>
  <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://adfs.contoso.com/adfs/ls/" />
  </IDPSSODescriptor>

• SingleLogoutService URL from "SingleLogoutService" in IDPSSODescriptor with "HTTP-POST" binding. In the example, it is "https://adfs.contoso.com/adfs/ls/".

  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
  <KeyDescriptor use="encryption">
  ...
  </KeyDescriptor>
  <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://adfs.contoso.com/adfs/ls/" />
  <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  Location="https://adfs.contoso.com/adfs/ls/" />
  ...
  </IDPSSODescriptor>

• Token Signing Certificate in PEM format

Follow these steps to export the Token Signing Certificate, applicable to ADFS 2.0, 3.0 and 4.0:

1. Log into the Identity Provider Server and click on Administrative Tools > ADFS 2.0

   Management. The ADFS 2.0 window will be displayed.

2. Click Services to open the Service Snap-in. The available Services will be displayed.
3. Click on Certificates in the Services Snap-in. The Certificates pane will be displayed with the available Certificates.
4. Select the Certificate under Token-Signing in the Certificates Pane. The Certificate folder will be displayed.
   
   
5. Click on the Copy to File option in the Details tab of the Certificate window. The Certificate Export Wizard will be launched.
   
   
6. Click Next in the Welcome to the Certificate Export Wizard window. The Export Private Key Page will be displayed.
7. Check No do not export private key option on this page. This will ensure that only the ‘Public Key’ gets exported.
8. Click Next to proceed further. You will be prompted to choose the file format in which the certificate is to be exported.
9. Select the Base64 encoded X.509 (.CER) option and click Next. You will be prompted to select the location where the file is to be saved.
10. Select a location where the token signing certificate is to be saved. You will now need to specify a file name to identify the token signing certificate that is being exported.
11. Specify an appropriate file name, verify that the file type is Base 64 Encoded (.cer) and click Save. The Certificate Export Wizard window will display the File Name and location specified. Verify the file path specified.
12. Click Next to proceed with exporting the Token Signing Certificate. The Certificate will be exported to the location specified. The Certificate Export Wizard window will be displayed with a message "The export was successful".
13. Click OK and then Finish to exit the Certificate Export Wizard.
14. Treat the Entry ID, SingleSignOnService URL, and SingleLogoutService URL as highly sensitive data. Store the information securely.
15. Save the file (Token signing certificate) in PEM format securely too.

The information above will be used to configure the Application Portal once ADFS configuration is complete.

Configure ADFS

ADD A RELYING PARTY TRUST

The relying party trust maintains the relationship between the federation service and the Application Portal, so we need to add relying party trust to get that relationship, please see the following Microsoft page for more information: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust.

To add a new relying party trust by using the ADFS Management snap-in and manually configure the settings, perform the following procedure on a federation server.

Membership in Administrators, or equivalent, on the local computer is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups.

The example displayed is from ADFS 3.0, but it is similar for ADFS 2.0 and 4.0.

1. In Server Manager, click Tools, and then select AD FS Management.
2. Under Trust Relationships > Relying Party Trusts, right-click Add Relying Party Trust.
3. On the Select Data Source page, click Import data about the relying from a file.
   1. Download the XML file metadata from the appropriate location.

   CONGA CLOUD REALM	APPLICATION PORTAL URL
   US REALM 1	https://login.us1s1.congacloud.com/x/adfs-saml2/metadata
   US1 Preview	https://login.us0s1.congacloud.com/x/adfs-saml2/metadata
   EU1	https://login.eu1s1.congacloud.com/x/adfs-saml2/metadata
   EU1 Preview	https://login.eu0s1.congacloud.com/x/adfs-saml2/metadata
   AU REALM 1	https://login.au1s1.congacloud.com/x/adfs-saml2/metadata
   EU1 Subrealm	https://login.eu1s2.congacloud.com/x/adfs-saml2/metadata
   US1 Subrealm	https://login.us1s2.congacloud.com/x/adfs-saml2/metadata

4. Enter the Federation metadata file location = xml file in the appropriate box.

   CONGA CLOUD REALM	APPLICATION PORTAL URL
   US REALM 1	https://login.us1s1.congacloud.com/x/adfs-saml2/metadata
   US Preview	https://login.us0s1.congacloud.com/x/adfs-saml2/metadata
   EU1	https://login.eu1s1.congacloud.com/x/adfs-saml2/metadata
   EU Preview	https://login.eu0s1.congacloud.com/x/adfs-saml2/metadata
   AU REALM 1	https://login.au1s1.congacloud.com/x/adfs-saml2/metadata
   E1 EU1	https://login.eu1s2.congacloud.com/x/adfs-saml2/metadata
   US REALM 2	https://login.us1s2.congacloud.com/x/adfs-saml2/metadata

5. On the Specify Display Name page, type a name in Display name, under Notes type a description for this relying party trust, and then click Next.
   
   
6. On the Configure Multi-factor Authentication Now?, click Next.
7. On the Choose Access Control Policy select Permit all users to access this relaying party and click Next. For more information about Access Control Policies, see Access Control Policies in AD FS.
8. On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
9. On the Finish page, click Close.
10. Now the new Relying Party should be displayed on middle pane.

ADD ISSUANCE TRANSFORM RULES

1. Select the new Relying Party Trust in the middle pane and click Edit Claim Rules on Actions pane.
   
   
2. Click Add Rule
3. On Choose Rule Type step, select Send LDAP Attributes as Claims on Claim rule template and click Next.
   
   
4. On Configure Claim Rule, enter the following information:
   1. Specify a claim rule name.
   2. Attribute store = Active Directory.
   3. Mapping of LDAP attributes to outgoing claim types:
      
      

• For the LDAP Attribute, add a row clicking on the list box and select Surname and Surname for the Outgoing Claim Type.
• For the LDAP Attribute, add a row clicking on the list box and select Given-Name and Given Name for the Outgoing Claim Type.
• For the LDAP Attribute, add a row clicking on the list box and select Display-Name and Name for the Outgoing Claim Type.
• For the LDAP Attribute, add a row clicking on the list box and select E-Mail-Address and E-Mail Address for the Outgoing Claim Type.
• For the LDAP Attribute, add a row typing on the list box objectGUID and type objectGUID for the Outgoing Claim Type.
• For the LDAP Attribute, add a row by clicking on the list box and select Token-Groups - Qualified by Domain Name and Group for Outgoing Claim Type. (See Below)
  
  
  1. Click Finish to dismiss the window. Click Apply to apply the changes.
  2. Add a transform rule. Click Add Rule...
     
     
• On Choose Rule Type step, select Transform an Incoming Claim on Claim rule template and click Next.
  
  
  1. Specify a claim rule name.
  2. For 'Incoming claim type:', type in objectGUID.
  3. For 'Outgoing claim type:': select Name ID.
  4. For 'Outgoing name ID format:', select Persistent Identifier.
  5. Select Pass through all claim values.
  6. Click Finish.
  7. Click OK to complete rules.

Configure the Application Portal

The next step is to setup the Application Portal with the details from your Identity Provider. You may have already received an e-mail invite that provides you access to the Conga Platform, in which case you can refer back to the guide in order to complete the integration steps in the Application Portal.

If you've received a setup link from your Conga implementation specialist, proceed to the steps documented in the following guide: Integrate the First Identity Provider.

If you're lacking an e-mail invite or setup link, contact Conga Support for assistance.

Test Integration

Please follow the steps documented in the following guide: Test IdP Integration