Setup ADFS

Print
This article describes how to setup an SSO connection between Connexys and an ADFS. It consists of a number of steps.
 
The first step involves exchanging and importing each others 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 organisation as an identity provider and you have to setup a relying party trust for Connexys in ADFS. At last 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. Connexys delivers certificates in PEM format. These certificates must be imported in 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 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 Connexys 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 behaviour of identity claims with the claim rule language. See how the spnamequalifier 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 offers 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 login only to ADFS or Login 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 Connexys.
Have more questions? Submit a request

Comments