To ensure broad compatibility with commonly used SAML identity providers, SAFIRE’s federation hub can adjust its behaviour to handle specific quirks in some implementations. This is mainly intended for proprietary SAML software stacks that do not fully support our deployment profiles. It is not a substitute for correcting misconfigurations.

Quirks are signalled in identity provider metadata by setting the x-safire.ac.za:quirks EntityAttribute as follows:

<mdattr:EntityAttributes>
  <saml:Attribute FriendlyName="quirks" Name="urn:x-safire.ac.za:quirks" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml:AttributeValue>quirk1</saml:AttributeValue>
    <saml:AttributeValue>quirk2</saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>

Note that is is only supported for identity providers that are directly registered in SAFIRE.

This documentation will guide you through the Microsoft Entra ID (Azure AD) configuration process as an authentication source in SimpleSAMLphp. By integrating Entra ID in this way, you can retain your users’ familiar login experience while leveraging SimpleSAMLphp’s flexibility to fetch and/or manipulate attributes from Entra ID and other sources.

While SAFIRE can directly work with Entra ID or SimpleSAMLphp (as explained in our Configuring Entra ID SAML-based SSO for SAFIRE and Configuring SimpleSAMLphp for SAFIRE documentation), you may find yourself in a situation where this approach better fits your use case.

Microsoft does not recommend deploying new instances of AD FS. Instead, they encourage you to consider Entra ID (formerly Azure AD). This raises a common question: can you migrate an existing SAFIRE identity provider from AD FS to Entra ID?

Unfortunately, the answer is not straightforward. This document outlines the main challenges, along with some approaches you might consider.

No direct migration path

In Entra ID, SAML identity providers are configured as “Enterprise Applications”. However, the cloud SAML provider does not offer feature parity with AD FS and has some fundamental limitations. We’ve previously documented how to integrate Entra ID with SAFIRE for a new identity provider and highlighted some of the caveats.

While it is possible to connect Microsoft Entra ID directly into SAFIRE, this has several caveats you need to be aware of. To help you make an informed decision, the info boxes in this document highlight some of the things you need to consider. Read through it carefully before starting your implementation.

Microsoft recommends integrating Entra ID into SAFIRE via a SAML Proxy such as Shibboleth, which mirror’s the R&E federation communty’s guidence. (Some SAFIRE providers opt to use SimpleSAMLphp for this instead.) Doing this avoids many of the caveats highlighted below.

Types of certificates

SAML installations typically use at least two¹ different certificates: one of the public facing portions of a website, and one to establish a private trust relationship between providers. Whilst it is possible to use the same certificate for these two roles, this is not best practice nor is it recommended.

This theme generator has been updated for SimpleSAMLphp 2.0.x

A number of people seem to find SimpleSAMLphp’s theming system intimidating. To aid with this, we’ve written a simple theme generator for SimpleSAMLphp.

The generator takes SSP’s stock templates and massages them to include some branding – amongst other things, a logo on the top left of the page and corporate colours in the header bar.

The generator is a bash script, and is available here. It takes a number of command line options which can be used to manipulate the resulting theme:

SimpleSAMLphp has good documentation, and so this is not a complete/worked example of how to configure it. Instead this provides the SAFIRE-specific snippets you may need when working through that documentation.

Configuring metarefresh to fetch SAFIRE metadata

You should use the metarefresh and cron modules to manage SAFIRE’s metadata automatically. SimpleSAMLphp provides documentation on automated metadata management which explains the basics of how you set this up. This document assumes you have a working cron module and have installed and enabled metarefresh.

This is a recipe for rolling over (changing) your SAML signing certificate and the associated private key without a service affecting outage.

NB! You should be aware that this process is NOT instantaneous, and requires proper planning to ensure your users can continue using your provider without incident. Therefore, you need to begin the process well before the expiry of your existing SAML signing certificate (plan for at least a week). If you let your certificate expire, your users may not be able to log in, and it will take some time to recover from this.

Microsoft does not recommend deploying new instances of AD FS. Instead they encourage you to consider Entra ID. Information on using Entra ID with 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:

As a result of the baseline changes that occured in march 2021, it is no longer possible to directly integrate Google Workspace (G Suite) with SAFIRE without making schema changes. In particular, you would need to add support for the displayName and eduPersonScopedAffiliation attributes. As no current providers use Google Workspace, his document has not been updated to incorporate information on how to do that, nor has it been tested. It remains theoretically possible to integrate Google Workspace.