Tuesday, 14 July 2020

Microsoft Azure Active Directory & SAML Direct Federation - making it work.

( Note: this was written on 14/7/20, I expect Microsoft will fix the issues listed here at some point)



Most companies that use Microsoft Azure use it for the bulk of their needs, including identity management through Azure Active Directory.

What if Azure is only a small part of your larger IT estate, or you use a central identity service like Okta as your IdP? It's best practice to manage identities in one place, and most corporates that I've helped use some sort of Identity Federation to make this happen.

If you've found this post, then likely you're interested in SAML based Direct Federation, as described in this Microsoft document here:


This allows external IdP domains that use SAML or WS-Fed to be invited into an Azure AD, while the user identity and credentials remain the responsibility of the external IdP.
This kind of configuration is very commonly used with AWS, and on AWS it's very well understood and pretty bullet-proof.

At this point, you'll probably go ahead, follow the Microsoft documentation, and find out it doesn't work!

( To be fair, at the time this post was written, Microsoft listed the feature as a "Preview")

Computer says no


The setup from the Azure side is straightforward, as per the Microsoft docs.

If you follow the docs for the IdP side, you will likely end up with an error like...

AADSTS5000819: SAML Assertion is invalid. Email address claim is missing or does not match domain from an external realm.
 ... when trying to accept the invitation sent to the Federated guest user from Azure.

Configuring the IdP

I was using Google GSuite as the SAML IdP here, and had multiple support calls with both Microsoft and Google about the problems.

Unfortunately, some of the details in that Microsoft document are either incorrect or written in a confusing way. As of the date of this blog post, here's what you need to make this work on the IdP side.

ACS Url: "https://login.microsoftonline.com/<Azure-tenant-ID>/saml2"

Entity ID: "urn:federation:MicrosoftOnline"

Attribute: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

...mapped to user's primary email address ( the domain that was referenced in the Azure side "external identities" setup )

Your tenant ID is a UUID that can be found on your Azure AD overview page.

At this point, thing will start looking a little better.

When the user clicks the link to accept the invite, they will be redirected to IdP sign-in, then hopefully back to an Azure page.

If they click any of the links on that Azure page, they will likely be directed back to an Azure login page which won't understand who they are  :-(

Oh so close - How to access Azure portal.


The central part of the Azure portal does not understand Federated Identities.

In order to access your Azure portal, specify the Azure tenant ID as part of the portal URL.

eg. https://portal.azure.com/<tenant-id>

While the redirect from the user invite does seem to work, the redirection from the portal page to the IdP does not seem to. This means the user login workflow is always.

  1. Click on the invitiation link in Azure email
  2. Authenticate
  3. Go to the correct https://portal.azure.com/<tenant-id> address

It's not exactly elegant, but it does seem to work.

CLI/API access


Web UIs are nice for poking around, but everyone uses CLI/API access with their favourite Infrastructure-as-code tool for any serious work, right?

The "az" cli suffers from a similar problem, luckily it's easier to rectify.

az login -t <tenant-id>


  1. Thank you so much for the correction on the ACS and the attribute!!!
    Would have never figured it out by myself.

  2. Thanks so much for posting this blog - this helped me a lot too. My issue (I had the same SAML error you posted) was that I had the wrong ACS URL - so I changed mine to use the pattern you mentioned.

    But I wasnt clear on how to apply the the Attribute you called out, so for those who may be reading this, to clarify the last point, go to your google app SAML Attribute Mapping section, and map the "Primary email" field with the value of "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" and this fixed the issue for me.

  3. Thanks for this write-up. The Microsoft documentation is still out of date. I recently setup using Google as IdP to Azure AD using these steps.

  4. You guys are heroes. As of today the documentation is still not up to date. The info above, including that from Mark, is needed to get this working properly. Thanks guys!