Skip to main content
Version: 2.7

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

A walkthrough video is provided at the end of this page.

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:
    • The Cortex Archive host
    • 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 settings:

  • 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 access Cortex Archive (for example: https://archive.company.com)

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

  • CertificatePassword Password used when exporting the certificate

Example:

{
  "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:

  • Create a new Relying Party Trust

  • Choose manual configuration

  • When prompted:

    • Entity ID / Relying Party Identifier: use the same value as PublicUri

    • Signing certificate: upload the public certificate (no private key)

    • Accept defaults unless your organization has specific security requirements

Step 3: Configure Claims Mapping​

Cortex Archive requires a stable identifier to associate incoming users with existing accounts.

At minimum:

  • Map SAM-Account-Name -> Name ID

  • This allows Cortex Archive to match users based on their Windows username.

    • Additional claims may be mapped depending on your configuration (email-based lookup, custom identifiers, etc.).

Optional Configuration Settings​

Most environments work with the default configuration. If authentication fails or behaves unexpectedly, the following options may be required.

Settings are shown using the format:

Block:SubBlock:Setting

When using:

  • appsettings.json -> nested JSON blocks

  • Environment variables -> Block__SubBlock__Setting

  • Authentication:LookUpBy Set to Email if users should be identified by email address instead of username

  • Authentication:IdentifierClaim Name of the claim sent by ADFS that identifies the user (for example: emailAddress or a URI-style claim)

  • Authentication:Saml:CertificateValidationMode Set to None to disable certificate validation (not recommended for production)

  • Authentication:Saml:RevocationMode Controls certificate revocation checking behavior

  • Authentication:Saml:ForceAuthn Forces credential entry at the IdP on every login, even if the user already has an active session

Troubleshooting​

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

  • Review the Cortex Archive logs

  • Verify claim mappings in ADFS

  • Confirm certificate validity and trust chain

See Administration Authentication Troubleshooting for common issues and diagnostics.

Video Walkthrough​

The following video demonstrates a full end-to-end configuration using ADFS:

```