Login Hints

Informing the identity provider (IdP) of who you would like to authenticate can influence the user login experience. For example, if you send the username as a login hint, the IdP can populate the username field automatically. Therefore, removing the need for the user to re-enter their username once they are redirected to the IdP.

For this purpose, the SAML protocol defines an optional property called Subject that can be sent in an authentication request. The Subject property specifies information, such as the NameId, of the user you would like to authenticate. Hence, the Subject property can be treated the same as OpenID Connect's login_hint parameter.

Adding Subject to Authentication Requests

By default, our component will exclude Subject from authentication requests. To include the Subject in an authentication request, you must set the Subject option on SAML challenge properties (SamlChallengeProperties). You can read more about the SAML challenge properties at Overriding Options Per Request.

HttpContext.ChallengeAsync("saml-idp", new SamlChallengeProperties
{
    Subject = new Saml2Subject(new Saml2NameIdentifier("bob_123", new Uri("urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified")))
});

Custom Request Parameter

Some identity providers, such as Microsoft Azure, do not support the Subject element in authentication requests. Instead, they require the login hint to be sent as a custom query string parameter, such as "login_hint". This is outside the SAML specification; hence, we don't support it out of the box. Please contact support for more details.

Validating Received Subject

We recommend validating the subject returned by the IdP in a callback method. You can find an example callback method in the IdentityServer Quickstart. Using this approach, you can validate the returned subject using custom logic.

var result = await HttpContext.AuthenticateAsync("saml-idp");
var nameId = result.Principal.Claims.FirstOrDefault(x => x.Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" || x.Type == "sub");
if (nameId != "bob_123")
{
    // handle mismatch
}