/Saml2/SSO/Callback returns 404

[barryw-securesave]

I've upgraded to v8 in preparation for configuring my IdentityServer instance as an SP connected to an external IdP using SAML. While testing, I'm finding that the /Saml2/SSO/Callback url returns 404 after a redirect from the ACS url. Have I missed a bit of configuration? Currently on v8..0.10 for all packages. Saml is being enabled via default AddSaml(), though I've also tried by explicitly setting Endpoints.SingleSignonCallbackPath.

[wcabus]

Hi @barryw-securesave,

It looks like the wrong SAML role is being used. Duende IdentityServer can act both as an SAML IDP or SP in v8:

• When IdentityServer needs to be an Identity Provider (IDP), then you need to use AddSaml() when configuring IdentityServer.
• When IdentityServer acts as a Service Provider (SP), then you should register an authentication handler using either AddSamlServiceProvider() on AddAuthentication() or configure a dynamic SAML provider when dynamic providers are used.

The /Saml2/SSO/Callback endpoint is part of the SAML IDP flow: this is where your login page returns to finish an incoming SAML request from a Service Provider. This endpoint is not meant to receive responses from external IDPs, which explains what you're experiencing.

Configuring IdentityServer as a Service Provider

Instead of adding AddSaml() to your IdentityServer builder, try setting up the SAML authentication handler:

builder.Services.AddIdentityServer(...);

builder.Services.AddAuthentication()
    .AddSamlServiceProvider("external-saml-idp", options =>
    {
        options.SpEntityId = "https://your-identityserver";
        options.IdpEntityId = "https://external-idp";
        options.SingleSignOnServiceUrl = "https://external-idp/saml/sso";
        options.SigningCertificateBase64 = ["base64-encoded signing certificate from the IDP"];

        // SP-Initiated SSO will redirect to /ExternalLogin/Callback, so we need to 
        // store the SAML ClaimsPrincipal using the temporary external cookie scheme:
        options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
    });

The SAML service provider serves its endpoints under the configured ModulePath which defaults to /Saml2. You may need to update the external IDP with the correct ACS url.

If IdentityServer needs to act as both an SP and IDP, then you may want to use a different ModulePath, as the IDP side will also use /Saml2 as the root SAML path.

Optional: enabling IDP-Initiated SSO

Identity Providers can also start the login process on their end, called IDP-Initiated SSO. If your external IDP requires this, update the authentication handler configuration:

builder.Services.AddAuthentication()
    .AddSamlServiceProvider("external-saml-idp", options =>
    {
        options.SpEntityId = "https://your-identityserver";
        options.IdpEntityId = "https://external-idp";
        options.SingleSignOnServiceUrl = "https://external-idp/saml/sso";
        options.SigningCertificateBase64 = ["base64-encoded signing certificate from the IDP"];
        options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
        
        // Enable IDP-initiated SSO
        options.AllowUnsolicitedAuthnResponse = true;

        // Redirect to the external login callback handler for IDP-Initiated SSO flows
        options.IdpInitiatedCallbackUrl = "/ExternalLogin/Callback";
    });

The IDP may send a relayState which you can retrieve from AuthenticationProperties.Items["relayState"]. Treat the relayState as untrusted input and validate it before redirecting the user anywhere based on the information in the relay state.

Hope this helps! Let us know how it goes.