This guide provides step-by-step instructions for configuring SAML SSO with Active Directory Federation Services (AD FS) for the EvTrack Visitor Management System.

Note: If your AD FS instance synchronizes with Microsoft Entra ID (formerly Azure AD), consider using OpenID Connect (OIDC) instead of SAML for enhanced compatibility and features. This guide supports AD FS 2016, 2019, and 2022.

Table of Contents

Prerequisites

Before configuring SAML SSO with AD FS, ensure you have:

  1. Valid FQDN with SSL/HTTPS: Your EvTrack instance must be accessible via HTTPS with a valid SSL certificate
  2. AD FS Server: Active Directory Federation Services 2016, 2019, or 2022 properly configured with HTTPS endpoint
  3. AD FS Administrative Access: Permissions to configure Relying Party Trusts and Claim Rules
  4. EvTrack Administrative Access: Access to modify application.properties configuration
  5. Email Domain Federation: Your organization’s email domain must be federated with AD FS
  6. Network Connectivity: EvTrack server must be able to reach the AD FS server over HTTPS

AD FS Server Configuration

Part 1: Register EvTrack as Relying Party Trust

AD FS uses “Relying Party Trusts” to represent external applications like EvTrack. Follow these steps to register EvTrack:

Step 1: Open AD FS Management Console

  1. Log in to your AD FS server
  2. Open Server Manager → Tools → AD FS Management
  3. Navigate to Trust Relationships → Relying Party Trusts

Step 2: Add Relying Party Trust

  1. In the Actions pane, click Add Relying Party Trust…
  2. The Add Relying Party Trust Wizard will open
  3. Click Start on the Welcome page

Step 3: Select Data Source

  1. Select Enter data about the relying party manually
  2. Click Next

relying party manually” selected

Step 4: Specify Display Name

  1. Display name: Enter EvTrack Visitor Management
  2. Notes (optional): Enter a description like “SAML SSO for EvTrack visitor management system”
  3. Click Next

Step 5: Choose Profile

  1. Select AD FS profile
  2. Click Next

Step 6: Configure Certificate

  1. Leave the certificate configuration empty (optional for SAML)
  2. Click Next

Step 7: Configure URL

  1. Check Enable support for the SAML 2.0 WebSSO protocol
  2. Relying party SAML 2.0 SSO service URL: Enter the Assertion Consumer Service (ACS) URL 
    https://YOUR-FQDN/login/saml2/sso/adfs

    Replace YOUR-FQDN with your actual EvTrack domain (e.g., evtrack.company.com)

  3. Click Next

Important: The URL must match exactly, including the registration ID adfs at the end. This registration ID identifies the AD FS provider in EvTrack’s multi-provider SAML configuration.

Step 8: Configure Identifiers

  1. Relying party trust identifier: Enter evtrack-visitor-management
  2. Click Add to add the identifier to the list
  3. Click Next

Note: This identifier is called the “Entity ID” in SAML terminology and must match the configuration in EvTrack’s application.properties.

Step 9: Choose Access Control Policy

  1. Select an access control policy:
    • Permit Everyone - Allows all authenticated AD users (recommended for initial setup)
    • Permit Specific Group - Restrict access to specific AD security group (recommended for production)
  2. Click Next

Security Recommendation: For production environments, create a dedicated AD security group (e.g., “EvTrack-Users”) and restrict access to members of this group.

Step 10: Review and Finish

  1. Review all settings on the summary page
  2. Ensure Configure claims issuance policy for this application is checked
  3. Click Next
  4. Click Close to finish the wizard

The Claim Rules editor will open automatically. Proceed to Part 2 to configure claim rules.

Part 2: Configure Claim Rules

Claim rules map Active Directory attributes to SAML claims that EvTrack uses to identify and provision users.

Understanding Claim Rules

EvTrack requires these SAML claims for user provisioning:

  • Given Name - User’s first name
  • Surname - User’s last name
  • Email Address or User Principal Name (UPN) - User identifier

AD FS provides two mapping options based on your Active Directory schema:

Use this option if your users have email addresses populated in Active Directory (mail attribute).

Step 1: Add LDAP Attribute Rule

  1. In the Edit Claim Issuance Policy dialog, click Add Rule…
  2. Claim rule template: Select Send LDAP Attributes as Claims
  3. Click Next

Step 2: Configure Rule

  1. Claim rule name: Enter EvTrack User Attributes (Email)
  2. Attribute store: Select Active Directory

  3. Mapping of LDAP attributes to outgoing claim types:

    LDAP Attribute Outgoing Claim Type
    Given-Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    Surname http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    E-Mail-Addresses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  4. Click Finish

Step 3: Transform Email to Name ID

EvTrack expects the user identifier in the SAML Name ID field:

  1. Click Add Rule… again
  2. Claim rule template: Select Transform an Incoming Claim
  3. Click Next
  4. Claim rule name: Enter Transform Email to Name ID
  5. Incoming claim type: Select E-Mail Address
  6. Outgoing claim type: Select Name ID
  7. Outgoing name ID format: Select Email
  8. Pass through all claim values: Checked
  9. Click Finish

Option B: UPN-Based Identifier (Alternative)

Use this option if email addresses are not populated or you prefer to use User Principal Names.

Step 1: Add LDAP Attribute Rule

  1. In the Edit Claim Issuance Policy dialog, click Add Rule…
  2. Claim rule template: Select Send LDAP Attributes as Claims
  3. Click Next

Step 2: Configure Rule

  1. Claim rule name: Enter EvTrack User Attributes (UPN)
  2. Attribute store: Select Active Directory

  3. Mapping of LDAP attributes to outgoing claim types:

    LDAP Attribute Outgoing Claim Type
    Given-Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    Surname http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    User-Principal-Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
  4. Click Finish

Step 3: Transform UPN to Name ID

  1. Click Add Rule… again
  2. Claim rule template: Select Transform an Incoming Claim
  3. Click Next
  4. Claim rule name: Enter Transform UPN to Name ID
  5. Incoming claim type: Select UPN
  6. Outgoing claim type: Select Name ID
  7. Outgoing name ID format: Select Unspecified
  8. Pass through all claim values: Checked
  9. Click Finish

Step 4: Finalize Claim Rules

  1. Click OK to close the Edit Claim Issuance Policy dialog
  2. The claim rules are now configured

Important: Choose either Option A (Email) or Option B (UPN), not both. Using both configurations may cause conflicts in user identification.

Part 3: Optional - Group Membership Claims

If you want to use Active Directory groups for role-based authorization in EvTrack:

Step 1: Add Group Claim Rule

  1. Right-click your EvTrack Relying Party Trust → Edit Claim Issuance Policy…
  2. Click Add Rule…
  3. Claim rule template: Select Send Group Membership as a Claim
  4. Click Next

Step 2: Configure Group Claim

  1. Claim rule name: Enter EvTrack Admin Group
  2. User’s group: Click Browse and select your AD group (e.g., EvTrack-Admins)
  3. Outgoing claim type: Enter groups - the claim must be delivered as the SAML attribute name groups, because EvTrack reads the groups assertion attribute and maps each of its values to a granted authority (e.g., ROLE_ADMIN)
  4. Outgoing claim value: Enter ROLE_ADMIN (or your desired role identifier)
  5. Click Finish

Step 3: Repeat for Additional Roles

Create additional rules for other security groups as needed (e.g., EvTrack-Users, EvTrack-Managers).

Note: Group claim integration requires additional configuration in EvTrack’s authorization logic. Contact EvTrack support for guidance on role mapping.

Part 4: Obtain Federation Metadata URL

EvTrack needs the AD FS federation metadata URL to configure trust automatically.

Step 1: Locate Federation Metadata Endpoint

  1. In AD FS Management, navigate to Service → Endpoints
  2. Locate the Metadata section
  3. Find the endpoint with Type: Federation Metadata
  4. The URL Path will be: /FederationMetadata/2007-06/FederationMetadata.xml

Step 2: Construct Full Metadata URL

Your federation metadata URL will be:

https://adfs.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml

Replace adfs.yourdomain.com with your actual AD FS server FQDN.

Step 3: Verify Metadata Accessibility

  1. Open a web browser
  2. Navigate to the metadata URL
  3. You should see XML content starting with <EntityDescriptor>
  4. Verify the URL is accessible from the EvTrack server (test from the EvTrack server if possible)

Important: This metadata URL must be accessible from the EvTrack server over HTTPS. If your AD FS server is internal-only, ensure the EvTrack server can reach it via network routing or VPN.

EvTrack Application Configuration

Update application.properties

Add or update the following configuration in your application.properties file:

# ====================
# SSO Configuration
# ====================
# Enable SAML SSO (set to true to activate)
evtrack.security.config.sso.enable=true
# Auto-provision new users from SSO (recommended)
evtrack.security.config.sso.auto-provision-new-user=true
# Auto-update username from SSO provider
evtrack.security.config.sso.auto-update-entity-username=true
# AD FS SAML Service Provider Configuration
spring.security.saml2.relyingparty.registration.adfs.entity-id=evtrack-visitor-management
spring.security.saml2.relyingparty.registration.adfs.assertingparty.metadata-uri=https://adfs.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml
# Signing Credentials for SAML Logout (Required for Single Logout)
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].private-key-location=file:/path/to/saml-signing.key
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].certificate-location=file:/path/to/saml-signing.crt
# Single Logout Configuration
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.url=https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.adfs.singlelogout.response-url={baseUrl}/logout/saml2/slo

Important: Replace adfs.yourdomain.com with your actual AD FS server FQDN. Replace /path/to/ with the actual paths to your SAML signing credentials (see SLO Configuration section below).

Configuration Notes

  1. Registration ID: The configuration uses adfs as the registration ID. This must match the ACS URL you configured in AD FS: https://YOUR-FQDN/login/saml2/sso/adfs

  2. Entity ID: The entity-id value evtrack-visitor-management must match the Relying Party Trust Identifier you configured in AD FS

  3. Metadata URI: EvTrack will automatically fetch the AD FS configuration from this URL, including:
    • Single Sign-On endpoint
    • Signing certificates
    • Supported bindings
    • Name ID formats

  4. Password Reset: When SSO is enabled (evtrack.security.config.sso.enable=true), the password reset functionality at /auth/password-reset/** is automatically disabled

  5. Auto-provisioning: When enabled, new users will be automatically created in EvTrack upon their first SSO login with attributes populated from SAML claims

  6. Username Updates: When enabled, user information (first name, last name, email) will be synchronized from AD FS on each login

EvTrack Endpoints for AD FS Configuration

When configuring AD FS, you need to provide these EvTrack endpoints:

Endpoint Type URL Purpose
Assertion Consumer Service (ACS) https://YOUR-FQDN/login/saml2/sso/adfs Receives SAML authentication responses
Entity ID evtrack-visitor-management Unique identifier for EvTrack SP
SP Metadata https://YOUR-FQDN/saml2/metadata/adfs Service Provider metadata (optional)
Single Logout Response https://YOUR-FQDN/logout/saml2/slo Receives SAML logout responses

Note: The registration ID adfs in these URLs can be customized, but must match across all configurations in both AD FS and EvTrack.

SAML Single Logout (SLO) Configuration

Single Logout allows users to log out from both EvTrack and AD FS with a single logout action. This section is * *required** for logout functionality to work correctly.

Why SLO Configuration is Required

SAML logout requires the Service Provider (EvTrack) to sign logout requests using a private key. Without proper signing credentials configured, you will encounter this error:

org.springframework.security.saml2.Saml2Exception: java.lang.IllegalArgumentException:
Failed to resolve any signing credential

Step 1: Generate Signing Credentials

You must generate your own private key and self-signed certificate for signing SAML logout requests:

# Generate RSA 2048-bit private key and self-signed certificate (valid for 10 years)
openssl req -newkey rsa:2048 -nodes \
  -keyout saml-signing.key \
  -x509 -days 3650 \
  -out saml-signing.crt \
  -subj "/C=US/ST=State/L=City/O=YourOrganization/OU=IT/CN=evtrack-visitor-management"

This generates two files:

  • saml-signing.key - Private key (keep this secure and never share it)
  • saml-signing.crt - Public certificate (upload this to AD FS if required)

Certificate Format Requirements:

  • Private key must be in PKCS#8 PEM format (unencrypted)
  • Certificate must be in PEM format (Base64-encoded with BEGIN/END markers)
  • If you have a DER-format certificate (.cer), convert it to PEM: 
    openssl x509 -inform DER -in certificate.cer -out certificate.pem -outform PEM

Step 2: Configure Signing Credentials in EvTrack

Add the signing credentials to your application.properties:

# Signing Credentials for SAML Logout (Required)
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].private-key-location=file:/absolute/path/to/saml-signing.key
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].certificate-location=file:/absolute/path/to/saml-signing.crt

Important Notes:

  • Use absolute file paths or paths relative to the application working directory
  • The file: protocol is required when referencing files outside the classpath
  • Ensure the application has read permissions for these files

Step 3: Configure Single Logout Endpoint

AD FS typically uses the WS-Federation logout endpoint for SAML logout:

# Single Logout URL and Binding
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.url=https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.adfs.singlelogout.response-url={baseUrl}/logout/saml2/slo

AD FS Logout URL Format:

AD FS uses the WS-Federation signout endpoint for compatibility:

  • Format: https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0
  • Replace adfs.yourdomain.com with your AD FS server FQDN

Binding Configuration by Provider:

  • AD FS: Use REDIRECT (most common)
  • Azure Entra ID: Use REDIRECT
  • Okta: Use POST
  • Other providers: Check the Identity Provider’s metadata XML for the SingleLogoutService binding

To verify the correct logout URL and binding, check your AD FS metadata URL for:


<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                     Location="https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0"/>

Step 4: Upload Certificate to AD FS (If Required)

Some AD FS configurations require uploading the public certificate to verify signed logout requests. Check with your AD FS administrator.

If certificate upload is required:

  1. Open AD FS Management
  2. Navigate to Trust Relationships → Relying Party Trusts
  3. Right-click EvTrack Visitor Management → Properties
  4. Go to the Signature tab
  5. Click Add… and select your saml-signing.crt file
  6. Click OK to save

Note: Not all AD FS versions require this step. Test logout functionality first; if it fails, upload the certificate.

Complete Configuration Example

Here’s a complete working example for AD FS with Single Logout:

# SSO Enable
evtrack.security.config.sso.enable=true
evtrack.security.config.sso.auto-provision-new-user=true
evtrack.security.config.sso.auto-update-entity-username=true
# AD FS SAML Configuration
spring.security.saml2.relyingparty.registration.adfs.entity-id=evtrack-visitor-management
spring.security.saml2.relyingparty.registration.adfs.assertingparty.metadata-uri=https://adfs.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml
# Signing Credentials (Required for logout)
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].private-key-location=file:/etc/evtrack/saml-signing.key
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].certificate-location=file:/etc/evtrack/saml-signing.crt
# Single Logout Configuration
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.url=https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0
spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.adfs.singlelogout.response-url={baseUrl}/logout/saml2/slo

Security Best Practices

  1. Private Key Security:
    • Store private keys outside the application directory
    • Set restrictive file permissions: chmod 600 saml-signing.key
    • Never commit private keys to version control
    • Consider using a secrets management system (Azure Key Vault, HashiCorp Vault)
  2. Certificate Rotation:
    • Set calendar reminders before certificate expiration
    • Generate new certificates well before expiration
    • Update both EvTrack configuration and AD FS settings
    • Test the new configuration before removing old certificates
  3. Backup:
    • Keep secure backups of your signing credentials
    • Document the certificate generation process
    • Store backup copies in a secure location

SSL Certificate Configuration

SSL can be configured in two ways:

Option 1: Web Application Firewall (WAF) / Load Balancer

If SSL termination is handled by a WAF or load balancer:

  • Ensure the WAF/LB forwards the proper headers
  • EvTrack is configured to handle forwarded headers with server.forward-headers-strategy=native

Option 2: Direct Server SSL

If SSL is configured directly on the EvTrack server:

  1. Obtain the following certificate files from your certificate provider:
    • ca_bundle.crt - Certificate Authority bundle
    • certificate.crt - SSL certificate
    • private.key - Private key
  2. Convert to PKCS12 format (if needed): 
    openssl pkcs12 -export -out keystore.p12 -inkey private.key -in certificate.crt -certfile ca_bundle.crt -name evtrack
  3. Update application.properties: 
    server.ssl.enabled=true
server.ssl.key-store-type=PKCS12
server.ssl.key-store=keystore.p12
server.ssl.key-store-password=YOUR_KEYSTORE_PASSWORD
server.ssl.key-alias=evtrack

Note: On an onsite server the web service listens on port 5443 by default (server.port=5443). If HTTPS does not come up after a restart, verify that the keystore file is at the location configured in application.properties, that the keystore password is correct, and that port 5443 is open in the firewall and not used by another service.

For detailed SSL configuration instructions, refer to: https://docs.evtrack.com/onsite-deployment/https-configuration

Testing the Configuration

Step 1: Restart EvTrack

After updating the configuration, restart the EvTrack application to apply changes:

# Systemd service
sudo systemctl restart evtrack

# Or if running directly
./mvnw spring-boot:run

Step 2: Access SSO Login Page

  1. Open a web browser
  2. Navigate to https://YOUR-FQDN/login/sso
  3. You should see the EvTrack login page with an “Login with AD FS” button

Step 3: Test Authentication

  1. Click the Login with AD FS button
  2. You will be redirected to your AD FS login page
  3. Enter your Active Directory credentials (username@domain.com and password)
  4. If using Windows Integrated Authentication, you may be logged in automatically
  5. After successful authentication, you should be redirected to the EvTrack dashboard

Step 4: Verify User Provisioning

If auto-provisioning is enabled (evtrack.security.config.sso.auto-provision-new-user=true):

  1. Log in with a user account that doesn’t exist in EvTrack yet
  2. Verify the user is created automatically in EvTrack
  3. Check that user attributes are populated correctly:
    • First Name (from givenname claim)
    • Last Name (from surname claim)
    • Email or Username (from emailaddress or upn claim)

Step 5: Test Single Logout

  1. After logging in successfully, click the logout button in EvTrack
  2. You should be redirected to AD FS and logged out
  3. Attempting to access protected EvTrack pages should require re-authentication
  4. Verify you’re also logged out of other AD FS-connected applications

Troubleshooting

Common AD FS-Specific Issues

1. “Page cannot be displayed” or redirect loop after AD FS login

Possible Causes:

  • Incorrect ACS URL in AD FS configuration
  • SSL/HTTPS not properly configured
  • Network connectivity issues

Solutions:

  • Verify the ACS URL in AD FS exactly matches: https://YOUR-FQDN/login/saml2/sso/adfs
  • Ensure your FQDN resolves correctly and is accessible over HTTPS
  • Check AD FS Event Viewer logs (Applications and Services Logs → AD FS → Admin)
  • Verify SSL certificate is valid and trusted by browsers
  • Test network connectivity from user’s location to both AD FS and EvTrack servers

2. “Invalid SAML Response” error

Possible Causes:

  • Entity ID mismatch
  • Clock synchronization issues
  • Incorrect metadata URL

Solutions:

  • Verify Entity ID in EvTrack (evtrack-visitor-management) matches the Relying Party Trust Identifier in AD FS
  • Check system time synchronization on both AD FS and EvTrack servers (SAML is time-sensitive, typically ±5 minutes) 
    # Check time on Linux
timedatectl status
# Sync time if needed
sudo ntpdate -s time.nist.gov
  • Verify the metadata URL is correct and accessible from EvTrack server
  • Check that the metadata URL returns valid XML (not an error page)

3. Claim mapping issues - Missing name or email

Possible Causes:

  • LDAP attributes not populated in Active Directory
  • Incorrect claim rule configuration
  • Attribute name mismatch

Solutions:

  • Verify LDAP attribute names in your Active Directory schema: 
    # PowerShell - Check user attributes
Get-ADUser -Identity "username" -Properties GivenName,Surname,EmailAddress,UserPrincipalName
  • Ensure the attributes have values (not blank)
  • Review claim rules in AD FS Management → Relying Party Trusts → EvTrack → Edit Claim Issuance Policy
  • Check exact LDAP attribute names used in claim rules (case-sensitive):
    • Given-Name (not GivenName)
    • Surname (not LastName)
    • E-Mail-Addresses (not Email or Mail)
    • User-Principal-Name (not UPN)

4. SAML attribute debugging

Enable SAML response debugging to see what claims AD FS is sending:

In EvTrack: Add to application.properties:

logging.level.org.springframework.security.saml2=DEBUG

In AD FS:

  1. Open Event Viewer on AD FS server
  2. Navigate to Applications and Services Logs → AD FS → Admin
  3. Look for Event ID 1200 (successful token issuance) or 364 (failed authentication)
  4. Review the claim values in the event details

Browser SAML Tracer (Advanced): Install a SAML tracer browser extension (e.g., SAML-tracer for Firefox/Chrome) to inspect SAML requests and responses in real-time.

5. “Failed to resolve any signing credential” error during logout

Possible Causes:

  • Missing or incorrectly configured signing credentials
  • Incorrect file paths
  • File permission issues
  • Certificate format issues

Solutions:

  • Verify signing credentials are configured in application.properties: 
    spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].private-key-location=file:/path/to/saml-signing.key
spring.security.saml2.relyingparty.registration.adfs.signing.credentials[0].certificate-location=file:/path/to/saml-signing.crt
  • Check that private key and certificate files exist and are readable: 
    ls -la /path/to/saml-signing.*
# Ensure read permissions (at least 644 for certificate, 600 for private key)
chmod 600 /path/to/saml-signing.key
chmod 644 /path/to/saml-signing.crt
  • Verify file paths are absolute paths or correct relative paths
  • Ensure certificate is in PEM format (starts with -----BEGIN CERTIFICATE-----)
  • Check application startup logs for certificate loading errors

6. “Missing certificates or unrecognized format” error

Possible Causes:

  • Certificate file is in DER (binary) format instead of PEM format

Solutions: Convert the certificate to PEM format:

openssl x509 -inform DER -in certificate.cer -out certificate.pem -outform PEM

Update configuration to use certificate.pem instead of certificate.cer

7. Logout redirects to AD FS but fails to complete

Possible Causes:

  • Incorrect logout URL
  • Incorrect logout binding
  • Missing logout response URL

Solutions:

  • Verify logout URL format for AD FS: https://adfs.yourdomain.com/adfs/ls/?wa=wsignout1.0
  • Ensure binding is set to REDIRECT: 
    spring.security.saml2.relyingparty.registration.adfs.assertingparty.singlelogout.binding=REDIRECT
  • Verify logout response URL is configured: 
    spring.security.saml2.relyingparty.registration.adfs.singlelogout.response-url={baseUrl}/logout/saml2/slo
  • Check AD FS metadata for the correct SingleLogoutService endpoint

8. Certificate validation errors

Possible Causes:

  • AD FS using self-signed certificate
  • Certificate trust chain issues
  • Expired certificates

Solutions:

  • If AD FS uses a self-signed certificate, add it to EvTrack’s Java truststore: 
    # Export AD FS certificate from browser or AD FS server
# Import into Java truststore
keytool -import -alias adfs-cert -file adfs.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
  • Verify AD FS certificate validity: 
    openssl s_client -connect adfs.yourdomain.com:443 -showcerts
  • Check certificate expiration dates on both AD FS and EvTrack

9. Network connectivity issues

Possible Causes:

  • Firewall blocking HTTPS traffic
  • DNS resolution issues
  • Proxy configuration

Solutions:

  • Test connectivity from EvTrack server to AD FS: 
    curl -v https://adfs.yourdomain.com/FederationMetadata/2007-06/FederationMetadata.xml
  • Check firewall rules allow HTTPS (port 443) to AD FS server
  • Verify DNS resolution: 
    nslookup adfs.yourdomain.com
  • If using a proxy, configure Java proxy settings: 
    -Dhttps.proxyHost=proxy.company.com
-Dhttps.proxyPort=8080

Enable Debug Logging

For comprehensive troubleshooting, enable debug logging in application.properties:

# SAML Protocol Debugging
logging.level.org.springframework.security.saml2=DEBUG
# HTTP Request Debugging
logging.level.org.springframework.web=DEBUG

Common Error Messages and Solutions

Error Message Cause Solution
SAML 2.0 response validation failed Clock skew or invalid signature Synchronize clocks, verify metadata URL
InResponseToField does not correspond to sent message Session timeout or replay attack detection Increase session timeout, check for duplicate requests
Audience validation failed Entity ID mismatch Verify Entity ID matches in both AD FS and EvTrack
No assertion consumer service found Incorrect ACS URL Verify ACS URL matches exactly
Unable to decrypt NameID Encryption mismatch Check if AD FS is encrypting assertions (usually not needed)

Security Considerations

Network Security

  1. HTTPS Enforcement:
    • Ensure HTTPS is enforced for all SSO-related endpoints
    • Use valid, trusted SSL certificates (not self-signed for production)
    • Configure HSTS (HTTP Strict Transport Security) headers
  2. Network Segmentation:
    • Place AD FS servers in a secure network zone
    • Restrict network access to AD FS management interfaces
    • Use firewall rules to limit connections

Access Control

  1. User Access:
    • Regularly audit SSO user access logs
    • Implement proper role-based access control (RBAC) in EvTrack
    • Use AD security groups to control who can access EvTrack
  2. Multi-Factor Authentication (MFA):
    • Configure MFA in AD FS for enhanced security
    • Require MFA for administrative accounts
    • Consider requiring MFA for all EvTrack users
  3. Access Control Policies:
    • Use AD FS Access Control Policies to restrict access by:
      • Device compliance
      • Network location
      • Group membership
      • Time of day

Certificate Management

  1. Certificate Lifecycle:
    • Monitor certificate expiration dates (both AD FS and SAML signing)
    • Implement automated certificate renewal processes
    • Test certificate rollover procedures
  2. Private Key Protection:
    • Store private keys with restrictive permissions (chmod 600)
    • Use hardware security modules (HSMs) for high-security environments
    • Never commit private keys to version control

Monitoring and Auditing

  1. Log Monitoring:
    • Enable and monitor AD FS audit logs
    • Monitor EvTrack application logs for authentication events
    • Set up alerts for failed authentication attempts
  2. Regular Reviews:
    • Conduct regular security audits of SAML configuration
    • Review and update claim rules as needed
    • Audit user provisioning and access patterns
  3. Incident Response:
    • Have a plan for responding to authentication failures
    • Document rollback procedures for configuration changes
    • Maintain emergency access procedures (break-glass accounts)

Additional Resources

Microsoft AD FS Documentation

EvTrack Documentation

SAML Resources

Support

For additional assistance with AD FS SAML SSO configuration, please contact EvTrack support with:

  • Your application.properties SSO configuration (excluding sensitive data like private keys)
  • Any error messages from the EvTrack application logs
  • AD FS Event Viewer logs showing authentication attempts
  • The Federation Metadata URL from AD FS
  • Network diagram showing connectivity between users, AD FS, and EvTrack

Back to top

Copyright EvTrack. All rights reserved.

Page last modified: 2026-09-28 15:32.