Informing the identity provider 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 identity provider can populate the username field automatically. Therefore, removing the need for the user to re-enter their username once they are redirected to the identity provider.
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.
Therefore, 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 will need to 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 query string parameter (e.g., "login_hint"). This is outside the SAML specification; hence, we don't support it out-of-the-box. You will need to edit the request URL yourself before it's sent to the IdP. We recommend rewriting the URL using the app.Use method in ASP.NET Core.
Note that if you are signing authentication requests, adding an additional parameter to the query string will invalidate the signature, resulting in request validation failure at the identity provider. In this case, we recommend using HTTP POST binding if possible, as it doesn't have the same concerns. If you are having trouble, please contact our support.
Validating Received Subject
We recommend validating the subject returned by the identity provider in a callback method. An example callback method can be found 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
}