Azure AD Authentication

With Azure AD authentication an organisation can configure users with specific domains for authentication with SWITCH edu-ID when accessing Microsoft Online Services.

When entering the Email for login, the domain is analysed and, according to the settings of the organisation owning this domain, the user authenticates either against the Azure AD or is redirected to an external login page, in this case the SWITCH edu-ID login page. The organisation can manage the domains in their tenant each separately, allowing for example to authenticate only a subset of their domains via edu-ID. See Azure AD subdomain authentication for information about federated authentication for a subdomain only, while the parent domain is still set on managed authentication.

Authentication Flow

  1. A user wants to access an Azure AD resource (i.e. Office365).
  2. The user must use as username an email address of the organization that owns the tenant.
  3. Based on the domain part of the username, the tenant is selected and the user is redirected to the edu-ID IdP for authentication
  4. The user authenticates with any edu-ID supported authentication mechanism, and is then redirected to the desired resource. The attributes ImmutableID and UserPrincipalName are passed to the resource to identify the user.

Service Description

With the chosen solution architecture using SAML Proxies, it is possible to let users authenticate via SWITCH edu-ID for Microsoft Online Services. In addition, also multiple domains can be configured to be eventually redirected to the same IdP, which Microsoft by default has no mechanism for. For a user who needs her edu-ID on a nearly daily basis to access different services, logging in via the edu-ID is a standard process and thanks to Single Sign On (SSO), she might already be authenticated and doesn’t even need to enter her credentials again.

SWITCH offers a straightforward guidance for the changeover to the federated authentication with edu-ID, providing ready-to-use commands for the configuration in the Powershell.

What the Organisation Needs to do

There are some prerequisites for an an organisation in order to let (some of) their domains being authenticated via SWITCH edu-ID.

  • This service is only available for organisations who have already integrated SWITCH edu-ID.
  • All Azure AD enabled accounts must have been provisioned in the Azure AD tenant beforehand. This can be accomplished with Azure AD Connect, Graph API, Powershell or other means.
  • The two attributes ImmutableID and UserPrincipalName must have been provisioned in the SWITCH edu-ID accounts of all users, as those must be provided when the user authenticates (see below for details).

When this prerequisites are met, the last step is to adjust the authentication settings for the specific domain(s) via Powershell, such that users having a username with this domain are correctly redirected. This step is guided by SWITCH, providing a set of commands to safely accomplish the changeover.

Attribute Synchronisation Prerequisites

The following two attributes need to be provided by an organisation (Attribute Provider) either via Push (Affiliation API) or Pull (Attribute Provider API) for each Azure AD enabled user account.

Attribute Name Value Comments
extAzureADImmutableID ImmutableID matching the user object in Azure AD For organisations using AD and Azure AD Connect:
The values must be those that Azure AD Connect uses as sourceAnchor. By default, Azure AD Connect stores these values in the Active Directory attribute „ms-DS-ConsistencyGuid“. In this case, the ImmutableID is the base64 encoded value of „ms-DS-ConsistencyGuid“.

For organisations not using AD/Azure AD Connect:
The organisations must create suitable values for each Azure AD enabled account and store these values appropriately in their identity management system or user directory (e.g. OpenLDAP). The values must be supplied as part of the affiliations synchronised to the SWITCH edu-ID. Furthermore, the organiations must synchronise these values with their Azure AD tenant in a suitable way (e.g. via the Graph API or using PowerShell). (The synchronisation to Azure AD is not part of the SWITCH edu-ID service.)

The value must be provided in the format as the PowerShell command „get-msoluser“ returns the attribute „ImmutableID“.

Additional information: Azure AD Connect: Design concepts
userPrincipalname UserPrincipalName matching the user object in Azure AD For organisations using AD:
These values can directly be taken from the Active Directory attribute „userPrincipalName“.

For organisations not using AD:
Since the „UserPrincipalName“ values should correspond to the users' e-mail-addresses per convention, organisations can usually directly use the users' existing primary e-mail addresses as values. Alternatively, they can store the „UserPrincipalname“ as separate attribute in their identity management system or user directory (e.g. OpenLDAP), which might be an advantage in certain cases.

Additional information: Active Directory User-Principal-Name attribute


These attributes are supported by the following SWITCH edu-ID components:

  • Affiliation API: The Affiliation API supports these two attributes in the SCIM scheme with the names extAzureADImmutableID and userPrincipalName.
  • Attribute Provider API: An implementation of the Attribute Provider API must provide these two attributes with the names extAzureADImmutableID and userPrincipalname.

Setting up the Service

If your organisation already uses SWITCH edu-ID and you want to set authentication for Microsoft Online Services for one or more domains to proceed via edu-ID, contact us via email to discuss further steps. If you meet the prerequisites, SWITCH will prepare the service and a first test for the changeover can be done within short time.

After successful testing, the service is ready for permanent use.

Technical Details

The Service runs via SAML proxies, which also allow to authenticate multiple domains via the same IdP. Each domain for which an organisation sets the authentication to Federated gets a SAML Proxy redirecting the requests to the edu-ID IdP. The Proxy itself is a Shibboleth IdP, using the authn/SAML flow - introduced with version 4 - to only act as SAML Proxy and use another IdP (here, the edu-ID IdP) for authentication. In this way, each domain is configured to be redirected to a different IdP (namely the respective proxy), but authentication is eventually performed on the same IdP for all of them.


Each proxy consists of two instances, running in docker containers on different machines. In front of them, there is a Load Balancer which ensures the traffic is evenly divided and in case of outage of one instance, only the healthy one is used.

Speaking of healthiness, SWITCH monitors the proxies, regularly doing automated health checks with alerting when failing, and extracting various metrics and Logs in order to keep track of their status.