Admin Single Sign-On (SSO) Setup: Integrating Microsoft ADFS with Vome

Admin Single Sign-On (SSO) Setup: Integrating Microsoft ADFS with Vome

This article outlines how to integrate Microsoft Active Directory Federation Services (ADFS) with Vome using SAML-based Single Sign-On (SSO) and LDAP authentication. It covers the complete process - from configuring ADFS relying party trusts to setting up LDAP connectivity for user authentication. This guide is intended for system administrators managing SSO and directory services within their organizations.

## Overview

Integrating Microsoft ADFS with Vome allows your organization to leverage your existing Active Directory infrastructure for user authentication. This setup enables:

- **Centralized Authentication**: Users authenticate against your corporate Active Directory
- **SAML-based SSO**: Secure token-based authentication between ADFS and Vome
- **LDAP User Lookup**: Direct integration with your directory services for user information
- **Enhanced Security**: Leverages your existing security policies and credential management

> **Note**: This guide focuses specifically on Microsoft ADFS integration. If your organization uses Microsoft Entra ID (Azure AD), please refer to the separate Entra ID integration guide.

## Prerequisites

Before you begin, ensure you have:

- **Active Directory Infrastructure**: A functioning Active Directory domain with ADFS installed and configured
- **ADFS Administrative Access**: Permissions to create relying party trusts and modify ADFS configuration
- **Vome Administrative Access**: Access as the account holder of the Vome Admin platform
- **Vome Subscription**: Your Vome subscription has access to the Ultimate plan
- **Network Connectivity**: Ensure Vome can reach your LDAP servers over the network
- **Service Account**: A dedicated Active Directory service account for LDAP binding
- **SSL Certificates**: Valid SSL certificates for secure LDAP communication (recommended)
- **Basic Knowledge**: Familiarity with SAML protocols and LDAP directory services

## Step 1: Configure ADFS SAML Authentication

### 1.1 Access ADFS Management Console
- Open the **ADFS Management** console on your ADFS server
- Navigate to **Trust Relationships** → **Relying Party Trusts**

### 1.2 Add Vome as a Relying Party Trust
- Click **Add Relying Party Trust** to start the wizard
- Select **Claims Aware** as the trust type
- Choose **Enter data about the relying party manually**

### 1.3 Configure Basic Settings
- **Display Name**: Enter "Vome SSO" or similar identifier
- **Profile**: Select **AD FS profile**
- **Certificate**: Skip certificate configuration for now (will be configured later)
- **URL**: Check **Enable support for the SAML 2.0 WebSSO protocol**

### 1.4 Configure SAML Endpoints
You will receive these URLs from your Vome configuration:


### 1.5 Configure Claim Rules
Create the following claim rules:

**Rule 1: Send LDAP Attributes**
- Rule Name: "Send LDAP Attributes"
- Attribute Store: Active Directory
- LDAP Attributes:
  - `E-Mail-Addresses` → `E-Mail Address`
  - `Display-Name` → `Name`
  - `SAM-Account-Name` → `Name ID`

**Rule 2: Transform Name ID**
- Rule Name: "Transform Name ID to Email"
- Incoming Claim Type: `E-Mail Address`
- Outgoing Claim Type: `Name ID`
- Outgoing Name ID Format: `Email`

## Step 2: Configure LDAP Authentication

### 2.1 Create Service Account
Create a dedicated Active Directory service account for LDAP binding:

```
Username: svc_vome_ldap
Password: [Secure Password]
Description: Vome LDAP Service Account
```

**Required Permissions**:
- **Log on as a service** (if running as service)
- **Read** permissions on the directory tree where users are located
- Member of **Domain Users** (minimum required group)

### 2.2 Identify LDAP Configuration Parameters

Gather the following information from your Active Directory environment:

- **Domain Controllers**: List of your domain controller FQDNs
- **LDAP Port**: Usually 636 for LDAPS (secure) or 389 for LDAP
- **Base DN**: The distinguished name of your domain (e.g., `DC=corp,DC=local`)
- **Service Account DN**: Full distinguished name of your service account
- **User Search Base**: Organizational Unit containing your users (if different from domain root)

### 2.3 Test LDAP Connectivity
Before configuring Vome, test LDAP connectivity:

```powershell
# Test LDAP connection using PowerShell
$ldapServer = "ldaps://dc01.corp.local:636"
$credential = Get-Credential # Enter service account credentials
$directoryEntry = New-Object System.DirectoryServices.DirectoryEntry($ldapServer, $credential.UserName, $credential.GetNetworkCredential().Password)
$directoryEntry.Path
```

## Step 3: Configure Vome ADFS Integration

### 3.1 Access Vome SSO Settings
- Log into your Vome Admin platform
- Navigate to **Settings** → **Single Sign-On**
- Select **Microsoft ADFS** as your identity provider

### 3.2 Configure SAML Settings
Enter the following information:

**Identifier (Entity ID)**:
```
```

**Reply URL (Assertion Consumer Service)**:
```
```

> **Note**: Copy these URLs and use them in your ADFS relying party trust configuration

### 3.3 Configure LDAP Settings

**LDAP Server URIs**:
```
ldaps://dc01.corp.local,ldaps://dc02.corp.local
```
*Enter multiple domain controllers separated by commas for redundancy*

**LDAP Port**:
```
636
```
*Use 636 for LDAPS (secure) or 389 for LDAP (not recommended for production)*

**LDAP Bind DN**:
```
```
*Or use the full DN format: CN=svc_vome_ldap,OU=Service Accounts,DC=corp,DC=local*

**LDAP Bind Password**:
```
[Service Account Password]
```

**LDAP Base DN**:
```
DC=corp,DC=local
```

**LDAP User Filter**:
```
(sAMAccountName=%(user)s)
```
*This filter searches for users by their SAM account name*

### 3.4 Test LDAP Connection
- Click **Test LDAP Connection** to verify connectivity
- Ensure the test passes before proceeding
- If the test fails, verify network connectivity, credentials, and firewall rules

## Step 4: Upload Certificates and Metadata

### 4.1 Export ADFS Metadata
From your ADFS server, export the federation metadata:

- Save this file as `adfs-metadata.xml`

### 4.2 Export ADFS Token Signing Certificate
Using ADFS Management Console:

- Navigate to **Service** → **Certificates**
- Right-click on **Token-signing** certificate
- Select **Export Certificate**
- Save as Base64-encoded format

### 4.3 Upload to Vome

**SAML Metadata File**:
- Upload the `adfs-metadata.xml` file

**SAML Certificate File**:
- Upload the token-signing certificate file

**LDAP CA Certificate** (if using LDAPS):
- Export your domain's root CA certificate
- Upload as Base64-encoded .cer file
- This ensures secure LDAP communication

## Step 5: Test and Validate Configuration

### 5.1 Verify Configuration
- Review all entered information for accuracy
- Ensure certificates are properly uploaded
- Confirm LDAP test connection succeeded

### 5.2 Save and Activate
- Click **Verify Configuration** to save settings
- Vome will validate the configuration and provide feedback

### 5.3 Test SSO Login
1. Navigate to your Vome login page
2. Click **Sign in with ADFS** (or similar button)
3. You should be redirected to your ADFS login page
4. Enter your Active Directory credentials
5. Upon successful authentication, you should be redirected back to Vome

## Troubleshooting

### Common Issues and Solutions

**LDAP Connection Failures**:
- Verify network connectivity to domain controllers
- Check firewall rules (port 636 for LDAPS, 389 for LDAP)
- Validate service account credentials and permissions
- Ensure DNS resolution of domain controller names

**SAML Authentication Errors**:
- Verify metadata files are current and correctly uploaded
- Check certificate validity and format
- Confirm claim rules are properly configured in ADFS
- Review ADFS event logs for detailed error messages

**Certificate Errors**:
- Ensure certificates are in Base64 format
- Verify certificate chains are complete
- Check certificate expiration dates
- For LDAPS, ensure proper CA certificate chain

**User Not Found Errors**:
- Verify LDAP user filter syntax
- Check Base DN configuration
- Confirm user exists in specified organizational unit
- Validate service account has read permissions on user objects

### Diagnostic Steps

1. **Check ADFS Event Logs**:
   - Review Admin and Debug logs under Applications and Services Logs → AD FS

2. **Test LDAP Connectivity**:
   - Use tools like `ldp.exe` or PowerShell to test LDAP queries

3. **Validate SAML Tokens**:
   - Use browser developer tools to inspect SAML responses
   - Check claim values and formatting

4. **Network Troubleshooting**:
   - Verify DNS resolution: `nslookup dc01.corp.local`
   - Test port connectivity: `telnet dc01.corp.local 636`

## Additional Support

### Documentation and Resources

- **Microsoft ADFS Documentation**: [Microsoft ADFS Official Docs](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services)
- **SAML Protocol Reference**: [OASIS SAML Specification](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
- **LDAP Reference**: [RFC 4511 - LDAP Protocol](https://tools.ietf.org/html/rfc4511)

### Security Considerations

- **Use LDAPS**: Always use secure LDAP (port 636) in production environments
- **Service Account Security**: Use dedicated service accounts with minimal required permissions
- **Certificate Management**: Regularly review and update certificates before expiration
- **Network Security**: Implement appropriate firewall rules and network segmentation