Configuring ADFS for SAFIRE

Note: While it is possible to use ADFS with SAFIRE, it has known interoperatability problems with the sort of multi-party federation used in the R&E world. SAFIRE’s architecture shields you from some of these effects, but you do sacrifice some flexibility and control.

In order to configure Active Directory Federation Services (ADFS) as an identity provider for SAFIRE, you need to do four things:

  1. Create a Relying Party Trust that fetches the federation hub’s metadata from https://metadata.safire.ac.za/safire-hub-metadata.xml
  2. Configure claim rules to map AD LDAP attributes to SAFIRE’s attributes
  3. Configure a claim rule to generate eduPersonAffiliation from some internal role mapping
  4. Configure a claim rule to generate a transient NameID and then map this internal claim as a Name ID of type urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Scripted configuration

Ensure you make adequate backups before executing any script from this site

You can use PowerShell to configure ADFS, and there is a sample add-safire-relyingparty.ps1 script to automatically add SAFIRE as a relying party.

This script needs one piece of information from you — your primary DNS domain name, which will be used to configure scopes on those attributes that require it. It can be specified as -idpScope or you will be prompted for it.

The script creates a Claim Issuance Policy that generates as many of SAFIRE’s attributes as possible from the default AD schema, including all the recommended attributes. If you have other values in your AD that map to other SAFIRE attributes, you should consider adding those mappings to.

Without knowing about your internal structure, it is impossible for the script to generate a complete eduPersonAffiliation. If you look through the script, you will find a  “Transform Group to eduPersonAffiliation” rule that adds all members of the Domain Users group as members of your organisation (case 5). This rule can be expanded or adapted to better fit your situation (cf case 2). For instance, the “Domain Users” group can be changed to one that better fits your environment. Likewise, you may have groups that reflect the other values in the eduPersonAffiliation vocabulary.

Note the script does not handle the certificate considerations

Claim Descriptions

Whilst not strictly necessary, you can also add user-friendly claim descriptions to the new claims we’ve created. This makes them display better in the AD FS Management interface.

The following PowerShell snippet adds a claim description for the eduPersonPrincipalName attribute:

if ("urn:oid:1.3.6.1.4.1.5923.1.1.1.6" -notin @(Get-AdfsClaimDescription | foreach { $_.ClaimType }))
{
    Add-AdfsClaimDescription -ClaimType "urn:oid:1.3.6.1.4.1.5923.1.1.1.6" `
      -Name "eduPerson Principal Name" `
      -IsAccepted:$true `
      -IsOffered:$true `
      -IsRequired:$false `
      -Notes "A scoped identifier for a person. It should be represented in the form 'user@scope' where 'user' is a name-based identifier for the person and where 'scope' defines a local security domain. Each value of 'scope' defines a namespace within which the assigned identifiers MUST be unique. Given this rule, if two eduPersonPrincipalName (ePPN) values are the same at a given point in time, they refer to the same person. There must be one and only one '@' sign in valid values of eduPersonPrincipalName."
}

An example claim-descriptions.ps1 PowerShell script that adds descriptions for all of SAFIRE’s attributes is available to help you with this.

Certificate considerations

Microsoft refers to the certificates used in SAML as “token signing certificates”. By default AD FS is configured to generate token signing certificates automatically, and to renew them annually.

Unfortunately certificate roll-over in an multi-party federation is non-trivial (it doesn’t work like a web server), and we generally recommend that long-lived certificates are used. This can be achieved in AD FS by changing the CertificateDuration parameter.

The supplied PowerShell does not do this for you, since that may affect other trust relationships you have in AD FS. However, you can do this from an elevated PowerShell session as follows:

# Set certificate validty to ten years to match SAFIRE recommendations
Set-AdfsProperties -CertificateDuration "3652"
# Issue a new certificate
# NB: this will immediately roll over your existing certificate - do not do this if your certificate is in production
Update-AdfsCertificate -CertificateType Token-Signing –Urgent

AD FS also uses a second “token encryption” certificate to encrypt assertions. Doing this is not recommended as the attributes are already protected by the HTTPS transport, and additional encryption makes debugging harder. The supplied PowerShell disables this, and you can disable encryption manually by looking on the Encryption tab of the SAFIRE Relying Party in ADFS and removing the certificate for encryption.

Improving generated metadata

By default, ADFS publishes its generated metadata at a well-known URL of:

  • https://your-adfs-server.example.ac.za/FederationMetadata/2007-06/FederationMetadata.xml

You can use this to obtain the copy of metadata you need to supply to SAFIRE. However, but default the auto-generated metadata does not include many of the required elements.

You can improve the generated metadata (and thus require less editing) by providing ADFS with some information about your organisation. To do this, open AD FS Management, select the service and then click on Edit Federation Service…. In the resulting properties dialogue, complete the organisational information on the Organization tab and check the Publish organization information in federation metadata checkbox.

Note that you’ll still need to add your contacts and some of the MDUI elements (such as your logo URL and privacy statement) by hand before sending your metadata to SAFIRE. We’re not aware of any way to get ADFS to add these automatically.

Other technical requirements

There are two additional technical requirements that the supplied PowerShell script does not configure.

Logging requirements

By default, Windows rotates the event log based on size whereas the technical requirements specify a minimum retention period. Thus it is possible that you will delete logs earlier than you’re supposed to. You will need to adjust the event logging properties for your server to ensure you retain logs as specified in the technical requirements.

You should change your Log retention policy to “Archive the log when full, do not overwrite events.” and set a suitable maximum log size to ensure you retain the full period required. You may need to make sure you’ve allocated sufficient disk space for logging to store this.

Time synchronisation

Modern versions of Windows server do syncronise time, but this may be changed by your local group policy. Please ensure your server is set to synchronise time against a reliable timesource (such as za.pool.ntp.org).

Multi-factor authentication

To enable support multi-factor authentication for your users, you may need to alter your claim issuance policy and add a rule to pass the Authentication Methods References claim. You will also need to explicitly confirm that the authentication methods you’ve enabled are compatible with academic federation. See authnmethodsreferences for details.

South African Identity Federation