SAML Single Sign-On (Azure Entra ID)

This guide provides step-by-step instructions for configuring SAML SSO with Azure Entra ID (formerly Azure AD) for the EvTrack Visitor Management System.

Prerequisites
Azure Entra ID Configuration
EvTrack Application Configuration
SAML Single Logout (SLO) Configuration
SSL Certificate Configuration
Testing the Configuration
Troubleshooting
Security Considerations

Prerequisites

Valid FQDN with SSL/HTTPS: Your EvTrack instance must be accessible via HTTPS with a valid SSL certificate
Azure Entra ID Access: Administrative access to configure enterprise applications
EvTrack Administrative Access: Access to modify application.properties

Azure Entra ID Configuration

Step 1: Create Enterprise Application

Log in to the Azure Portal
Navigate to Azure Active Directory → Enterprise Applications
Click New application → Create your own application
Enter name: “EvTrack Visitor Management”
Select Integrate any other application you don’t find in the gallery
Click Create

Step 2: Configure SAML Settings

In your enterprise application, go to Single sign-on
Select SAML as the single sign-on method

Configure the following in Basic SAML Configuration:

Setting	Value
Identifier (Entity ID)	`evtrack-visitor-management`
Reply URL (Assertion Consumer Service URL)	`https://YOUR-FQDN/login/saml2/sso/entra`
Sign on URL (optional)	`https://YOUR-FQDN/login/sso`

Note: Replace YOUR-FQDN with your actual fully qualified domain name (e.g., evtrack.company.com)

Step 3: Configure User Attributes & Claims

The default claims are usually sufficient, but ensure these are mapped:

Unique User Identifier (Name ID): user.userprincipalname
Given Name: user.givenname
Surname: user.surname
Email Address: user.mail

Step 4: Download Federation Metadata

In the SAML Certificates section, locate App Federation Metadata Url
Copy this URL - you’ll need it for EvTrack configuration
Download the Certificate (Base64) if manual certificate configuration is required

The metadata URL will look similar to:

https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}

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

# Azure Entra SAML Service Provider Configuration
spring.security.saml2.relyingparty.registration.entra.entity-id=evtrack-visitor-management
spring.security.saml2.relyingparty.registration.entra.assertingparty.metadata-uri=https://login.microsoftonline.com/{YOUR-TENANT-ID}/federationmetadata/2007-06/federationmetadata.xml?appid={YOUR-APP-ID}
# Signing Credentials for SAML Logout (Required for Single Logout to work)
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].private-key-location=file:/path/to/your-private.key
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].certificate-location=file:/path/to/your-certificate.crt
# Single Logout Configuration
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.url=https://login.microsoftonline.com/{YOUR-TENANT-ID}/saml2
# IMPORTANT: Azure Entra requires REDIRECT binding (other providers like Okta may require POST)
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.entra.singlelogout.response-url={baseUrl}/logout/saml2/slo

Important: Replace {YOUR-TENANT-ID} and {YOUR-APP-ID} with the actual values from your Azure Entra ID configuration.

Configuration Notes

Password Reset: When SSO is enabled (evtrack.security.config.sso.enable=true), the password reset functionality at /auth/password-reset/** is automatically disabled
Auto-provisioning: When enabled, new users will be automatically created in EvTrack upon their first SSO login
Username Updates: When enabled, user information will be synchronized from the SSO provider on each login

SAML Single Logout (SLO) Configuration

Single Logout allows users to log out from both EvTrack and Azure Entra ID 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 Azure Entra)

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.entra.signing.credentials[0].private-key-location=file:/absolute/path/to/saml-signing.key
spring.security.saml2.relyingparty.registration.entra.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 Binding

Azure Entra ID requires HTTP-Redirect binding for single logout (this differs from other providers like Okta which use POST):

# Single Logout URL and Binding
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.url=https://login.microsoftonline.com/{YOUR-TENANT-ID}/saml2
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.entra.singlelogout.response-url={baseUrl}/logout/saml2/slo

Binding Configuration by Provider:

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 binding, check your IdP’s metadata URL for:

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                     Location="https://login.microsoftonline.com/.../saml2"/>

Step 4: Upload Certificate to Azure Entra ID

The public certificate must be uploaded to Azure Entra so it can verify the signed logout requests:

Go to Azure Portal → Enterprise Applications → Your EvTrack application
Navigate to Single sign-on → SAML Certificates
In the Verification certificates or SAML Signing Certificate section:
- Click Upload certificate
- Select your saml-signing.crt file
- Save the configuration

Why this is necessary: Azure Entra uses your public certificate to cryptographically verify that logout requests are genuinely coming from your EvTrack instance.

Complete Configuration Example

Here’s a complete working example for Azure Entra ID 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
# Azure Entra SAML Configuration
spring.security.saml2.relyingparty.registration.entra.entity-id=evtrack-visitor-management
spring.security.saml2.relyingparty.registration.entra.assertingparty.metadata-uri=https://login.microsoftonline.com/{YOUR-TENANT-ID}/federationmetadata/2007-06/federationmetadata.xml?appid={YOUR-APP-ID}
# Signing Credentials (Required for logout)
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].private-key-location=file:/etc/evtrack/saml-signing.key
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].certificate-location=file:/etc/evtrack/saml-signing.crt
# Single Logout Configuration
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.url=https://login.microsoftonline.com/{YOUR-TENANT-ID}/saml2
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.entra.singlelogout.response-url={baseUrl}/logout/saml2/slo

Security Best Practices

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)
Certificate Rotation:
- Set calendar reminders before certificate expiration
- Generate new certificates well before expiration
- Update both EvTrack configuration and Azure Entra settings
- Test the new configuration before removing old certificates
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:

Obtain the following certificate files from your certificate provider:
- ca_bundle.crt - Certificate Authority bundle
- certificate.crt - SSL certificate
- private.key - Private key

Convert to PKCS12 format (if needed):

openssl pkcs12 -export -out keystore.p12 -inkey private.key -in certificate.crt -certfile ca_bundle.crt -name evtrack

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

Restart EvTrack after updating the configuration
Navigate to https://YOUR-FQDN/login/sso
Click the “Login with Microsoft” button
Authenticate with your Azure Entra ID credentials
Verify successful redirect to the EvTrack dashboard

Test User Provisioning

If auto-provisioning is enabled:

Log in with a user that doesn’t exist in EvTrack
Verify the user is created automatically
Check that user attributes (name, email) are populated correctly

Troubleshooting

Common Issues

“Page cannot be displayed” after Azure login
- Verify the Reply URL in Azure matches exactly: https://YOUR-FQDN/login/saml2/sso/entra
- Ensure SSL certificate is valid and trusted
- Check that the FQDN is accessible from the user’s location
“Invalid SAML Response” error
- Verify the Entity ID matches: evtrack-visitor-management
- Ensure the metadata URL is correctly formatted with your tenant and app IDs
- Check system time synchronization (SAML is time-sensitive)
User provisioning fails
- Verify evtrack.security.config.sso.auto-provision-new-user=true
- Check application logs for specific error messages
- Ensure required user attributes are being sent from Azure

SAML Single Logout Issues

“Failed to resolve any signing credential” error during logout
- Cause: Missing or incorrectly configured signing credentials
- Solution:
  - Verify signing credentials are configured in application.properties
  - Check that private key and certificate files exist and are readable
  - Ensure file paths are correct (absolute paths or relative to working directory)
  - Verify certificate is in PEM format (not DER/binary format)
  - Check application startup logs for certificate loading errors
“Missing certificates or unrecognized format” error
- Cause: Certificate file is in DER (binary) format instead of PEM format
- Solution: Convert the certificate to PEM format:
```
openssl x509 -inform DER -in certificate.cer -out certificate.pem -outform PEM
```
  Then update configuration to use certificate.pem
Logout redirects to Azure but fails to complete
- Cause: Incorrect logout binding configuration
- Solution:
  - For Azure Entra: Verify binding is set to REDIRECT (not POST)
  - Check IdP metadata XML to confirm the correct binding
  - Ensure singlelogout.response-url is configured: {baseUrl}/logout/saml2/slo

Enable Debug Logging

For troubleshooting, add to application.properties:

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

Security Considerations

Network Security
- Ensure HTTPS is enforced for all SSO-related endpoints
User Access
- Regularly audit SSO user access
- Implement proper role-based access control (RBAC)
- Consider implementing conditional access policies in Azure

Additional Resources

Support

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

Your application.properties SSO configuration (excluding sensitive data)
Any error messages from the application logs
The App Federation Metadata URL from Azure

Using Active Directory Federation Services instead of Azure Entra ID? See SAML Single Sign-On (AD FS).

Table of Contents