SurePassID Identity Provider

SurePassID Identity Provider Capabilities Document

Version 2026.4

Purpose: This document describes the federation capabilities of the SurePassID Identity Provider (IdP), covering the SAML 2.0, OpenID Connect (OIDC), and Entra ID External Authentication Method (EAM) surfaces. It is intended for Service Provider (SP) and Relying Party (RP) test tool developers to understand what features to test and how the IdP behaves in various scenarios.

Scope: Authentication Component vs. Admin Portal

Important: This component is the authentication runtime only. It authenticates users and issues SAML assertions, OIDC tokens, and EAM results. It does not provide screens for defining your federation setup.

All end-user configuration for SAML 2.0, OIDC, and EAM is performed in the SurePassID Admin Portal. This includes creating and managing tenants/domains, registering Service Providers and OIDC clients, enabling the EAM surface, assigning users and applications, uploading or generating signing certificates, and setting conditional-access policies.

The IdP reads that configuration at runtime. If a capability described below appears unavailable, verify the corresponding setting in the Admin Portal first.

Entra ID configuration references

Deployment availability

The Identity Provider is included in the on-premises, air-gapped, cloud-gapped, and cloud installations, so the capabilities described in this document are available in every deployment model. A standalone Identity Provider installer is also available for large-scale deployments across distributed systems. See the SurePassID Identity Provider User Guide for details.

1. SAML Protocol Support

1.1 Bindings

SP-to-IdP Bindings (AuthnRequest Reception)

Implementation Location: SSOService.aspx.cs - ReceiveAuthnRequest() method

// HTTP-POST detection
if (Request.HttpMethod.Equals("POST", StringComparison.OrdinalIgnoreCase))
{
    IdentityProvider.ReceiveAuthnRequestByHTTPPost(...);
}
else
{
    IdentityProvider.ReceiveAuthnRequestByHTTPRedirect(...);
}

IdP-to-SP Bindings (SAML Response Transmission)

Key Limitation: The IdP only sends SAML responses via HTTP-POST binding. The SP's Assertion Consumer Service (ACS) must accept HTTP-POST.

SLO Bindings (Logout)

Implementation Note: While HTTP-Redirect is accepted for incoming logout requests, the IdP always sends LogoutResponses via HTTP-POST for reliability.

1.2 NameID Formats

NameID Generation Details

Persistent NameID Characteristics:

• Deterministic: Same user + same SP always produces the same NameID
• Pairwise: Different SPs receive different NameIDs for the same user
• Opaque: Base64-encoded SHA256 hash (URL-safe: +→-, /→_)
• Stable: Survives server restarts (based on database IDs + configured salt)

Default Behavior: If no SSOSubjectSource is configured, the IdP defaults to email (emailAddress format).

1.3 Authentication Context Classes

Current Limitation: The IdP always returns Password as the AuthnContextClassRef, regardless of whether multi-factor authentication (MFA) was performed. The MFA status is tracked internally but not reflected in the SAML assertion's AuthnContext.

Implementation Location: SAML2Util.cs

var authnStatement = new AuthnStatement
{
    AuthnContext = new AuthnContext
    {
        AuthnContextClassRef = new AuthnContextClassRef(SAMLIdentifiers.AuthnContextClasses.Password)
    }
};

2. SAML Features

2.1 Request Handling

ForceAuthn Handling

Implementation: When ForceAuthn="true", the IdP clears the current session and redirects to the login page.

// SSOService.aspx.cs
var requireLocalLogin = IsLocalLoginRequired(authnRequest.ForceAuthn);
if (requireLocalLogin)
{
    Session[spSession.SESSION_CONST] = null;  // Clear session
    Response.Redirect("SSOLogin.aspx", true); // Force login
}

IsPassive Handling

Current Behavior: The IdP does not currently check for IsPassive. If no session exists, the user will be redirected to login regardless of the IsPassive flag. This may result in protocol violations when IsPassive="true" is set but no session exists.

Expected Behavior (not implemented): Should return urn:oasis:names:tc:SAML:2.0:status:NoPassive when IsPassive="true" and no session exists.

AssertionConsumerServiceURL Validation

Security Behavior: When the ACS URL in the AuthnRequest doesn't match the registered URL:

1. The IdP logs a security warning
2. The IdP uses the registered URL (not the requested one)
3. The request is allowed to proceed (for backward compatibility)

if (!string.Equals(requestedAcsUrl, registeredAcsUrl, StringComparison.OrdinalIgnoreCase))
{
    // Log security event
    SsoUtil.WriteLogInfo(..., AuditResultCode.SSOAcsUrlMismatch, ...);
    // Use registered URL instead
    samlResponse.Destination = registeredAcsUrl;
}

NameIDPolicy Handling

Current Behavior: The IdP parses the NameIDPolicy element but does not honor the requested format. The NameID format is determined by the SP application's SSOSubjectSource configuration, not by the AuthnRequest.

Test Implication: SPs cannot dynamically request a specific NameID format per request. The format is fixed per SP configuration.

Scoping / ProxyCount

The IdP does not support proxy scenarios or SP scoping hints.

2.2 Response Generation

Signature Configuration

Both the outer Response and the inner Assertion are signed with the IdP's private key.

Signature Order:

1. Assertion is signed first (SAMLAssertionSignature.Generate)
2. Signed assertion is added to Response
3. Response is signed (SAMLMessageSignature.Generate)

Assertion Encryption

Current Limitation: The IdP does not encrypt assertions. All assertion content is transmitted in cleartext (though signed). Transport-level security (HTTPS) is relied upon for confidentiality.

Assertion Validity Period

Default Validity: 20 minutes if no SSOAssertionTimeSpanHHMMSS is configured.

Format: HH:MM:SS or DD:HH:MM:SS

• Example: 00:20:00 = 20 minutes
• Example: 01:00:00:00 = 1 day

// SAML2Util.cs
private static TimeSpan GetAssertionTimeSpan(string duration)
{
    // Returns TimeSpan.FromMinutes(20) if duration is null/empty
    // Parses "HH:MM:SS" or "DD:HH:MM:SS" format
}

Clock Skew Handling

The IdP does not add clock skew tolerance to NotBefore. It uses the exact current server time. Clock skew tolerance should be handled by the SP.

Recommendation: SPs should allow 2-5 minutes of clock skew when validating NotBefore and NotOnOrAfter.

2.3 Attribute Statements

Standard Attributes

Group Attributes

Attribute Configuration

Attributes are configured per SP in the SSOAttributeListValuePairs field as XML:

<AttributeList>
  <attributes>
    <attr>
      <name>email</name>
      <value>_email</value>
    </attr>
    <attr>
      <name>firstName</name>
      <value>_givenname</value>
    </attr>
    <attr>
      <name>groups</name>
      <value>_groups</value>
    </attr>
  </attributes>
</AttributeList>

Attribute Name Formats

Note: The attribute Name is set from the configuration, and FriendlyName is set to the same value.

Automatic Attribute Mapping from SP Metadata

When importing SP metadata, the IdP automatically maps requested attributes to SurePassId placeholders based on:

Common OID Mappings:

Implementation Location: SurePassClassLib\Utility\Saml2Util.cs - MapAttributeToPlaceholder() method

3. Single Logout (SLO)

3.1 SP-Initiated SLO

Endpoint: /SAML/SLOService.aspx

SLO Processing Flow

1. Receive LogoutRequest (POST or Redirect)
2. Validate Request ID (replay attack check)
3. Validate Destination (optional, logs if mismatch)
4. Lookup Session by SessionIndex in cache
5. Validate Signature (if required by SP config)
6. Remove Session from IdP cache
7. Terminate Local Session (FormsAuthentication.SignOut())
8. Send LogoutResponse with Success status

3.2 IdP-Initiated SLO

Current Behavior: When a user logs out from the IdP directly (via /SAML/Logout.aspx):

• The IdP session is terminated
• All SAML session records are removed from cache
• No LogoutRequests are sent to SPs

This means SPs will not be notified when a user logs out from the IdP. The SP sessions will remain active until they expire or the user initiates logout from the SP.

3.3 Partial Logout Handling

The IdP does not implement partial logout scenarios. If session lookup fails or an SP is unreachable:

• The IdP proceeds with local logout
• Returns Success status in LogoutResponse
• Does not attempt to contact other SPs

3.4 LogoutResponse Status Codes

Current Limitation: The IdP always returns Success, even if:

• The session was not found
• The session had already expired
• Internal errors occurred

3.5 SLO Configuration Per SP

4. IdP-Initiated SSO

4.1 Support Status

4.2 Initiation Modes

Configured per SP via SSOAllowableInitiation:

4.3 IdP-Initiated Flow

1. User authenticates to IdP (login page)
2. User selects application from portal
3. IdP calls SPLauncher.aspx?sid={appId}
4. IdP generates SAML Response (no InResponseTo)
5. IdP POSTs response to SP's ACS URL
6. RelayState from SP configuration is included

4.4 RelayState Handling

Implementation:

// SPLauncher.aspx.cs
if (!partnerSsoApps.SSORelayState.IsNullOrEmpty())
{
    relayState = partnerSsoApps.SSORelayState;
}
SAML2Util.SendSaml2Assertion(conn, partnerSsoApps, partnerUser, null, relayState, this);

4.5 IdP-Initiated Response Differences

5. Artifact Resolution

The IdP does not implement the SAML 2.0 Artifact Resolution Protocol. All responses are sent directly via HTTP-POST.

6. Metadata

6.1 Metadata Endpoint

URL Pattern: https://{idp-host}/meta/{domain-name}

Example: https://sso.example.com/meta/acme

6.2 Metadata Elements

<?xml version="1.0" ?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
                  entityID="https://sso.example.com/{sha1-hash-of-domain}/">
  <IDPSSODescriptor 
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"
      WantAuthnRequestsSigned="true">
    
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>{base64-cert}</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
    <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
    <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>
    
    <SingleSignOnService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        Location="https://sso.example.com/login/{domain}" />
    <SingleSignOnService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://sso.example.com/login/{domain}" />
        
    <SingleLogoutService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://sso.example.com/SAML/SLOService.aspx" />
    <SingleLogoutService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        Location="https://sso.example.com/SAML/SLOService.aspx" />
  </IDPSSODescriptor>
  
  <ContactPerson contactType="technical">
    <SurName>Support</SurName>
    <EmailAddress>support@surepassid.com</EmailAddress>
  </ContactPerson>
</EntityDescriptor>

6.3 Entity ID Format

The IdP Entity ID is generated as:

{IdP-Root-URL}/{SHA1-Hash-of-Domain}/

Example: https://sso.example.com/a1b2c3d4e5f6.../

This hash-based Entity ID:

• Is unique per tenant/domain
• Doesn't expose the domain name
• Is consistent across requests

7. Error Handling

7.1 SAML Error Status Codes

7.2 Error Behavior

Important: The IdP generally does not send SAML error responses. Instead:

This means SPs will typically see:

• User remains at IdP (no redirect back)
• Session timeout eventually occurs
• No SAML Response received

7.3 Audit Codes

Internal audit codes used for logging (not exposed in SAML responses):

8. Security & Validation

8.1 AuthnRequest Signature Validation

Current Behavior:

• If signature is present and invalid → Request rejected
• If signature is present and valid → Request processed
• If signature is absent → Request processed (warning logged)

Note: The WantAuthnRequestsSigned="true" in metadata is advisory. The IdP does not currently enforce this at runtime per SP. A future enhancement could add per-SP SSORequireSignedAuthnRequests configuration.

8.2 Certificate Requirements for SP Registration

SP Registration: SPs can be registered without providing a certificate. If no certificate is provided:

• AuthnRequest signatures will not be validated
• LogoutRequest signatures will not be validated

8.3 Certificate Rollover

Certificate Rollover Process:

1. Generate new IdP certificate
2. Upload to IdP configuration
3. Republish metadata
4. SPs must manually re-import metadata

8.4 Replay Attack Prevention

Request ID Cache Behavior:

public static bool TryAddRequestId(string requestId)
{
    // Returns true if new request (allowed)
    // Returns false if duplicate within expiration window (rejected)
}

Cache Expiration: Request IDs are tracked for 5 minutes by default. After expiration, the same ID can be reused. Configure via SamlCache.RequestIdExpirationMinutes.

Note: This same request ID cache is also used by the EAM authorization endpoint for request object jti replay protection, so SamlCache.RequestIdExpirationMinutes sets the replay window for both SAML and EAM. See Section 13.

8.5 InResponseTo Validation

The IdP includes InResponseTo in:

• samlp:Response/@InResponseTo
• saml:SubjectConfirmationData/@InResponseTo

9. Configuration Options

9.1 SP-Specific Settings (PartnerSSOApps Table)

9.2 Global Settings (web.config / appSettings)

Note: The SamlCache.* settings apply only to the SAML request ID and SAML session caches (and, for the request ID cache, to EAM replay checks). They do not configure the OIDC session cache, which is in-memory only. See Section 13.

9.3 Feature Flags

10. Known Edge Cases & Limitations

10.1 Compatibility Notes

10.2 Character Encoding

10.3 URL Length Limitations

10.4 Session Management

10.5 Partially Implemented Features

10.6 Multi-Tenancy Considerations

10.7 Known Test Gaps

The following scenarios may need additional testing:

1. Large Assertion Handling

   • Many attributes
   • Many group memberships
   • Very long attribute values

2. Clock Skew Scenarios

   • Server clock significantly ahead/behind
   • Assertion validity edge cases

3. Concurrent Request Handling

   • Same request ID from different IPs
   • Rapid successive requests

4. Character Encoding Edge Cases

   • Non-ASCII domain names
   • Unicode normalization in NameIDs

Appendix A: Test Checklist for SP Test Tool

A.1 Core SSO Tests

• SP-initiated SSO via HTTP-Redirect
• SP-initiated SSO via HTTP-POST
• IdP-initiated SSO
• ForceAuthn enforcement
• Assertion signature validation
• Response signature validation
• NotBefore/NotOnOrAfter validation
• Audience restriction validation
• InResponseTo validation (SP-initiated only)

A.2 NameID Tests

• Email format NameID
• Unspecified format NameID
• Persistent format NameID (verify pairwise uniqueness)
• Transient format NameID (verify uniqueness per session)

A.3 Attribute Tests

• Standard attributes (email, name, phone)
• Group attributes (single and multi-value)
• Role attributes
• Custom attribute mapping

A.4 SLO Tests

• SP-initiated logout (HTTP-POST)
• SP-initiated logout (HTTP-Redirect)
• Session cleanup verification
• Signature validation on LogoutRequest

A.5 Security Tests

• Replay attack detection (same request ID)
• ACS URL mismatch handling
• Invalid signature rejection
• Unsigned request handling (when configured)

A.6 Error Handling Tests

• Invalid SP Issuer
• Missing required configuration
• Certificate errors
• Timeout/session expiration

11. OpenID Connect (OIDC) Capabilities

The IdP exposes a general-purpose, multi-tenant OpenID Connect Provider under oidc/{domain}/*. Clients are registered in the SurePassID Admin Portal; nothing below is configured in this component.

11.1 OIDC Endpoints

11.2 Supported Protocol Features

As advertised by the discovery document:

Supported claims: sub, iss, aud, exp, iat, auth_time, nonce, acr, amr, azp, at_hash, c_hash, sid, name, given_name, family_name, preferred_username, email, email_verified, phone_number, phone_number_verified.

Key constraint: Authorization Code flow with PKCE is the only supported flow. Implicit and hybrid flows are not offered.

11.3 Tenant Gating

The OIDC surface is gated on the tenant's AllowSSO setting. A disabled or misconfigured tenant returns no discovery metadata and issues no tokens, so endpoint URLs and signing certificates are never leaked.

12. Entra ID External Authentication Method (EAM) Capabilities

The EAM surface is an MFA-only OIDC profile consumed by Microsoft Entra ID under eam/{domain}/*. Entra ID performs primary authentication and delegates the second factor to SurePassID.

12.1 EAM Endpoints

12.2 Supported Protocol Features

Supported claims: sub, iss, aud, exp, iat, nonce, acr, amr.

The IdP accepts the user identity either from a signed request object or via id_token_hint parameter mode, and returns a signed id_token by form_post asserting that MFA was completed. acr and amr communicate which authentication methods were used.

12.3 Entra ID Setup

EAM registration on the Entra side, and the matching tenant configuration on the SurePassID side, are both performed outside this component:

• Set up SurePassID MFA for Entra ID: https://support.surepassid.com/how-to-set-up-surepassid-mfa-for-entra-id
• What is SurePassID MFA for Microsoft Entra EAM: https://support.surepassid.com/what-is-surepassid-mfa-microsoft-entra-eam

13. Cache and Session State Topology

The three protocol surfaces do not share a single cache. Despite the SamlCache.* configuration prefix, each protocol uses a different combination of the two underlying caches, which matters when planning multi-node deployments.

13.1 Cache Usage Per Protocol

EAM reuses the SAML request ID cache solely for replay protection, rejecting a request object whose jti has already been seen. This provides parity with the SAML AuthnRequest replay check. EAM does not create or track sessions in the SAML session cache.

OIDC uses an entirely independent OidcSessionCache that tracks relying party participants per session (sid) for back-channel and front-channel logout. It has no dependency on the SAML caches, and the two are initialized separately at application startup because OIDC Single Logout and SAML SLO track session state independently.

13.2 Backing Store and Configuration

13.3 Multi-Node Deployment Considerations

These behaviors are important for load-balanced, distributed, and standalone large-scale deployments:

For load-balanced deployments, either enable sticky sessions so that OIDC logout requests return to the originating node, or confirm that the deployment topology tolerates per-node OIDC session state.

Appendix B: Quick Reference - Endpoint URLs

SAML 2.0

OpenID Connect

Entra ID EAM

Document History

This document is intended for technical teams developing Service Provider and Relying Party test tools for the SurePassID Identity Provider. All tenant, application, and protocol configuration is performed in the SurePassID Admin Portal.