SAML Events

A number of callback delegates are provided that allow SAML protocol messages and SAML assertions to be accessed or modified during creation or processing.

For most applications, using these delegates is optional.

ISamlServiceProviderEvents

The ISamlServiceProviderEvents interface provides access to SAML SSO and SLO events when acting as the service provider.

ISamlServiceProviderEvents extends the ISamlProviderEvents interface.

OnAuthnRequestCreated

OnAuthnRequestCreated is called when a SAML authentication request has been created.

Func<HttpContext, AuthnRequest, AuthnRequest> OnAuthnRequestCreated { get; set; }

OnSamlResponseReceived

OnSamlResponseReceived is called when a SAML response is received from an identity provider.

Action<HttpContext, SamlResponse, string> OnSamlResponseReceived { get; set; }

OnSamlAssertionReceived

OnSamlAssertionReceived is called when a SAML assertion is received from an identity provider.

Action<HttpContext, SamlAssertion> OnSamlAssertionReceived { get; set; }

ISamlIdentityProviderEvents

The ISamlIdentityProviderEvents interface provides access to SAML SSO and SLO events when acting as the identity provider.

ISamlIdentityProviderEvents extends the ISamlProviderEvents interface.

OnAuthnRequestReceived

OnAuthnRequestReceived is called when a SAML authentication request is received from a service provider.

Action<HttpContext, AuthnRequest, string> OnAuthnRequestReceived { get; set; }

OnSamlAssertionCreated

OnSamlAssertionCreated is called when a SAML assertion has been created.

Func<HttpContext, SamlAssertion, SamlAssertion> OnSamlAssertionCreated { get; set; }

OnSamlResponseCreated

OnSamlResponseCreated is called when a SAML response has been created.

Func<HttpContext, SamlResponse, SamlResponse> OnSamlResponseCreated { get; set; }

ISamlProviderEvents

The ISamlProviderEvents interface is the base interface for ISamlServiceProviderEvents and ISamlIdentityProviderEvents.

OnResolveUrl

OnResolveUrl is called to resolve the destination URL when sending a SAML message.

Func<HttpContext, SamlEndpointType, string, string> OnResolveUrl { get; set; }

OnSendMessage

OnSendMessage is called when sending a SAML message.

Func<HttpContext, XmlElement, XmlElement> OnSendMessage { get; set; }

OnReceiveMessage

OnReceiveMessage is called when receiving a SAML message.

Func<HttpContext, XmlElement, XmlElement> OnReceiveMessage { get; set; }

OnGenerateSignature

OnGenerateSignature is called when a signature has been generated.

Action<HttpContext, X509Certificate2> OnGenerateSignature { get; set; }

OnVerifySignature

OnVerifySignature is called when a signature has been verified.

Action<HttpContext, X509Certificate2> OnVerifySignature { get; set; }

OnEncrypt

Action<HttpContext, X509Certificate2> OnEncrypt { get; set; }

OnDecrypt

OnDecrypt is called when data has been decrypted.

Action<HttpContext, X509Certificate2> OnDecrypt { get; set; }

OnLogoutRequestCreated

OnLogoutRequestCreated is called when a SAML logout request has been created.

Func<HttpContext, LogoutRequest, LogoutRequest> OnLogoutRequestCreated { get; set; }

OnLogoutResponseCreated

OnLogoutResponseCreated is called when a SAML logout response has been created.

Func<HttpContext, LogoutResponse, LogoutResponse> OnLogoutResponseCreated { get; set; }

OnLogoutRequestReceived

OnLogoutRequestReceived is called when a SAML logout request is received.

Action<HttpContext, LogoutRequest, string> OnLogoutRequestReceived { get; set; }

OnLogoutResponseReceived

OnLogoutResponseReceived is called when a SAML logout response is received.

Action<HttpContext, LogoutResponse, string> OnLogoutResponseReceived { get; set; }

OnArtifactResolveCreated

OnArtifactResolveCreated is called when a SAML artifact resolve request is created.

Func<HttpContext, ArtifactResolve, ArtifactResolve> OnArtifactResolveCreated { get; set; }

OnArtifactResponseCreated

OnArtifactResponseCreated is called when a SAML artifact response is created.

Func<HttpContext, ArtifactResponse, ArtifactResponse> OnArtifactResponseCreated { get; set; }

OnArtifactResolveReceived

OnArtifactResolveReceived is called when a SAML artifact resolve request is received.

Action<HttpContext, ArtifactResolve> OnArtifactResolveReceived { get; set; }

OnArtifactResponseReceived

OnArtifactResponseReceived is called when a SAML artifact response is received.

Action<HttpContext, ArtifactResponse> OnArtifactResponseReceived { get; set; }

Event Examples

Adding a Query String

The following example demonstrates adding a query string to the single sign-on service URL before sending the SAML authn request to the IdP.

_samlServiceProvider.Events.OnResolveUrl += (httpContext, samlEndpointType, url) =>
{
    return QueryHelpers.AddQueryString(url, "username", "[email protected]");
};

await _samlServiceProvider.InitiateSsoAsync(partnerName, returnUrl);

Adding Advice to the SAML Assertion

The following example demonstrates adding advice to the SAML assertion.

// Add optional advice to the SAML assertion.
_samlIdentityProvider.Events.OnSamlAssertionCreated += (httpContext, samlAssertion) =>
{
    samlAssertion.Advice = new Advice()
    {
        AdviceList = new List<AdviceListItem>()
        {
            new AdviceListItem()
            {
                SamlAssertion = new SamlAssertion()
                {
                    Issuer = samlAssertion.Issuer,
                    Subject = new Subject()
                    {
                        NameID = new NameID()
                        {
                            Name = "[email protected]"
                        }
                    }
                }
            }
        }
    };

    return samlAssertion;
};

return _samlIdentityProvider.SendSsoAsync(userName, attributes);

Adding SAML Extensions

The following example demonstrates adding SAML extensions to a SAML authentication request.

// Include SAML extensions in the authn request.
_samlServiceProvider.Events.OnAuthnRequestCreated += (httpContext, authnRequest) =>
{
    var xmlDocument = new XmlDocument();
    xmlDocument.LoadXml("<test xmlns=\"urn:test\">This is a test</test>");

    authnRequest.Extensions = new Extensions()
    {
        Items = new List<XmlElement>() { xmlDocument.DocumentElement }
    };

    return authnRequest;
};

await _samlServiceProvider.InitiateSsoAsync(partnerName);

Retrieving SAML Extensions

The following example demonstrates receiving SAML extensions in a SAML authentication request.

// Receive the SAML extensions included in the authn request.
IEnumerable<XmlElement> extensionsItems = null;

_samlIdentityProvider.Events.OnAuthnRequestReceived += (httpContext, authnRequest, relayState) =>
{
    extensionsItems = authnRequest.Extensions?.Items;
};

await _samlIdentityProvider.ReceiveSsoAsync();