Skip to main content
Version: 3.1

SAML Authentication with ADFS

This guide explains how to configure Cortex Archive to authenticate users using SAML 2.0 with Active Directory Federation Services (ADFS).

The process consists of:

  1. Configuring Cortex Archive to trust your Identity Provider (IdP)
  2. Configuring ADFS to trust Cortex Archive as a relying party
  3. Validating identity claims and login behavior

Prerequisites​

Before starting, ensure the following are available:

  • An ADFS server connected to your Active Directory domain
  • A valid, unexpired certificate for SAML signing and encryption
    • The PFX (with private key) must be available on the Cortex Archive server
    • The public certificate only must be available on the ADFS server
  • Administrative access to both the Cortex Archive host and the ADFS management console

Step 1 - Configure Cortex Archive to Use SAML​

Enable SAML authentication​

In appsettings.json, set the authentication type to saml:

{
  "Authentication": {
    "Type": "saml"
  }
}

Configure SAML identity provider settings​

Under the Authentication:Saml block, configure the following:

  • IdPMetadataUri - the URL to your ADFS federation metadata. For most environments:

    https://YOUR-ADFS-SERVER/FederationMetadata/2007-06/FederationMetadata.xml

  • PublicUri - the externally accessible URL users use to reach Cortex Archive (for example: https://archive.company.com)

  • CertificateFile (recommended) - full path to the .pfx certificate file containing the private key

  • CertificatePassword - the password used when exporting the certificate

Example configuration:

{
  "Authentication": {
    "Type": "saml",
    "Saml": {
      "IdPMetadataUri": "https://adfs.company.com/FederationMetadata/2007-06/FederationMetadata.xml",
      "PublicUri": "https://archive.company.com",
      "CertificateFile": "C:\\certs\\saml-signing.pfx",
      "CertificatePassword": "your_certificate_password"
    }
  }
}

Step 2 - Configure ADFS as a Relying Party​

On the ADFS server:

  1. Create a new Relying Party Trust using manual configuration.
  2. When prompted:
    • Entity ID / Relying Party Identifier - use the same value as PublicUri
    • Signing certificate - upload the public certificate only (no private key)
  3. Accept defaults unless your organization has specific security requirements.

Step 3 - Configure Claims Mapping​

Cortex Archive needs a stable identifier to match incoming users to existing accounts.

At minimum, map:

  • LDAP attribute: SAM-Account-Name
  • Outgoing claim type: Name ID

This allows Cortex Archive to match users by their Windows username. Additional claims may be mapped depending on your setup (email-based lookup, custom identifiers, etc.).

Optional Configuration Settings​

Most environments work with the default configuration. If authentication fails or behaves unexpectedly, the following settings may help.

Settings are listed in Block:SubBlock:Setting format:

  • In appsettings.json - use nested JSON blocks
  • In environment variables - replace : with __ (for example, Authentication__Saml__ForceAuthn)
SettingDescription
Authentication:LookUpBySet to Email if users should be identified by email address instead of username
Authentication:IdentifierClaimThe name of the claim sent by ADFS that identifies the user (for example: emailAddress or a URI-style claim)
Authentication:Saml:CertificateValidationModeSet to None to disable certificate validation - not recommended for production
Authentication:Saml:RevocationModeControls certificate revocation checking behavior
Authentication:Saml:ForceAuthnForces credential entry at the IdP on every login, even if the user has an active session

Troubleshooting​

If login fails, users are redirected unexpectedly, or claims are not recognised, see:

SAML with ADFS Troubleshooting

A video walkthrough of the full ADFS configuration is also available on that page.