Setup ADFS

Steps

This article describes how to set up an SSO connection between FastForward and an ADFS. It consists of a number of steps.

The first step involves exchanging and importing each other's signing and encryption certificates. After that, we both have to complete the circle of trust configuration in our federation products. On our side, we have to configure your organization as an identity provider and you have to set up a relying party trust for Bullhorn in ADFS. Finally, we have to create one or more test users on both sides, so we can test if everything works as expected. I will try to explain all this in more detail below.

Import certificates

If there is a requirement that all data between the Identity Provider and Service Provider is signed and encrypted (and there usually is), then both parties must generate certificates for signing and encryption. Usually, the certificates on the customer's side are automatically generated by the ADFS installation process. On our side, we have to create them manually. Bullhorn delivers certificates in PEM format. These certificates must be imported into the certificate store on your ADFS server(s). Because we use self-signed certificates, at least in our test environment, these certificates also must be added to the Trusted Root Certification Authorities store.

Export certificates

Now the customer needs to export the Microsoft ADFS server certificates (without the private key) and send them to us, so we can import them in our certificate stores. To export the ADFS certificates launch the ADFS 2.0 Management Tool. In the ADFS2.0 | Service | Certificates screen, you will find all the required certificates in one place. For each of the three certificates, double-click to open the Certificates window. Click on the Details tab and then click on the Copy to File button. This will start the export wizard. Click ‘No do not export private key’ and select the ‘DER Encoded X.509 (.cer)’ encoding.

Configure the Active Directory Federation Server

In order to configure the Circle of Trust in ADFS, you need to add a Relying Party Trust via the ADFS 2.0 Management tool. There are 3 ways to create a Relying Party Trust. One of them is importing the metadata XML file that Connexys will provide. However, ADFS lets you use a federation URL to obtain the metadata dynamically. If you prefer the last method then select the first option and use the following URL: https://app-a.connexys/nl/openam/saml2/jsp/exportmetadata.jsp?spentitityid=http://sso-a.connexys.nl/saml2/<customer>&realm=customers/<customer>

After importing the metadata please review the following properties:

  • On the Encryption Tab, please verify that the sso_client_te Certificate is selected.
  • On the Signature Tab, please verify that the sso_client_ts Certificate is selected.
  • On the Advanced Tab, please make sure that the SHA256 algorithm is selected.

After creating the Relying Party Trust you also need to create the claim rules to define what information you are allowing to be sent over to us as the trusted party (we need to discuss and agree on this). By default, we use the Windows Account Name to be sent over to the relying party (us). In order to do this, you need to create two Claim rules in the Edit Claim Rules wizard.
First, you need to create a generic LDAP rule where you have to map the internal Active Directory LDAP attributes to Claim Types.

In our ADFS test environment, Bullhorn will the sAMAccountName to the outgoing claim type UPN.

The second rule is very custom. Although ADFS allows you to create Claim Rules via a Wizard and also create ‘Transform Claim Rules’ where you can easily transform incoming claims and assign different attributes into it, it does not work for our product (OpenAM) yet, mainly because ADFS expects a spname qualifier to be present in the request which OpenAM currently is not sending (new version does!). Therefore you need to create a custom rule. ADFS 2.0 (or later) provides the option to define custom rules that can be used to determine the behavior of identity claims with the claim rule language. See how the spname qualifier attribute is added to the Claim request in the following rule:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer,
Value = c.Value, ValueType = c.ValueType,
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
= "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"]
= "http://adfs.customer.com/adfs/services/trust",
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"]
= https://sso-a.connexys.nl/saml2/customer);

You can import the aforementioned rule, for now, so we can test the single sign-on. These rules can of course be customized should the need arise later on in the project.

Test the single sign-on

Before testing the single sign-on we need to make sure that the test user does exist in both ADFS as well as in our user store.

ADFS offers various authentication methods, such as Forms authentication, which will always offer a user/password screen, but it also offers IWA (Integrated Windows Authentication) to authenticate internally. If you would navigate directly to the IDPInitiatedLogin.aspx page you will have the opportunity to log in only to ADFS or log in to ADFS and redirect directly to one of the configured Service Provider Trusts. There is also a way to skip the Sign-In page and go directly to one of the configured service providers by providing the service provider as a query parameter: That is the method that we will use eventually to initiate the SSO. The following should automatically log you in into ADFS and into Connexys if everything is configured correctly: https://adfs.customer.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=http://app-a.connexys.nl/saml2/customer

If you have any questions while setting everything up, please do not hesitate to contact us.