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 v2: use Rsk.IdentityServer4.Saml v3.*
- I am using IdentityServer4 v3: use Rsk.IdentityServer4.Saml v3.*
- I am using IdentityServer4 v4: use Rsk.IdentityServer4.Saml v4.*
If you are an existing service provider, you can continue to use Rsk.IdentityServer4.Saml. However, you may miss out on new features that will only be published in the Rsk.Saml library.
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.
When validating a SAML response, I'm receiving the error "SAML signature is valid but uses untrusted key"
When our component receives a signed SAML message, it will first validate the signature in the request 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?
To map from Identity Claims to SAML claims, you can configure the
SamlClaimsMapping object. Claims mapping can be set up on a per Service Provider level on the
ServiceProvider object or at the global level on the options class.
You can find our default claim mappings in our options documentation.
The SAML component will use your IdentityServer's Profile Service to retrieve all the requested claims for a user and then map those OIDC claims types into SAML claim types. If you are not getting the claims you expect, check that the requesting Client has the correct requested scopes and that those scopes contain the desired claims.
When acting as a Service Provider you can provision additional claims that may be needed by using a callback method, this is triggered after authentication. Check out the external controller in this sample.
IssueInstant too old to trust
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.
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?
The name identifier format specifies the format of the name identifier to be used to represent the subject. The IdP
DefaultNameIdentifierFormat option allows to you set the default Name Identifier format. By default, this value is "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified". For example, if you wish to use email address as the NameId, you will need to set the value of
DefaultNameIdentifierFormat to be "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress".
If you have a custom Name Identifier format, then you will need to create your own implementation of our
ISamlNameIdService to handle your custom format.
If you want to set a specific NameId per Service Provider, then you can extend our
Saml2SingleSignOnResponseGenerator class which is used to generate single sign-on responses. You can extend the
CreateResponse method by overriding the
Assertion.Subject property of the generated
Saml2Response object. To get Service Provider information, you can inject
IServiceProviderStore into the constructor of your class.
IServiceProviderStore should be resolved automatically as it is already registered in the DI container. Lastly, you will need to register your custom implementation in the DI container, which must be done after calling our component, as the last registered implementation of
ISaml2SingloeSignOnResponseGenerator will be used.
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
RequireSamlResponseDestination to be false.
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.
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.