Skip to main content

SAML with ADFS

Prerequisites​

  • An ADFS server connected to your intended Active Directory domain
  • An unexpired certificate to use for signing/encrypting the SAML response/assertions. The private key should be exported and available on the server that will run Cortex and only the certificate exported and available on the AD FS server.

Configure Cortex to find the IdP​

  1. In appsettings.json, set the Authentication type to "saml":

    {
      // ...
      "Authentication": {
        "Type": "saml",
        // ...
      }
    }

  2. In the "Saml" settings block (in the "Authentication" block), set values for the following settings:

    • IdPMetadataUri - the URI of the IdP's metadata. For most ADFS servers, this will be https://YOUR-ADFS-SERVER-NAME/FederationMetadata/2007-06/FederationMetadata.xml
    • PublicUri - the publicly accessible URL of the server running Cortex (i.e. what you'll type into your browser's address bar to get to Cortex).
    • CertificateFile - the full path to the certificate file, in pfx format. This needs to include the private key used to request/generate the certificate. (Optional, but highly encouraged)
    • CertificatePassword - the password set when the certificate was exported.

Configure Cortex as a Relying Party Trust​

  1. On your ADFS server, create a new relying party trust by manually entering the information into the wizard.

    • Use the value you entered for PublicUri above as the "Entity URI"
    • Upload the certificate (without the private key) when requested for a signing certificate
    • Choose the defaults for everything else

  2. Customize the claims that are sent by mapping "SAM-Account-Name" to "Name ID". This uses the Windows username to look up the appropriate user in Cortex.

  3. Optionally customize other options (see below) depending on your setup and security requirements. See the video below for examples.

Additional Options​

Depending on your specific configuration, you may or may not need the below options. Start by following the setup above, then changing a single option at a time, then re-testing. Depending on the type of misconfiguration (or "incomplete" configuration), you may see feedback in the UI, or in the logs.

note

For simplicity, the following options are listed in Block:SubBlock:Setting format. If you're configuring Cortex by modifying appsettings.json, that means you'll set the Setting in the JSON block SubBlock within the JSON block Block, e.g.:

{
   "Block": {
      "SubBlock": {
         "Setting": "value"
      }
   }
}

If you're configuring Cortex via environment variables, you'll set an environment variable named Block:SubBlock:Setting in Powershell or Block__SubBlock__Setting in any environment (that is, replacing the single colon with two underscores).

  • Authentication:LookUpBy - either "Email" or empty. If your IdP identifies users by email address (do you see an email address in the bottom left Corner when you log into Cortex?), set this to "Email".
  • Authentication:IdentifierClaim - the name of the claim that your IdP sends to identify your users. It could be something simple, like emailAddress, or something that looks like a URL. Your IdP documentation might help you figure this out.
  • Authentication:Saml:CertificateValidationMode - you can disable validation entirely by setting this to "None"
  • Authentication:Saml:RevocationMode - do you want to verify that the IdP's certificate is unexpired and has not been revoked?
  • Authentication:Saml:ForceAuthn - require the user to enter their username and password on the IdP's login screen regardless of whether they are already logged in. This is equivalent to Cherwell's "Authentication: Force" setting.

Video​