This document containins specific information about configuring an ADFS 2.0 server federation trust against Visma Proceedo as the Relying Partner (RP).
Details on setting up ADFS on a Windows Server is available on http://www.microsoft.com/downloads/en/details.aspx?FamilyID=B92EA722-0C30-4EA6-BD45-7E5934B870CF&displaylang=en and http://www.microsoft.com/downloads/en/details.aspx?familyid=062F7382-A82F-4428-9BBD-A103B9F27654&displaylang=en.
The configuration for the RP is essentially the same regardless of whether the admin chooses to deploy a single ADFS server setup or a server farm; details on setting up an ADFS server farm are available on http://social.technet.microsoft.com/wiki/contents/articles/adfs-2-0-high-availability-and-high-resiliency-walkthrough.aspx
Before beginning setup of a federation trust with Visma Proceedo as the Relying Partner (RP) the administrator should:
Agree with the Visma administrators on:
IDP name (also known as Customer Identifier) that the RP will use.
This will also need to be added as an extension to the claim sent to Visma.
The total length of the username+extension that is sent to Visma should not exceed 20 characters, this needs to be taken into account when choosing a customer identifier. This has reportedly been removed in later versions of Visma.
Path to your STS (your ADFS server) that the RP should use.
a local web address can be used if no external users need access.
If external users need access a public DNS name should be registered and used.
If a DNS alias is used instead of the real name of the server it must be registered as a DNS A-record (not a C-record alias) and a HOST\SERVERNAME and a HOST\SERVERNAME.DOMAIN.COM should be registered on the ADFS computer account‘s name (or service account if a server farm setup has been used) using the SETSPN utility.
The SSL web certificate used should match whatever DNS name is used for the server.
Format of user names that your STS (ADFS server) will send to the Proceedo server.
The users‘ SAM account names (the value stored in the sAMAccountName attribute of each user) *must* match exactly the name that the Proceedo servers have for each user – this is case sensitive.
User names that are sent to Visma should preferably be based on an export from Active Directory to ensure an exact match.
The public key of the ADFS Token Signing certificate that is being used on your STS.
This needs to be exported to a Base64-encoded .cer file and sent to Visma – it is simplest to do this within the ADFS console itself and the Service\Certificates\Token-signing node.
It is recommended to use the self-signed certificate that ADFS installs during the setup as this enables ADFS 2.0 features like automatic certificate rollover when the old certificate expires.
Note that the end-user is never exposed to the token signing certificate as all traffic within the SSL tunnel will be encrypted by the SSL certificate that is specified on the Service Communications node.
Figure 1: exporting the Token-signing certificatethat you will send to Visma.
Setting up the federation trust.
Setting up the initial federation trust with the Visma Proceedo RP can be done by choosing the ´Import data from the relying party from a file‘ option and specifying the XML file below for import within the ADFS Add Relying Party Trust wizard – the secure hash algorithm needs to be specified as SHA-1 afterwards as Visma requires SHA-1 for the federation trust.
Once the Relying party trust has been created – the admin should run the following Powershell commands within a Powershell:
Set-ADFSRelyingPartyTrust –TargetName ”www.proceedo.net” –NotBeforeSkew 5
The first command loads the ADFS powershell tools (if not loaded already) and the second command configures a time skew of 5 minutes for the www.proceedo.net RP trust.
Figure 2: Federation Trust properties after import from XML file and required changes.
Adding Claim Rules to the RP trust
Four custom claim rules need to be added to the Visma Proceedo RP trust. If your chosen identifier happens to match the extension you are using for the UPN of the user it is possible to use 3 rules and simply send the eduPersonPrincipalName attribute in the SAML token based on the contents of the UPN in AD.
However, in this document we assume that the customer identifier is different and needs to be added to the username afterwards.
The total length of the username+extension that is sent to Visma should not exceed 20 characters, this needs to be taken into account when choosing a customer identifier.
Figure 3: Edit Claim Rules
Figure 4: create per session identifier
Visma requires a per session identifier to be created using a custom rule – the contents of Figure 4 are in the text file below and should be modified to replace contoso.com with your domain name.
Figure 5: create transient name identifier
Visma requires a transient name identifier to be created using a custom rule – the contents of Figure 5 are in the text file below and should preferably be modified to replace contoso.com with your externally exposed DNS domain name (the name used for „Type“ is simply an internal placeholder that just needs to match in all claim references for your RP).
Figure 6: constructing eduPersonPrincipalName
Visma expects the username of the user to be sent as an attribute named eduPersonPrincipalName, as this attribute doesn‘t exist in AD it needs to be constructed and populated with the contents of the sAMAccountName attribute in AD.
The contents of Figure 6 are in the text file below.
Figure 7: adding identifying extension to eduPersonPrincipalName
Visma requires an identifying extension to be added to the eduPersonPrincipalName attribute before it is sent.
The contents of Figure 5 are in the text file below and should be modified to replace @contoso with the identifying extension you agreed upon with Visma at the start of the start.
Testing the setup
Testing the setup of the ADFS server itself can be done by browsing to https:// /adfs/ls/idpinitiatedsignon.aspx.
Once the trust is set up, the admin should be able to browse to https://www.proceedo.net/weblogic/samlRequest?idp=identifyingextension (replacing identifyingextension with the identifying extension agreed upon with Proceedo earlier).
If the trust is set up correctly you should be redirected back to your own STS (ADFS server) which issues you a SAML token and redirects you back to the Proceedo servers.
If logon to the Proceedo server via ADFS has succeeded you should reach the webpage http://www.proceedo.net/index.html?ssologin=true
If you are not redirected from your STS to Visma then you need to look closer at the configuration on it or at the configuration of the client your testing this from. Testing from several different clients would be advisable.
If you are redirected to the Visma server but get an error message after the redirection you need to contact Visma for details about what the exact error is as the error message that is displayed does not give any details about what the nature of the error is.
The web page of your ADFS server should be added to the Local Internet sites zone within IE in order for SSO against it to function.
The user names in AD need to match the user names that Visma has on file in order for signon to be allowed (this is case sensitive).
Cookies need to be enabled within the browser for SAML tokens to work, at a minimum for both the Proceedo servers (www.proceedo.net) and for your ADFS server.