Add optional domain hint to help skip the Microsoft Azure / EntraID account picker

[pmeulen]

Providing a realm (domain) hint along with a SAML 2.0 AuthnRequest to a Microsoft Enterprise Azure connection can help prevent the account picker from showing up in many occasion.

This was developed and tested in OpenConext/Stepup-AzureMFA#213

https://learn.microsoft.com/en-us/answers/questions/855476/domain-hint-alternative-for-saml describes two methods of doing this that should be equivalent. Note that this is not an official feature that is described in the Azure online documentation, but it appears to work reliably, and the post is from a Microsoft moderator. A limitation is that only one domain can be provided in a domain hint.

Option 1: Adding Scoping element to the AuthnRequest with an IDPList IDPEntry that contains the realm:

<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="iddeb9381bc15e4fd6a253b97205d47c6f" Version="2.0" IssueInstant="2015-02-26T18:57:06.4772751Z" IsPassive="false" AssertionConsumerServiceURL="https://www.authnauthz.com/saml/inboundauthnresponse" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">  
     <saml:Issuer>https://www.authnauthz.com</saml:Issuer>  
          <samlp:Scoping>  
               <samlp:IDPList>  
                    <samlp:IDPEntry ProviderID="https://example.com" Name=”example.com”/>  
               </samlp:IDPList>  
          </samlp:Scoping>  
</samlp:AuthnRequest>

Option 2: Adding a whr query parameter with the scope as value to the HTTP GET request to Azure's SAML Single Sign On Location.

Example SAML AuthnRequest using the HTTP-Redirect Binding (i.e. a HTTP GET) where coin:azure_domain_hint is set to hartingcollege.nl:

GET https://login.microsoftonline.com/12345678-abcd-1234-abcd-1234567890ab/saml2?SAMLRequest=lZHNbsIwEITvfYrI98QhLbRYBESLqiJRFUHooZfKmAUsJWvq3SAev0loBCek3vw3M59nB6NTkQdH8GQdpqITxSIANG5jcZeKVfYaPonR8G5AusgPalzyHhfwUwJxUAmRVHORitKjcposKdQFkGKjluP3mUqiWB28Y2dcLq4ktxWaCDxXRCKYTlLx3UnuH7q9x6d%2BrNdmA1sRfLbESU08JSphisQauTqKk24Y98O4m8V9lfRUJ%2FkSwaRitqi5Ue2ZD6SkzN3OYlRY4x25LTvMLUJkXCHbyLBODOvdZdWiyPoniQjGLe6LQyoL8EvwR2tgtZhdogB3tTeVfmscwokjzKWuCgVkaxouSQdpzhbhVQXzv%2F6eLZ7Hcqu69fkRqbcsm4fzj2Umhs30VFOSH%2F6TpwDWG816IK9NfgE%3D</samlp:RequestedAuthnContext></samlp:AuthnRequest>
&whr=hartingcollege.nl HTTP/1.1

The above PR uses this second method and it seems to work well.

implementation

• Use the whr query parameter (option 1) because this is the simplest to implement.
• Add a coin:azure_domain_hint configuration option (string) to Manage.
• Allow engine to receive this coin:azure_domain_hint in a push from manage.
• When coin:azure_domain_hint set for an IdP, the value is used as domain hint in the AuthnRequest that engine sends to the IdP (Azure). If coin:azure_domain_hint is not set for an IdP the extra parameter is not added. This allows per IdP configuration of this option and ensures IdPs other than Azure cannot be affected.