Windows SSO Authentication

This document provides a guide for configuring PhenixID Authentication Services (PAS) to enable federation with SAML, OIDC and Internal authentication using Windows SSO through Kerberos or NTLM authentication. This setup allows users authenticated within a Windows Active Directory environment to access SAML-based applications without needing to re-authenticate, leveraging seamless Single Sign-On (SSO).

This configuration integrates PhenixID seamlessly with a Windows-based SSO environment, allowing organizations to extend SAML and OIDC federation to Windows-authenticated users, enhancing security and simplifying access.

Windows Enviroment

You first need to setup the Windows environment for Windows SSO with PhenixID. This includes configuring a trusted Windows server, creating a service account, registering DNS records, and defining Service Principal Names (SPNs) to enable secure Kerberos authentication.

Install PAS on a Windows Server that is member of an Active Directory domain.
Create service account CN=phxid,CN=Users,DC=company,DC=local
Change the service "PhenixID service" to be run by CN=phxid,CN=Users,DC=company,DC=local
Register a DNS A record: A phenixid.company.local 127.0.0.1

C:\Users\Administrator>Setspn -S HTTP/phenixid.company.local phxid
Checking domain DC=company,DC=local  
Registering ServicePrincipalNames for CN=phxid,CN=Users,DC=company,DC=local
HTTP/phenixid.company.local  
Updated object  

C:\Users\Administrator>Setspn -S HTTPS/phenixid.company.local phxid
Checking domain DC=company,DC=local  
Registering ServicePrincipalNames for CN=phxid,CN=Users,DC=company,DC=local  
HTTPS/phenixid.company.local  
Updated object

If testing with web browser directly on server, Loopback checks must be disabled. Do not use in prod environments!
https://support.microsoft.com/en-us/kb/896861, Workaround method 2

Configuring PhenixID Authentication Services

Warning

NTLM is not recommended for use in modern authentication setups due to its outdated security mechanisms, vulnerability to relay attacks, and lack of support for multi-factor authentication. For secure and robust authentication, it is recommended to use Kerberos instead of NTLM whenever possible.

Next we need to configure PhenixID Authentication Services (PAS) for Windows SSO, enabling Active Directory users to access SAML applications seamlessly using Kerberos authentication.

Start with adding a WindowsSSO authenticator more information here.. Here is an example how the authenticator could look like:

{
    "alias": "winsso",
    "name": "WindowsSSOAuthenticator",
    "configuration": {
        "backupAuthenticator": "backupauth",
        "pipeID": "authPipe1"
    },
    "id": "winsso"
}

Here is an example how the pipe could look like:

{
  "id": "authPipe1",
  "description": "Pipe performing mutual TLS authentication",
  "enabled": "true",
  "valves": [{
   "name": "LDAPSearchValve",
   "enabled": "true",
   "config": {
    "connection_ref": "<your connection_ref>",
    "base_dn": [
     "DC=example,DC=com"
    ],
    "scope": "SUB",
    "size_limit": "0",
    "filter_template": "sAMAccountName={{request.username}}",
    "attributes": "*",
    "escape": "all"
   }
  },{
   "name": "FlowFailValve",
   "enabled": "true",
   "config": {
    "message": "guides.authentication.common.failed_authentication",
    "exec_if_expr": "flow.isEmpty()"
   }
  }]
 }

About The Backup Authenticator

The following configuration is optional: "backupAuthenticator": "backupauth",

This is what authenticator should be used if Kerberos authentication fails. This could be anything but for this example we will use DynamicAuthenticator with Username & Password authentication.

Note

Kerberos login is safer than a username & password login because it uses encrypted tickets and mutual authentication, ensuring both the user and the service verify each other's identities without directly exchanging passwords. This reduces the risk of password theft and protects against replay attacks, providing a more secure authentication process.

{
  "id": "backupauth",
  "alias": "backupauth",
  "name": "DynamicAuthenticator",
  "configuration": {
   "localizationKey": "usernamePassword",
   "defaultPipeErrorCode": "incorrectUsernameOrPassword",
   "userIdentifierAttribute": "sAMAccountName",
   "pipeID": "up-pipe",
   "inputElements": [
    {
     "name": "username"
    },
    {
     "name": "password"
    }
   ]
  }
 }

Example pipe for this authenticator:

{
  "id": "up-pipe",
  "description": "Pipe performing username password authentication",
  "enabled": "true",
  "valves": [{
   "name": "LDAPSearchValve",
   "enabled": "true",
   "config": {
    "connection_ref": "<your connection_ref>",
    "base_dn": [
     "DC=example,DC=com"
    ],
    "scope": "SUB",
    "size_limit": "0",
    "filter_template": "sAMAccountName={{request.username}}",
    "attributes": "*",
    "escape": "all"
    }
  },{
  "name": "LDAPBindValve",
  "config": { 
    "connection_ref":"<your connection_ref>",
    "password_param_name":"password",
    "userid_param_name":"username"
    }
  }]
}

About Group Membership Restrictions

Users with a large number of group memberships may encounter problems with Kerberos authentication. Please view this article for more information: Kerberos authentication problems - Windows Server | Microsoft Learn

Verification Steps for Windows SSO Authentication Configuration

Verify Windows Environment Setup:

Ensure that the PhenixID Authentication Services (PAS) server is installed on a Windows Server joined to an Active Directory domain.
Check that the service account is configured correctly and running the PhenixID service.
Confirm that DNS and SPN records are registered correctly for HTTP/phenixid.company.local and HTTPS/phenixid.company.local.

Test Windows SSO Authentication:

Access a SAML or OIDC-protected resource using a client within the Active Directory domain to verify Kerberos-based Single Sign-On.
Confirm that the user is not prompted for credentials and is authenticated automatically using Windows SSO.

Check PAS Logs for Successful Authentication Flow:

Review PAS logs to ensure the WindowsSSOAuthenticator processed the authentication request, and the LDAPSearchValve retrieved the user information based on the sAMAccountName.
Confirm that a successful session is established and that no errors are reported.

Test Backup Authenticator (Optional):

Temporarily disable Kerberos (e.g., by using an incorrect SPN) and access the resource to trigger the backup authenticator.
Verify that the backup authenticator prompts for username and password, and check that authentication proceeds if valid credentials are provided.

These steps will verify the correct setup of Windows SSO authentication with PhenixID, including both Kerberos authentication and the backup authenticator functionality.

Table of Contents