SurePassID Identity Provider

SAML 2.0, OpenID Connect, and Entra ID EAM - Complete Reference

SAML 2.0, OpenID Connect, and Entra ID EAM - Complete Reference

Version: 2026.4

Overview

The SurePassID Identity Provider authenticates users and issues federated credentials across three protocol surfaces:

It provides:

• Single Sign-On (SSO) - Authenticate once, access multiple applications
• Single Logout (SLO) - Logout from all connected applications
• Conditional Access Policies - Control access based on IP, time, and other factors (SAML 2.0 only in this release)
• Multi-Factor Authentication - Integrate with SurePassID authentication
• Attribute and Claim Mapping - Pass user attributes to Service Providers and Relying Parties

Note: Earlier releases of this component were SAML 2.0 only. As of 2026.4 it is the SurePassID Identity Provider, serving SAML 2.0, OIDC, and EAM from a shared authentication pipeline.

Deployment Options

The SurePassID Identity Provider is included in every SurePassID installation type, so the SAML 2.0, OIDC, and EAM surfaces are available regardless of how the platform is deployed:

Standalone Installer for Large-Scale Deployments

A standalone Identity Provider installer is also available for large-scale deployments across distributed systems. This lets you deploy the Identity Provider independently of the rest of the platform, so you can:

• Run multiple Identity Provider instances across sites, regions, or network segments
• Place the federation endpoints close to the Service Providers and Relying Parties that consume them
• Scale the authentication tier independently of the Admin Portal and other components

All instances continue to read tenant, application, and policy configuration from the SurePassID Admin Portal, so federation behavior stays consistent across a distributed deployment.

Where Configuration Is Performed

Important: This component is the authentication runtime. It does not provide administrative screens for defining your federation setup.

All end-user configuration for SAML 2.0, OIDC, and EAM is performed in the SurePassID Admin Portal.

Configured in the SurePassID Admin Portal:

• Tenants/domains and the AllowSSO gate that enables each protocol surface
• SAML Service Provider registration, ACS URLs, NameID format, and attribute mapping
• OIDC client registration, redirect URIs, scopes, secrets, and consent settings
• EAM enablement and the Entra ID trust relationship
• Signing certificates, including secondary certificates used during key rotation
• User and application assignment
• Conditional-access policies (IP whitelist, time-of-day, enforcement mode) — enforced for SAML 2.0 flows only; see Policy Evaluation

Configured in this component (operators only, via web.config):

• Session cache provider and expiration
• Diagnostic tracing switches
• Hardening and encryption settings

If a feature appears unavailable at runtime, verify the corresponding Admin Portal setting before investigating this component.

Entra ID configuration references

Key Components

Architecture

SAML 2.0 Flow Diagram

+-------------+                  +--------------+                 +------------+
|   Browser   |                  | SurePassIdp  |                 |  Service   |
|             |                  |     (IdP)    |                 |  Provider  |
+-------------+                  +--------------+                 +------------+
       |                                 |                              |
       |  1. Access SP Resource          |                              |
       |------------------------------------------------------------->  |
       |                                 |                              |
       |  2. AuthnRequest (Redirect)     |                              |
       |  <-------------------------------------------------------------|
       |                                 |                              |
       |  3. Submit AuthnRequest         |                              |
       |-------------------------------> |                              |
       |                                 |                              |
       |  4. Login Page                  |                              |
       |  <------------------------------|                              |
       |                                 |                              |
       |  5. Credentials + MFA           |                              |
       |-------------------------------> |                              |
       |                                 |                              |
       |  6. SAML Assertion (POST)       |                              |
       |  <------------------------------|                              |
       |                                 |                              |
       |  7. Submit Assertion to SP      |                              |
       |------------------------------------------------------------->  |
       |                                 |                              |
       |  8. Access Granted              |                              |
       |  <-------------------------------------------------------------|

OpenID Connect Flow Diagram

+-------------+                  +--------------+                 +------------+
|   Browser   |                  | SurePassIdp  |                 |  Relying   |
|             |                  |     (IdP)    |                 |   Party    |
+-------------+                  +--------------+                 +------------+
       |                                 |                              |
       |  1. Access RP Resource          |                              |
       |------------------------------------------------------------->  |
       |                                 |                              |
       |  2. Redirect to /authorize      |                              |
       |  <-------------------------------------------------------------|
       |     (code_challenge, state)     |                              |
       |                                 |                              |
       |  3. Authorization Request       |                              |
       |-------------------------------> |                              |
       |                                 |                              |
       |  4. Login Page + MFA            |                              |
       |  <----------------------------> |                              |
       |                                 |                              |
       |  5. Consent (if required)       |                              |
       |  <----------------------------> |                              |
       |                                 |                              |
       |  6. Redirect with code          |                              |
       |  <------------------------------|                              |
       |                                 |                              |
       |  7. Deliver code to RP          |                              |
       |------------------------------------------------------------->  |
       |                                 |                              |
       |                                 |  8. Token request            |
       |                                 |     (code + code_verifier)   |
       |                                 |  <---------------------------|
       |                                 |                              |
       |                                 |  9. id_token + access_token  |
       |                                 |  --------------------------> |
       |                                 |                              |
       |  10. Access Granted             |                              |
       |  <-------------------------------------------------------------|

Steps 8 and 9 occur back-channel between the relying party and the IdP token endpoint; the browser is not involved.

Entra ID EAM Flow Diagram

+-------------+                  +--------------+                 +------------+
|   Browser   |                  |  Entra ID    |                 |SurePassIdp |
|             |                  |              |                 |   (EAM)    |
+-------------+                  +--------------+                 +------------+
       |                                 |                              |
       |  1. Sign in to Entra ID         |                              |
       |-------------------------------> |                              |
       |                                 |                              |
       |  2. MFA required; redirect to   |                              |
       |     /eam/{domain}/authorize     |                              |
       |  <------------------------------|                              |
       |     (signed request object)     |                              |
       |                                 |                              |
       |  3. Authorization Request       |                              |
       |------------------------------------------------------------->  |
       |                                 |                              |
       |                                 |  4. Validate request object  |
       |                                 |     against Entra ID JWKS    |
       |                                 |  <-------------------------- |
       |                                 |                              |
       |  5. SurePassID MFA challenge    |                              |
       |  <---------------------------------------------------------->  |
       |                                 |                              |
       |  6. Signed id_token (form_post) |                              |
       |  <-------------------------------------------------------------|
       |     (acr, amr claims)           |                              |
       |                                 |                              |
       |  7. Submit id_token to Entra    |                              |
       |-------------------------------> |                              |
       |                                 |                              |
       |  8. Sign-in complete            |                              |
       |  <------------------------------|                              |

Component Interactions

+---------------------------------------------------------------+
|                         SurePassIdp                           |
|                                                               |
|  +-------------+   +-------------+   +-------------+          |
|  | SAML        |   | OIDC        |   | EAM         |          |
|  | SSOService  |   | Authorize   |   | Authorize   |          |
|  |   .aspx     |   |   .aspx     |   |   .aspx     |          |
|  +-------------+   +-------------+   +-------------+          |
|         |                 |                 |                 |
|         |                 +--------+--------+                 |
|         |                          |                          |
|         v                          v                          |
|  +----------------+         +----------------+                |
|  |    SsoUtil     |         |   SSOLogin     |                |
|  |                |         |  (shared MFA)  |                |
|  +----------------+         +----------------+                |
|         |                                                     |
|         v                                                     |
|  +------------------+                                         |
|  | Policy           |  (SAML 2.0 only - see note below)       |
|  | Evaluation       |                                         |
|  +------------------+                                         |
|         |                                                     |
|         v                                                     |
|  +----------------+   +----------------+   +----------------+ |
|  |  SAML2Util     |   | OidcToken /    |   | EamTokenSigner | |
|  |                |   | OidcUserInfo   |   |                | |
|  +----------------+   +----------------+   +----------------+ |
|         |                                                     |
|         v                                                     |
|  +-----------------------------------------------+            |
|  |     ComponentSpace SAML 2.0 Library           |            |
|  +-----------------------------------------------+            |
|                                                               |
+---------------------------------------------------------------+
                               |
                               v
                  +--------------------------+
                  |  SurePassClassLib        |
                  |  - Database Access       |
                  |  - Policy Engine         |
                  |  - Audit Service         |
                  |  - OIDC / EAM Services   |
                  +--------------------------+

Note: All three protocols share the same MFA experience through SSOLogin.aspx, but conditional access policy evaluation is currently invoked only from the SAML 2.0 flows. See Policy Evaluation.

Configuration

Database Configuration

Application Settings

Web.config (sample)

<configuration>
  <appSettings>
    <!-- Database Connection -->
    <add key="Connection.Server" value="your-sql-server" />
    <add key="Connection.Database" value="SurePassID" />
    <add key="Connection.Username" value="sa" />
    
    <!-- Encryption Keys -->
    <add key="System.Key" value="..." />
    <add key="System.IV" value="..." />
    <add key="System.Salt" value="..." />
    
    <!-- Single Tenant Mode -->
    <add key="Server.SingleTenantMode" value="false" />
    
    <!-- Directory Type Enumeration -->
    <add key="System.DirectoryType" value="SurePassId" />
    
    <!-- Diagnostic Tracing -->
    <add key="Trace.Enabled" value="true" />
    <add key="Server.TracePath" value="C:\Logs\SurePassIdp\" />
    
    <!-- SAML Attribute Prefix Removal -->
    <add key="Saml2.RemoveSsoRolePrefix" value="true" />
    <add key="Saml2.RemoveSsoGroupPrefix" value="true" />
  </appSettings>
  
  <system.web>
    <authentication mode="Forms">
      <forms loginUrl="~/SSOLogin.aspx" timeout="20" />
    </authentication>
    
    <sessionState mode="InProc" timeout="20" />
  </system.web>
</configuration>

Directory Types

The IdP supports multiple directory types for user authentication:

public enum DirectoryType
{
    SurePassId = 0,      // SurePassID native directory
    ActiveDirectory,      // Microsoft Active Directory
    Ldap,                // Generic LDAP directory
    Local                // Local users only
}

Usage:

var directoryType = SsoUtil.GetDirectoryType();

SAML Flows

SP-Initiated SSO Flow

1. Service Provider Sends AuthnRequest

The SP redirects the user to the IdP with an AuthnRequest:

GET /SAML/SSOService.aspx?SAMLRequest=<encoded_request>&RelayState=<state> HTTP/1.1
Host: idp.example.com

Or via HTTP-POST:

<form method="post" action="https://idp.example.com/SAML/SSOService.aspx">
  <input type="hidden" name="SAMLRequest" value="<encoded_request>" />
  <input type="hidden" name="RelayState" value="<state>" />
</form>

2. IdP Receives and Validates Request

The IdP performs multiple security validations:

// 1. Receive AuthnRequest
ReceiveAuthnRequest();

// 2. Check for replay attack
if (!ValidateRequestIdNotReplayed())
{
    return; // Request ID already used
}

// 3. Validate SP Issuer
if (!ValidateSpIssuer())
{
    return; // SP not registered
}

// 4. Verify signature (if present)
if (!ValidateAuthnRequestSignature())
{
    return; // Invalid signature
}

// 5. Evaluate conditional access policies for SAML
if (!SsoUtil.ValidatePolicy())
{
    return; // Policy violation
}

3. User Authentication

If ForceAuthn is set or no active session exists:

var requireLocalLogin = IsLocalLoginRequired(authnRequest.ForceAuthn);

if (requireLocalLogin)
{
    Session["AuthRequest"] = Request.QueryString;
    Session["requireLocalLoginInProgress"] = true;
    Session["ReturnURL"] = "~/SAML/SSOService.aspx";
    Response.Redirect("SSOLogin.aspx", true);
}

The user is redirected to SSOLogin.aspx for authentication:

1. Username/password authentication
2. Multi-factor authentication (if configured)
3. Device validation
4. Policy evaluation

4. Generate and Send SAML Assertion

After successful authentication:

SAML2Util.SendSaml2Assertion();

The assertion includes:

• Subject: User's NameID
• Conditions: Validity period, audience restrictions
• AuthnStatement: Authentication method and time
• AttributeStatement: User attributes (groups, roles, email, etc.)
• Signature: Digital signature (if configured)

5. User Accesses SP Resource

The SP validates the assertion and grants access.

IdP-Initiated SSO Flow

For IdP-initiated SSO (less common):

1. User accesses IdP directly
2. User authenticates at IdP
3. IdP presents list of available applications
4. User selects application
5. IdP generates assertion and sends to SP
6. User is logged into SP

OpenID Connect (OIDC)

Overview

The Identity Provider exposes a per-tenant OpenID Connect authorization server. Each tenant has its own issuer, signing keys, and discovery document, so relying parties can be onboarded independently.

Endpoints

Supported Flow

Only the Authorization Code flow is supported (response_type=code). Implicit and hybrid flows are intentionally not offered. PKCE using S256 is supported for every client and can be made mandatory per client.

Client authentication methods: client_secret_basic, client_secret_post, and none for public clients.

Relying Party Registration

OIDC clients are registered in the SurePassID Admin Portal. The key settings are:

Refresh Tokens

Refresh tokens rotate on every use. If a previously rotated refresh token is presented again, the IdP treats it as replay and revokes the entire descendant token chain. An absolute session lifetime caps how long a session can be extended regardless of rotation.

Logout

RP-initiated logout supports both front-channel (iframe) and back-channel (server-to-server) notification of participating relying parties. Relying parties are tracked per session, and a post_logout_redirect_uri is honored only when it is registered for the client.

Note: OIDC session state is held in an in-memory cache that is not shared across nodes. In a load-balanced deployment without sticky sessions, some logout notifications may be missed. See the Capabilities document for details.

Not Supported in This Release

client_credentials grant, private_key_jwt client authentication, implicit and hybrid flows, Pushed Authorization Requests (PAR), DPoP, and JARM.

Entra ID External Authentication Method (EAM)

Overview

EAM allows SurePassID to satisfy a Microsoft Entra ID multifactor authentication requirement. Entra ID performs the primary sign-in, then redirects the user to SurePassID for MFA. SurePassID returns a signed id_token asserting which authentication methods were used.

This is an MFA-only surface. It does not perform primary authentication and does not issue access tokens.

Endpoints

Request Modes

In both modes the asserted subject must match the expected login_hint or sub. Requests that supply neither are rejected.

Returned Claims

The signed id_token is returned by form_post and includes acr and amr claims describing the authentication methods actually used. The acr value can be overridden per tenant.

Replay Protection

A request object jti that has already been seen is rejected. This check shares the SAML request ID cache, so SamlCache.RequestIdExpirationMinutes also governs the EAM replay window. Ensure this value is at least as long as the Entra ID request object lifetime.

Entra ID Setup

Registration on the Entra ID side and the matching tenant configuration in the SurePassID Admin Portal are documented here:

• Set up SurePassID MFA for Entra ID
• What is SurePassID MFA for Microsoft Entra EAM

Single Logout (SLO)

SP-Initiated Logout Flow

1. Service Provider Sends LogoutRequest

The SP sends a LogoutRequest when the user logs out:

POST /SAML/SLOService.aspx HTTP/1.1
Host: idp.example.com
Content-Type: application/x-www-form-urlencoded

SAMLRequest=<encoded_logout_request>&RelayState=<state>

2. IdP Processes Logout Request

    // 1. Receive logout message (request or response)
    if (Request.HttpMethod.Equals("POST"))
    {
        SingleLogoutService.ReceiveLogoutMessageByHTTPPost();
    }
    else
    {
        SingleLogoutService.ReceiveLogoutMessageByHTTPRedirect();
    }

    // 2. Process request or response
    if (isRequest)
    {
        ProcessLogoutRequest();
    }
    else
    {
        ProcessLogoutResponse();
    }

3. Security Validations

Replay Attack Prevention:

if (!ValidateLogoutRequestIdNotReplayed())
{
    ServiceMessage = "Logout request has expired or already been processed.";
    return;
}

Destination Validation:

if (!ValidateLogoutRequestDestination())
{
    // Log security warning
    return;
}

Signature Validation (if required):

if (!ValidateLogoutRequestSignature())
{
    ServiceMessage = "Logout request signature verification failed.";
    return;
}

4. Terminate Session

// Remove SAML session from cache
if (sessionIndexes != null)
{
    foreach (var sessionIndex in sessionIndexes)
    {
        SamlRequestIdCache.RemoveSession(sessionIndex.Index);
    }
}

// Logout locally
FormsAuthentication.SignOut();
Session.Abandon();

5. Send LogoutResponse

// Create logout response
var logoutResponse = CreateLogoutResponse(idpIssuer);
logoutResponse.Status = new Status(SAMLIdentifiers.PrimaryStatusCodes.Success);

// Sign response (if configured)
if (partnerSsoApps.SSOSignLogoutResponses == true)
{
    SAMLMessageSignature.Generate();
}

// Send using configured binding
SendLogoutResponse();

IdP-Initiated Logout Flow

For IdP-initiated logout:

1. IdP sends LogoutRequest to each SP
2. SP processes logout and responds with LogoutResponse
3. IdP receives and logs response status
4. IdP terminates local session

private void ProcessLogoutResponse(LogoutResponse logoutResponse, string relayState)
{
    var statusCode = logoutResponse.Status.StatusCode;
    var isSuccess = statusCode.Contains();
    
    if (isSuccess)
    {
        // Log successful logout
        SsoUtil.WriteLogInfo(AuditResultCode.Success, AuditSeverity.Success,
                            "IdP-initiated logout completed successfully", ...);
    }
    
    // Logout locally
    FormsAuthentication.SignOut();
    Session.Abandon();
}

Logout Bindings

The IdP supports both SAML 2.0 logout bindings:

HttpPost = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
HttpRedirect = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";

Policy Evaluation

Overview

Conditional access policies control who can access SSO applications based on:

• IP Address: Whitelist-based IP restrictions
• Time of Day: Day-of-week and time-of-day access controls
• Enforcement Mode: Ignore, Log, or Enforce violations

Protocol Scope

Important: Conditional access policy evaluation is currently applied to SAML 2.0 flows only, and only when a policy is configured for the application. OpenID Connect and Entra ID EAM authentications do not invoke policy evaluation in this release.

All three protocols share the same multifactor authentication experience through SSOLogin.aspx, so MFA requirements still apply to OIDC and EAM sign-ins. However, IP whitelist and time-of-day restrictions are not enforced for those protocols.

If you rely on conditional access restrictions today, be aware that exposing the same user population through an OIDC client or through EAM provides an authentication path where those restrictions are not applied. Where IP or time-of-day enforcement is a requirement, apply an equivalent control at the relying party, at Entra ID Conditional Access, or at the network layer until policy evaluation is extended to these protocols.

Policy Evaluation Logic

The ValidatePolicy() method delegates to FederationPolicyDecision:

public static bool ValidatePolicy(...)
{
    try
    {
     
        var policyDecision = new FederationPolicyDecision();

        var result = policyDecision.Evaluate();

        // Log detailed results
        WriteDiagnosticTrace($"ValidatePolicy() - Result={result}, " +
            $"PolicyDecision.Result={policyDecision.Result?.ToJson()}");

        return result;
    }
    catch (Exception ex)
    {
        errorMsg = ex.Message;
        return false;
    }
}

Policy Results

The policy engine returns detailed results:

{
  "AccessAllowed": true,
  "Summary": {
    "ValidPolicies": 2,
    "IgnoredPolicies": 0,
    "LoggedPolicies": 1,
    "EnforcedPolicies": 0
  },
  "PolicyAnalysis": [
    {
      "PolicyDecision": true,
      "PolicyName": "Office Hours Policy",
      "EnforcementRuleText": "Enforce",
      "ValidIpPolicy": true,
      "IpPolicyMessage": "Client IP 192.168.1.100 is valid.",
      "ValidTimePolicy": true,
      "TimePolicyMessage": "Access time valid for Tuesday 14:30."
    }
  ]
}

Enforcement Modes

Access Decision Rules

Access is ALLOWED when:

• At least one policy passes all checks, OR
• All failed policies have enforcement mode Ignore or Log

Access is DENIED when:

• No policies pass AND at least one failed policy has enforcement mode Enforce

Audit Logging

All policy evaluations are automatically logged to the audit trail:

// Example audit record for policy violation
{
    "AuditAction": "IdentityProviderLogin",
    "ResultCode": 9069,  // SSOPolicyClientIPInvalid
    "Severity": "Severe",
    "Message": "SSO Policy Client IP Invalid",
    "RequestData": "{\"AccessAllowed\":false,\"Summary\":{...}}"
}

Policy-Related Audit Codes:

• 9061 - SSOPolicyNoDailyAccess
• 9062 - SSOPolicyNoDailyAccessIgnored
• 9063 - SSOPolicyNoDailyAccessLogged
• 9065 - SSOPolicyTimeRestriction
• 9066 - SSOPolicyTimeRestrictionIgnored
• 9069 - SSOPolicyClientIPInvalid
• 9070 - SSOPolicyClientIPInvalidIgnored
• 9067 - SSOPolicyExceptionIgnored
• 9068 - SSOPolicyException

SAML Attributes

Overview

SAML attributes pass user information from the IdP to the Service Provider. The IdP supports multiple attribute formats and sources.

Attribute Sources

1. SurePassID User Attributes

Standard user attributes from the SurePassID database:

• Email
• First Name
• Last Name
• Phone Number
• User ID
• Partner ID
• Department
• Title

2. SSO Roles

User roles specific to SSO applications:

// Get roles as comma-separated string
string roles = SsoUtil.GetSurePassSsoRoles(;

// Get roles as SAMLAttribute
SAMLAttribute rolesAttr = SsoUtil.GetSurePassSsoRolesXml();

Role Override Feature:

• If useSsoRoleOverride = true, returns only the first role starting with "primary_"
• Prefix "primary_" is removed if Saml2.RemoveSsoRolePrefix = true

Example:

SurePassID SSO Roles Roles: primary_admin, user, readonly
useSsoRoleOverride = true -> "admin" (prefix removed)
useSsoRoleOverride = false -> "primary_admin,user,readonly"

3. User Groups

User group memberships:

// Get groups as comma-separated string
string groups = SsoUtil.GetSurePassGroup();

// Get groups as SAMLAttribute
SAMLAttribute groupsAttr = SsoUtil.GetSurePassGroupXml();

// Get groups as XML string
string groupsXml = SsoUtil.GetSurePassGroupXmlString();

Group Override Feature:

• If useSsoGroupOverride = true, returns only the first group starting with "sso_"
• Prefix "sso_" is removed if Saml2.RemoveSsoGroupPrefix = true

Example:

Database Groups: sso_administrators, employees, contractors
useSsoGroupOverride = true -> "administrators" (prefix removed)
useSsoGroupOverride = false -> "sso_administrators,employees,contractors"

4. Active Directory Groups

For AD-integrated deployments:

string adGroups = SsoUtil.GetActiveDirectoryGroup(conn, userName);

Returns a comma-separated list of AD security groups for the user.

Attribute Formats

Basic Format (Most Common)

<saml:Attribute Name="email" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                FriendlyName="Email Address">
  <saml:AttributeValue>user@example.com</saml:AttributeValue>
</saml:Attribute>

URI Format

<saml:Attribute Name="urn:oid:0.9.2342.19200300.100.1.3" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
  <saml:AttributeValue>user@example.com</saml:AttributeValue>
</saml:Attribute>

Unspecified Format

<saml:Attribute Name="customAttribute" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml:AttributeValue>customValue</saml:AttributeValue>
</saml:Attribute>

Multi-Valued Attributes

Groups and roles are typically multi-valued:

<saml:Attribute Name="groups" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                FriendlyName="groups">
  <saml:AttributeValue>Administrators</saml:AttributeValue>
  <saml:AttributeValue>Employees</saml:AttributeValue>
  <saml:AttributeValue>IT Department</saml:AttributeValue>
</saml:Attribute>

Troubleshooting

Diagnostic Tracing

Enable Tracing

<appSettings>
    <add key="Trace.Enabled" value="true" />
    <add key="Server.TracePath" value="C:\Logs\SurePassIdp\" />
</appSettings>

Trace File Format

Filename: SurePassIdp20250115.log
Format: MM/dd/yyyy HH:mm:ss.fff | <message>

Example:
01/15/2025 14:32:15.123 | SSOService.aspx: Page_Load() Entry
01/15/2025 14:32:15.125 | SSOService.aspx: Session Exists
01/15/2025 14:32:15.127 | SSOService.aspx: Pre ReceiveAuthnRequest
...

Issue 1: Replay Attack Detected

Symptom:

ServiceMessage: "Authentication request has expired or already been processed."
Audit Code: 9142 (SSOReplayAttackDetected)

Causes:

• User refreshed the page during authentication
• SP is reusing request IDs
• Clock skew between SP and IdP

Solutions:

1. Educate users not to refresh during authentication
2. Configure SP to generate unique request IDs
3. Synchronize clocks using NTP
4. Check request ID cache retention period

Issue 2: Signature Verification Failed

Symptom:

ServiceMessage: "Authentication request signature verification failed."
Audit Code: 9140 (SSOAuthnRequestSignatureInvalid)

Causes:

• Certificate mismatch between SP and IdP
• Expired SP certificate
• Clock skew causing signature timing issues
• Tampered request

Solutions:

1. Verify SP public key matches certificate used for signing:

   SELECT SSOSPCertificate FROM PartnerSSOApps WHERE SSOAppId = <id>

2. Check certificate validity dates
3. Synchronize clocks (within 5 minutes)
4. Review network security devices (proxies, load balancers)
5. Capture and inspect SAML request XML

Issue 3: Policy Violation

Symptom:

ServiceMessage: "Access denied: SurePassId Policy. <policy details>"
Audit Codes: 9061-9070

Causes:

• User accessing from non-whitelisted IP
• Accessing outside allowed time window
• Policy configuration error

Solutions:

1. Check IP whitelist:

   SELECT * FROM PartnerFederationPolicies 
   WHERE PartnerUserId = <user_id> AND SSOAppId = <app_id>

2. Verify time-based policies:
   • Check user's timezone setting
   • Verify day-of-week restrictions
   • Confirm time-of-day ranges
3. Review enforcement mode:
   • Change to "Log" mode for testing
   • Review audit logs for detailed policy analysis
4. Validate policy JSON:

   SELECT RequestData FROM AuditLog 
   WHERE ResultCode IN (9061, 9065, 9069)
   ORDER BY AuditDate DESC

Issue 4: SP Configuration Not Found

Symptom:

ServiceMessage: "Cannot find SSO App by Service Provider Issuer (Entity ID)=..."
Audit Code: 9059 (SSOInternalError)

Causes:

• SP not registered in database
• SP Issuer (Entity ID) mismatch
• Case-sensitive comparison issue

Solutions:

1. Verify SP registration:

   SELECT * FROM PartnerSSOApps 
   WHERE SSOSPIssuer = '<sp_entity_id>'

2. Check Entity ID format:
   • Must match exactly (case-sensitive)
   • Common formats:
     • https://sp.example.com/saml/metadata
     • urn:sp:example:com
     • sp.example.com
3. Register SP:

   INSERT INTO PartnerSSOApps (PartnerId, SSOAppName, SSOSPIssuer, SSOSPAcsUrl, ...)
   VALUES (...)

Issue 5: Logout Not Working

Symptom:

• User logs out from SP but remains logged into IdP
• User logs out from IdP but remains logged into SP

Causes:

• SLO not configured on SP
• Logout URL not configured
• Session Index not tracked

Solutions:

1. Verify SLO configuration:

   SELECT SSOSPLogoutURL, SSOSPLogoutBinding 
   FROM PartnerSSOApps 
   WHERE SSOAppId = <id>

2. Check SP SLO support:
   • Ensure SP supports SLO (not all do)
   • Verify SP SLO endpoint is accessible
3. Review logout audit logs:

   SELECT * FROM AuditLog 
   WHERE AuditAction = <IdentityProviderLogin_Action_Id>
   AND Message LIKE '%logout%'
   ORDER BY AuditDate DESC

4. Test SLO endpoint:

   https://sp.example.com/logout

Issue 6: Certificate Password Decryption Error

Symptom:

Trace: "SLOService: GetCertificate error: ..."

Causes:

• Key management system unavailable
• Incorrect password encryption
• HSM connection failure

Solutions:

1. Check key provider:

   SELECT KeyProvider, KeyProviderEndpoint 
   FROM PartnerKeyManagement 
   WHERE PartnerId = <id>

2. Verify KMS endpoint:
   • Test connectivity to HSM/KMS
   • Check firewall rules
   • Verify credentials
3. Test certificate loading:

   var cert = new X509Certificate2(certBytes, password);

4. Review encryption configuration:
   • Verify System.Key, System.IV, System.Salt

Audit Log Queries

Recent SSO Activity

SELECT TOP 100
    AuditDate,
    PartnerUserLogin,
    ResultCode,
    ResultText,
    Message,
    RequestData
FROM AuditLog
WHERE AuditAction = <IdentityProviderLogin_Action_Id>
ORDER BY AuditDate DESC

Security Events

SELECT TOP 100
    AuditDate,
    PartnerUserLogin,
    ResultCode,
    ResultText,
    Message,
    ClientIP
FROM AuditLog
WHERE ResultCode IN (
    9139,  -- SSOAcsUrlMismatch
    9140,  -- SSOAuthnRequestSignatureInvalid
    9141,  -- SSOAuthnRequestSignatureRequired
    9142,  -- SSOReplayAttackDetected
    9143,  -- SSOLogoutDestinationMismatch
    9144,  -- SSOLogoutSignatureRequired
    9145   -- SSOLogoutSignatureInvalid
)
ORDER BY AuditDate DESC

Policy Violations

SELECT 
    AuditDate,
    PartnerUserLogin,
    ClientIP,
    ResultCode,
    ResultText,
    Message,
    CAST(RequestData AS NVARCHAR(MAX)) AS PolicyDetails
FROM AuditLog
WHERE ResultCode IN (9061, 9062, 9063, 9065, 9066, 9068, 9069, 9070)
ORDER BY AuditDate DESC

Failed Logins

SELECT TOP 100
    AuditDate,
    PartnerUserLogin,
    ResultCode,
    ResultText,
    Message,
    ClientIP
FROM AuditLog
WHERE AuditAction = <IdentityProviderLogin_Action_Id>
AND ResultCode != 1  -- Success
ORDER BY AuditDate DESC

Appendix

SAML 2.0 Specifications

• SAML Core: http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
• SAML Bindings: http://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf
• SAML Profiles: http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf

Audit Result Code Reference

• 9059 - SSOInternalError
• 9060 - SSOCertificateError
• 9139 - SSOAcsUrlMismatch
• 9140 - SSOAuthnRequestSignatureInvalid
• 9141 - SSOAuthnRequestSignatureRequired
• 9142 - SSOReplayAttackDetected
• 9143 - SSOLogoutDestinationMismatch
• 9144 - SSOLogoutSignatureRequired
• 9145 - SSOLogoutSignatureInvalid

Configuration Checklist

Minimum Configuration

• Database connection settings
• Encryption keys (System.Key, System.IV, System.Salt)
• SP Entity ID (SSOSPIssuer)
• SP ACS URL (SSOSPAcsUrl)
• IdP Entity ID (SSOIdPIssuer)
• IdP signing certificate

Recommended Configuration

• All minimum settings
• SP Logout URL (for SLO support)
• Signature requirements
• Conditional access policies
• Diagnostic tracing enabled
• Audit log retention policy

Optional Configuration

• SP certificate (for signature verification)
• Custom attribute mappings
• HSM integration
• Single tenant mode
• Directory integration (AD/LDAP)

Support

For additional assistance:

• Review diagnostic trace logs
• Review audit log in the SurePassID Admin Portal
• Query audit database for detailed events (non-cloud installations only)
• Verify tenant, application, and policy settings in the SurePassID Admin Portal
• Contact SurePassID Support
• For all SAML Knowledgebase articles go to https://support.surepassid.com/kb-search-results?q=saml&type=KNOWLEDGE_ARTICLE