This guide outlines the configuration of a Azure AD SAML Application to accept authentication requests from an AAF Rapid Identity Provider (Rapid IdP) service. In this mode of operation, the Rapid IdP service provides access to federation enabled services and proxies all user authentication requests to an organisation's Azure AD service. 

 

The article is specific to Azure AD, as a discrete task that integrates an Azure AD Origin Identity Provider, during one of the following activities:

  • deployment of a new Rapid IdP instance 

  • migrating an existing identity provider to the Rapid IdP service

  • converting an existing Rapid IdP service from LDAP authentication to a cloud-based Origin Identity Provider.

These three activities follow a similar pattern and are outlined in the article On-premise IdP Migration to Rapid IdP.


For situations where an existing Rapid IdP service is converted from LDAP authentication to a cloud-based Origin Identity Provider, testing before go-live is not possible. 

This is where the Test instance of an organisation's Rapid IdP service must be fully tested, evaluated and the configuration finalised before configuration of the Production instance is deployed.


This guide is one in a series for connecting and proxying cloud based authentication to AAF's Rapid IdP Service. These guides cover Google, Okta and Azure AD.


The AAF will provide the necessary information to start the configuration of the Azure AD SAML Application Service. The AAF will need to receive the Azure AD SAML Application metadata and certificate to complete the configuration of the Rapid IdP service. 

 

In proxying authentication requests to a third-party authentication service, like Azure AD, Rapid IdP no longer requires access to an organisation's on premise LDAP service for authentication or to source user attribute values. However, the necessary user attribute values must be available within the Origin Identity Provider authentication service for Rapid IdP to retrieve and release user attributes to those federation connected services to which users authenticate.


The following instructions are derived from the following Microsoft Support document:

https://docs.microsoft.com/en-au/azure/active-directory/saas-apps/saml-toolkit-tutorial


Before starting configuration of the Azure AD SAML Application, the AAF will provide the following configuration information to the customer's technical staff:

  • an Identifier (Entity ID) URI - which exactly matches the Shibboleth IdP EntityID when migrating an existing service

  • the Reply URL - also known as ACS (Assertion Consumer Service) - this value is the Sign on URL

  • a list of SAML attribute names which Rapid IdP is expecting - attribute names are case-sensitive

  • a certificate for assertion signing, if the Azure AD Portal allows the import of an external certificate to the SAML application.


Step 1 - Assess Existing User Attributes

The customer's technical staff, working with a selection of test users, should collect user's attributes release reports  from the AAF's Validator services and inspect user attributes release values for validity. The pre and post-migration attribute dumps should be compared to ensure no change in the key attributes released during the migration. 

Production Federation https://validator.aaf.edu.au/

Test Federation: https://validator.test.aaf.edu.au/

Step 2 - Sign into the Azure AD Admin Portal

Access the Azure AD Admin Portal and select Azure Active Directory.



Step 3 - Select Enterprise Applications

Select Enterprise applications from the menu on the left.



Step 4 - Select the New application link

Select the New application link and search for the Azure AD SAML Toolkit.



 


Step 5 - Name the Application

Clear labelling of the application is necessary if the same Azure AD service is connected to both AAF Production and Test Federations. For Test Federation AAF Rapid IdP-Test is sufficient. For Production Federation AAF Rapid IdP-Prod is suitable. End users will not see this name since all requests to the login service will be by Service Provider initiated logins. Click the Create button at the bottom of the window and the Properties window will appear for the newly created SAML application.



Step 6 - Configure Properties - Assign Users and Groups

The assignment of users, groups or roles to the SAML application is dependent on the customer's Azure AD configuration and should include those users who require access to the new SAML application.


Step 7 - Configure Properties - Single sign-on

SAML2 integration requires the combination of information from both the customer's organisation and the AAF. For help completing the configuration, use your app-specific documentation, the Azure Portal tool tips and consult with the AAF. Select configuration option Sign Sign-on and then select the SAML Sign-on method to display the configuration page.



Single Sign-on requires the configuration of the Basic SAML Configuration page using the AAF supplied values for:

  • Identifier (Entity ID), 

  • Reply URL (Assertion Consumer Service URL) and 

  • Sign on URL



Step 8 - Configure Properties - Attributes & Claims 

Using the AAF supplied list of attribute names, configure the mapping of AAF attributes to Azure AD user attributes. Depending on the customer's Azure AD configuration, missing attributes should be added to Azure AD and populated with the necessary user values. 


The choice of mapping the contents of Azure AD extensionattributes to various on-premise attributes is left to the organisation's discretion. The following is only an example:

user.extensionattribute1 contains the person's persistent non-reassignable identifier,
user.extensionattribute3 contains the person's studentID, if available, 
user.extensionattribute4 contains the person's organisation affiliation (ie: staff, student, alumni, etc)
user.extensionattribute5 contains the person's entitlements if available

Administrators may add and populate the the following attribute names to Azure AD (to match AAF attribute names) to more closely match the AAF attribute names:

  • dsdStudentID
  • eduPersonAffiliation
  • eduPersonEntitlement


Attribute names released to Rapid IdP are case-sensitive, administrators need to ensure that claim attribute names match the AAF provided attribute names (left highlight column below illustrates an example configuration). 




The Unique User Identifier (Name ID) Claim should reference a persistent user attribute and the format for the claim should be of type persistent.


 


All other claims should be configure with a Name format of Unspecified. 



Unnecessary or superfluous claims should be removed.

Federation Attributes

Complete documentation on AAF Attributes is available here: https://validator.aaf.edu.au/documentation.

AAF Core Attributes are the standard vocabulary for the federation and the higher education and research sector.


To assist with the mapping of Azure AD values to AAF attributes, explore the AAF attribute definitions to gain an understanding of their purpose and usage. The selection of Azure AD attributes should be such that they align closely to the AAF attribute descriptions. Organisations are only required to support the attributes in the core list.


Of the core attributes, the following are consumed without modification by the Rapid IdP service:

  • mail

  • givenName

  • surname

  • displayName (this can be a direct mapping to an existing Azure AD attribute or Rapid IdP can generate the value by combining firstName and Surname values)

  • eduPersonAffiliation - can be defined statically within Rapid IdP, if all users have the same affiliation status within an organisation, otherwise the customer must calculate and assign values to each user from the defined vocabulary

  • eduPersonEntitlement - if no values are assigned within Azure AD, this attribute may be defined statically within Rapid IdP with the default value of urn:mace:dir:entitlement:common-lib-terms.


The following attributes are generated by the Rapid IdP service from a single persistent, non-reassignable, unique identifier provided by an organisation:

  • auEduPersonSharedToken

  • eduPersonTargetedID

  • persistentNameID

Sources of persistent, non-reassignable, unique (for an organisation) identifiers commonly include: employeeID, studentID, unix uidnumber or other identity management system internal identifier that is sticky to the individual throughout their entire identity lifecycle with an organisation, including when an individual leaves and returns to an organisation after any period of time away. 

When there is no suitable attribute, the AAF will make recommendations on a case-by-case basis in consultation with an organisation, for deploying an immutable identifier for every user. Unique values for this identifier will need to be available for every user. The process of adding values for this attribute should become part of an organisation's identity management process and documented accordingly.

The following attributes are generated by the Rapid IdP service based on the available values for other identifiers mapped to the Azure AD App attributes:

  • eduPersonPrincipalName (combines uid or a suitable immutable persistent identifier and homeOrganization as a scoped attribute)

  • eduPersonScopedAffiliation (combines eduPersonAffiliation and homeOrganization as an scoped attribute )

 

The following attributes are generated by the Rapid IdP service at the time of user authentication:

  • authenticationMethod

  • eduPersonAssurance

 

The following attributes are defined statically:

  • homeOrganization (this is the organisation's security domain, ie: example.edu.au)

  • homeOrganizationType

  • ‘O’ - aka: organizationName.

Step 9 - SAML Signing Certificate

The customer must downloads the Azure AD Federation Metadata XML. This XML file must be provided to the AAF. The AAF uses the provided Federation Metadata when configuring the Rapid IdP service to receive and trust requests from the Azure AD SAML Application. This metadata will include the Azure AD SAML application certificate for signing tokens issued to Rapid Idp. 


It should be noted that the max age on the default certificate is typically two years. Administrators should note the expiry date to replace this certificate. Alternatively, consider creating and uploading a new PFX file with RSA encryption with a longer expiry period (beyond the scope of this article) to replace the default certificate before downloading and providing the Federation Metadata XML file to the AAF.


The Federation Metadata XML can be downloaded in option 3 from the download link.


The configuration items referenced in option 4, for configuring an application to redirect to Azure AD, are already included in the Federation Metadata XML provided.


Option 5 for testing of Single Sign-on is not necessary - all Testing of the service occurs outside the Azure AD Portal.


Step 10 - Rapid IdP Service Deployed

At this step the Rapid IdP becomes active and becomes available for testing in the following scenarios before being made available to an organisation's users.

  • deployment of a new Rapid IdP instance 

  • migrating an existing identity provider to the Rapid IdP service


For situations where an existing Rapid IdP service is converted from LDAP authentication (or a different cloud-based Origin Identity Provider) to a cloud-based Origin Identity Provider, testing before go-live is not possible. This is where the Test instance of an organisation's Rapid IdP service must be fully tested, evaluated and the configuration finalised before configuration of the Production instance is deployed.


Step 11 - Test Functionality

Repeat Step 1 with the same selection of test users and compare the new reports with the pre-migration attribute reports. Raise all discrepancies with the AAF for review and possible configuration changes. 


Step 12 - Configure Token Encryption

This step adds the AAF public certificate for the Rapid Idp service to the Azure AD SAML application for signing assertions sent to the Rapid Idp service. From the menu on the left select Token encryption (see Figure for Step 5). These are long lived certificates.


From the information provided by the AAF, extract the certificate (all text between and including 

“-----BEGIN CERTIFICATE-----“ and “-----END CERTIFICATE-----“) to a file. Upload the certificate file using the import functionality. Once imported, “activate Token encryption certificate” from the item's menu on the right.


 


Step 13 - Re-Test Functionality to Confirm Assertion Signing

Similar to Step 1, however only a few users need to complete re-testing to confirm access with SAML assertion signing enabled.


Links

These instructions were derived from the following Microsoft documentation

https://docs.microsoft.com/en-au/azure/active-directory/saas-apps/saml-toolkit-tutorial

AAF Test Validator https://validator.test.aaf.edu.au/

AAF Production Validator https://validator.aaf.edu.au/