Which IdentityServers do you support?
What version of the package should I use?
- I am a SAML Service Provider: I want to allow users to log in using an external SAML Identity Provider:
- Use Rsk.Saml
- I am a SAML Identity Provider: I want to allow users in external systems to log in using my user store:
- I am using IdentityServer4 v4
- Use Rsk.Saml.IdentityServer4
- I am using Duende IdentityServer
- Use Rsk.Saml.DuendeIdentityServer
If you are using an older version of IdentityServer4, v3 or v2, you will need to use the older versions of our libraries:
- Rsk.Saml v3.*
- Rsk.IdentityServer4.Saml v3.*
- Rsk.IdentityServer4.Saml.EntityFramework v3.*
Can the Rsk.Saml component be integrated with a .NET Framework application?
Our SAML component only supports ASP.NET Core applications. This means that you cannot use our component directly inside your .NET Framework application.
However, if your .NET Framework application uses IdentityServer for sign-in, you can use our component to federate with an external SAML identity provider. This is because all the SAML interactions would occur in the IdentityServer codebase.
Do you have any samples available?
We have a GitHub repo with a number of different use cases.
Can I see your source code?
Rock Solid Knowledge's SAML component is closed source, and it is a violation of our EULA to decompile our source code. However, our source code can be purchased. For pricing, please contact email@example.com.
How can I view a SAML message?
See our Troubleshooting documentation.
How can I retrieve my metadata document?
If you are acting as the SAML Identity Provider, you can retrieve your metadata by visiting the path
If you are acting as the SAML Service Provider, you can retrieve your metadata by visiting the path configured in your
The default value for
MetadataPath configuration option is
Please be aware that if you are acting as both SAML Service Provider and SAML Identity Provider, you will have two separate metadata documents for both sides of the SAML protocol.
If you are integrating with multiple external identity providers, you will have a unique metadata path, and hence metadata document, per identity provider. You can read more on this in our Federating with Multiple External Providers documentation.
SAML signature is valid but uses untrusted key
When our component receives a signed SAML message, it will first validate the signature in the message using the key configured for the IdP or SP. If signature validation fails, it will attempt to validate the signature using the key embedded in the SAML message itself. If validation succeeds using the embedded key, the key is marked as untrusted and the overall validation will fail.
To resolve this, check that you have imported the correct public key from your partner's metadata file. If you are using the correct key, then you will need to contact your partner to find out why they are advertising the wrong key in their metadata file.
How do I map between IdentityServer and SAML Claims?
See our IdP Claims Mapping and Assertion Attributes documentation.
When acting as a Service Provider, you can provision additional claims that may be needed by using a callback method, which is triggered after authentication. Check out the external controller in this sample.
IssueInstant too old to trust or IssueInstant is in the future
To account for differences in server times or other factors, the options class contains a setting called
TimeComparisonTolerance. This setting will allow a SAML message's IssueInstant validation to succeed if the time is still within range of the additional tolerance. Microsoft uses a default setting of 300 seconds, but we recommend using the lowest possible value.
Unrecognized SAML service provider - cannot find Client/SP configuration
When acting as an Identity Provider, each Service Provider requires an IdentityServer Client object and a matching Service Provider object.
The Client's ClientId must match the EntityId of the Service Provider and vice versa.
Client is not configured for SAML2P
The IdentityServer Client object is not configured for SAML. The
ProtocolType of the Client must be "saml2p". The constant
IdentityServerConstants.ProtocolTypes.Saml2p can also be used.
Unable to determine correct ACS endpoint
The component cannot find a corresponding Assertion Consumer Service (ACS) endpoint on the
ServiceProvider object for the request. Ensure that the
AssertionConumserServices collection contains an endpoint of the correct binding, location and index for the request. The Service Provider metadata should provide details for all its ACS Endpoints that need to be configured.
How do I use SAML in a mobile app or SPA?
We do not recommend using SAML directly in your mobile application or Single Page Application (SPA). Since SAML was not designed for these public application types, you may experience compatibility and security issues.
We recommend using OpenID Connect in mobile applications and SPAs. This protocol was designed with these application types in mind and works alongside OAuth, allowing for API authorization.
Using an OpenID Provider such as IdentityServer4, you can use both OpenID Connect and our SAML component. This will allow you to authenticate users, no matter the type of requesting application, and/or support server-side applications that use SAML.
You can read more on this in our article Why You Wouldn’t Use SAML in a SPA and Mobile App.
What are requestId and logoutId?
The requestId and logoutId query string parameters are automatically included in the URL when the SAML login process errors or during user interaction at the SLO (logout) endpoint.
The request ID allows you to retrieve information about the current SAML request by passing it to the
ISamlInteractionService, such as the ID of the requesting application.
The logout ID allows you to complete single logout for the current session using
You can change the requestId query string key to something else by setting the
RequestIdParameter property on your
How do I change the NameId?
See our Configuring NameId documentation.
Invalid SAML message issuer
This error is thrown when there is a mismatch found between the configured EntityId of the partner Identity Provider (IdP) and the issuer specified in the SAML message sent by the IdP. Please check that the IdP EntityId specified in your
Saml2pAuthenticationOptions.IdentityProviderOptions configuration matches the EntityId specified in the IdP metadata.
If you are federating with multiple identity providers, the callback paths used for each IdP must be unique. Read more on this in our Federating With Multiple External Providers documentation.
IdP Metadata is Unsigned Error ("No signature element could be found in the metadata document's parent node")
Various elements in a metadata document can be digitally signed, as indicated by the element's inclusion of a
signature node. A digital signature is used to validate the integrity of the metadata document. A digital signature is optional and may not be present in the metadata document.
By default, our SAML component requires the metadata document to be digitally signed, and an error will be thrown if a signature node is missing. However, you can override this behavior by setting the option
RequireValidMetadataSignature to be false, which will allow signature validation errors to be ignored.
Missing SAML message destination
A SAML message can optionally contain a
destination attribute, which is a URI reference indicating the address to which the message has been sent. This is useful to prevent malicious forwarding of requests to unintended endpoints.
By default, our SAML component requires the
destination attribute to be present in SAML messages and will throw an error if it is missing; however, you can override this behavior by setting the option
RequireSamlMessageDestination to be false.
Invalid SAML message destination
A SAML message can contain the destination address to which the message has been sent. The incoming message validation will fail if the destination value does not match your configuration.
If you are acting as the SAML service provider, the authentication response message should be sent to your
AssertionConsumerService endpoint (
CallbackPath config option), and a logout request/response should be sent to your
SingleLogoutService endpoint (
SignedOutCallbackPath config option).
If you are acting as the SAML identity provider, the authentication request should be sent to your
SingleSignOnService endpoint (
/saml/sso), and a logout request/response should be sent to your
SingleLogoutService endpoint (
If your partner provider is sending an incorrect message destination, it may be that they have misconfigured your details on their end. We recommend sending them your metadata document and ensuring that they have your correct details.
If the difference in the destination value is HTTP vs HTTPS, check out the FAQ "My application is running on HTTPS, but the SAML component is seeing HTTP".
My application is running on HTTPS, but the SAML component is seeing HTTP
You may observe this issue through various errors, such as:
- The incoming message validation fails due to an invalid destination
- The generated metadata contains endpoints with HTTP instead of HTTPS
If you are running your SAML implementation behind a load balancer or a proxy, this issue is usually due to misconfiguration. It could be that the load balancer is not setting the Forwarded Headers, or your application is not listening to them properly.
We determine the application path using the
This means that our component will correctly use the path you have configured for your application.
We recommend checking the Microsoft documentation on configuring your ASP.NET Core application to work with proxy servers and load balancers.
SAMLResponse contains incorrect audience restriction
This error is thrown when the
AudienceRestriction value in the received assertion does not match your service provider Entity ID (unique identifier).
AudienceRestriction should exactly match the value you have specified in the configuration option
It may be that the Identity Provider has misconfigured your Entity ID on their end. We recommend sending them your metadata document and ensuring that they have your correct details.
If you are using Azure AD, please note that they prefix your entity ID with
spn: if your entity ID is not a URI.
We expect an exact string match to the entity ID value, as the SAML specification does not specify any prefixes.
This means that our SAML response validation will fail if there is an
spn: prefix in the
You can get around this issue by prefixing your Entity ID value (
ServiceProviderOptions.EntityId) to match the convention used by Azure AD.
SamlAssertion must have at least one statement
This error is thrown when there are no other attributes for the user except Name ID (unique identifier) in the SAML assertion.
If you are the identity provider generating the failing assertion, you can resolve this issue by adding some other claims for the user, such as family name, given name, and email. You should then start generating SAML tokens successfully.
If the user already has other claims, it may be that you have not configured the client to have access to the required scopes.
Please ensure that the client has access to the
profile scopes, as well as any other scopes that it requires.
Check out our Claims Mapping and Assertion Attributes documentation for more details.
If you are the service provider that is receiving the failing assertion, we recommend contacting your identity provider to add additional claims for the user.
Sign in request has expired
Our SAML service provider throws this error when the correlation cookie is not present or cannot be read.
The correlation cookie is used to remember information about the initial SAML request. When you issue a SAML request, the service provider creates a correlation cookie that contains information about the request, such as the request ID, relay state, and authentication properties. This cookie is consumed when the response is received.
There are a few reasons why the correlation cookie may not be present when the response is received:
- The login process at the identity provider took some time to complete, and your service provider no longer trusts it. We set the correlation cookie expiration to 15 minutes by default. Generally, 15 minutes is enough time to complete any extended 2-factor authentication that might be involved during a log-on process. However, you can change the expiration using the
- Browsers are taking the initiative to block third-party cookies. When affected by this, your browser will not attach the cookies to cross-origin requests. Check out our Same Site Cookie Changes documentation for more details.
- The correlation cookie may be overwritten. This usually happens during development if you run multiple instances of our service provider component on localhost, just on different ports. The cookie from one instance will be overwritten by the other. To resolve this, change the
If you are unable to resolve the error using the above fixes, we recommend doing some investigation to determine the lifetime of the cookie. When you start the SAML request, your application should create a correlation cookie, and the cookie should be present in the HTTP request when you receive the SAML response.
Sub claim is missing IdentityServer error
This error is thrown when you have IdentityServer acting as a SAML Service Provider, and IdentityServer cannot find the "sub" claim in the main authentication cookie. See our IdentityServer as a SAML SP documentation for the recommended solution.
User is not authenticated error during user authentication
Your IdentityServer thinks that the user is not authenticated, even though the user just logged in. This could be a cookie or user claim issue.
We use the IdentityServer IUserSession to get the currently authenticated user.
The default IdentityServer implementation authenticates using the cookie authentication scheme. It may be that your user is not signing into your default authentication scheme. Instead, they may be using a different scheme, or perhaps even an external scheme. We recommend ensuring that the user is signing in with the correct default sign-in scheme, and this should fix the error.
Otherwise, it could be a Same Site Cookie issue, where the browser is not attaching the authentication cookie to the HTTP request. If you are running locally over HTTP, changing over to HTTPS should fix the error. You can learn more about same site cookie issues from our SameSite Cookie documentation