> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/auth/aaa/manage-aaa-sources/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Manage AAA sources

> Configure multiple AAA sources for redundancy and failover

Configure multiple Authentication, Authorization, and Accounting (AAA) sources for redundancy and enable manual failover between sources.

## Overview

Platform supports one active AAA source at a time. If the active AAA source becomes unavailable, users cannot log in to Platform.

**Solution:** Configure multiple AAA sources and manually switch between them when the primary source fails.

**Use cases:**

* LDAP server failure - Switch to backup LDAP server
* Active Directory maintenance - Switch to Local AAA temporarily
* External AAA outage - Switch to alternative authentication provider

AAA sources cannot be federated by enabling multiple simultaneously. Enabling multiple AAA adapters with the `aaa` broker simultaneously may prevent users from logging in.

## Before you begin

* Administrator access to Platform
* All AAA adapters configured and tested
* Understanding of profile system (Platform 2023.2) or configuration methods (Platform 6)
* Documented failover procedures for operations team

## How AAA source management works

### AAA adapters and brokers

**Adapters** handle communication with external systems. AAA adapters (Local AAA, LDAP, Active Directory, RADIUS) authenticate users.

**Brokers** deliver requests to adapters. The `aaa` broker delivers authentication requests to AAA adapters.

**Key requirement:** Only one AAA adapter should have the `aaa` broker configured at a time.

### Profile-based management

**Profiles** designate which services (applications and adapters) are enabled on Platform.

**Strategy:**

1. Configure multiple AAA adapters
2. Create separate profiles, each enabling one AAA adapter
3. Switch active profile to change AAA source

## Configure AAA adapters

Configure all AAA adapters you plan to use before creating profiles.

### Navigate to adapters

Go to **Admin Essentials > Adapters**.

### Select AAA adapter

Choose the adapter to configure (Local AAA, LDAP, Active Directory, RADIUS).

### Configure adapter settings

Set connection details, credentials, and authentication parameters.

See adapter-specific documentation for configuration details:

* [Configure Local AAA](/itential-platform/auth/aaa/configure-local-aaa-authentication)
* [Configure LDAP](/itential-platform/configure/auth/ldap/configure-ldap-authentication)
* [Configure Active Directory](/itential-platform/configure/auth/ldap/configure-ldap-authentication)

### Configure AAA broker

Verify `aaa` appears in the `brokers` array:

**Advanced View (JSON):**

```json
{
  "model": "LocalAAA",
  "name": "local-aaa",
  "type": "Adapter",
  "properties": {
    "brokers": ["aaa"]
  }
}
```

### Test adapter

Verify adapter connects successfully to authentication source.

### Repeat for all AAA adapters

Configure all AAA adapters you plan to use.

Test each AAA adapter thoroughly before using it for production authentication. Verify users can authenticate and authorization works correctly.

## Platform 6: Manage AAA sources

Platform 6 uses environment variables and properties files for primary configuration.

### Configuration hierarchy (Platform 6)

Platform 6 configuration priority:

1. **Environment variables** (highest priority) - `ITENTIAL_*`
2. **Properties file** - `/opt/itential/platform/server/dev/local.properties`
3. **Profile document** (lowest priority) - MongoDB `iap_profiles` collection

### Method 1: Environment variables (recommended)

Use environment variables for dynamic AAA source switching without file changes.

**Configure in systemd service file:**

```bash
sudo vi /usr/lib/systemd/system/itential-platform.service
```

**Add environment variables:**

```
[Service]
# Primary AAA source (LDAP)
Environment="ITENTIAL_AAA_ADAPTER=adapter-ldap"

# Backup AAA source (comment out when using primary)
# Environment="ITENTIAL_AAA_ADAPTER=local-aaa"
```

**Switch AAA source:**

### Edit service file

```bash
sudo vi /usr/lib/systemd/system/itential-platform.service
```

### Comment primary, uncomment backup

```
[Service]
# Primary AAA source (LDAP) - commented out during failover
# Environment="ITENTIAL_AAA_ADAPTER=adapter-ldap"

# Backup AAA source (Local AAA)
Environment="ITENTIAL_AAA_ADAPTER=local-aaa"
```

### Reload systemd daemon

```bash
sudo systemctl daemon-reload
```

### Restart Platform

```bash
sudo systemctl restart itential-platform
```

### Verify AAA source

Check Platform logs for successful authentication adapter initialization.

### Method 2: Properties file

Configure active AAA source in properties file.

**Edit properties file:**

```bash
sudo vi /opt/itential/platform/server/dev/local.properties
```

**Set active adapter:**

```properties
# Primary AAA source
aaa_adapter=adapter-ldap

# Backup AAA source (comment out when using primary)
# aaa_adapter=local-aaa
```

**Switch AAA source and restart:**

```bash
# Edit file to change active adapter
sudo vi /opt/itential/platform/server/dev/local.properties

# Restart Platform
sudo systemctl restart itential-platform
```

### Method 3: Profiles (fallback)

Use profiles when environment variables and properties file are not configured.

Follow [Platform 2023.2 profile procedures](#platform-20232-manage-aaa-sources) below.

## Platform 2023.2: Manage AAA sources

Platform 2023.2 uses profile-based configuration exclusively.

### Create profiles

Create separate profiles for each AAA source by cloning the default profile.

### Navigate to profiles

Go to **Admin Essentials > Profiles**.

### Select default profile

Select the default profile (typically `profile1`).

### Clone profile

Click the **menu** button (three dots) and select **Clone**.

### Name profile

Enter a descriptive name indicating the AAA source (e.g., `LDAP-Primary`, `LocalAAA-Backup`).

### Save profile

Click **Clone** to create the new profile.

### Repeat for each AAA source

Create one profile per AAA source.

**Example profiles:**

* `LDAP-Primary` - Primary LDAP server
* `LDAP-Backup` - Backup LDAP server
* `LocalAAA-Emergency` - Local AAA for emergencies

### Configure profiles

Enable the appropriate AAA adapter in each profile.

### Navigate to profiles

Go to **Admin Essentials > Profiles**.

### Select profile

Choose the profile to configure.

### Open Configure tab

Click the **Configure** tab.

### Expand adapters section

Under **Edit Profile Services**, select **Adapters**.

### Enable AAA adapter

Check the box for the AAA adapter to use with this profile.

**Important:** Only enable one AAA adapter per profile.

### Disable other AAA adapters

Ensure all other AAA adapters are unchecked.

### Save configuration

Click the **Save** icon.

### Repeat for all profiles

Configure each profile with its designated AAA adapter.

**Example configuration:**

**LDAP-Primary profile:**

* ✅ LDAP Adapter (enabled)
* ❌ Local AAA (disabled)
* ❌ Active Directory (disabled)

**LocalAAA-Backup profile:**

* ❌ LDAP Adapter (disabled)
* ✅ Local AAA (enabled)
* ❌ Active Directory (disabled)

### Switch between profiles

Change the active profile to switch AAA sources.

### Navigate to profiles

Go to **Admin Essentials > Profiles**.

### Select target profile

Choose the profile for the AAA source you want to use.

### Open metadata drawer

Click the **menu** button (three dots) and select **View Metadata**.

### Activate profile

Toggle the **Active Profile** switch to enable.

### Save metadata

Click **Save** at the bottom of the metadata drawer.

### Restart Platform

Restart Platform on all servers in cluster:

```bash
sudo systemctl restart itential-platform
```

For HA environments, restart all Platform servers reading from the MongoDB database.

### Verify AAA source

Log out and log in to verify authentication works with new AAA source.

In some Platform versions, multiple AAA adapters with the `aaa` broker can prevent proper loading. Ensure only one AAA adapter has the `aaa` broker configured.

## Emergency failover (all versions)

If AAA source failure prevents UI access, edit the configuration file directly.

### Platform 6

**Edit properties file:**

```bash
# Navigate to properties file
cd /opt/itential/platform/server/dev

# Edit properties file
sudo vi local.properties

# Change active AAA adapter
# Change from:
aaa_adapter=adapter-ldap
# To:
aaa_adapter=local-aaa

# Restart Platform
sudo systemctl restart itential-platform
```

**Or edit environment variables:**

```bash
# Edit service file
sudo vi /usr/lib/systemd/system/itential-platform.service

# Change ITENTIAL_AAA_ADAPTER value
# From:
Environment="ITENTIAL_AAA_ADAPTER=adapter-ldap"
# To:
Environment="ITENTIAL_AAA_ADAPTER=local-aaa"

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart itential-platform
```

### Platform 2023.2

**Edit properties.json:**

```bash
# Navigate to Platform directory
cd /opt/pronghorn/current

# Edit properties.json
sudo vi properties.json

# Change profile ID
# Find line:
"id": "LDAP-Primary"
# Change to:
"id": "LocalAAA-Backup"

# Restart Platform
sudo systemctl restart itential-platform
```

**Example properties.json:**

```json
{
  "pathProps": {
    "description": "File Path Variables",
    "sdk_dir": "/opt/pronghorn-applications",
    "encrypted": true
  },
  "id": "LocalAAA-Backup",
  "mongoProps": {
    "credentials": {
      "passwd": "itentialPassword",
      "user": "itentialUser"
    },
    "db": "pronghorn",
    "url": "mongodb://localhost:27017"
  }
}
```

## High availability considerations

### Cluster-wide changes

In HA deployments with multiple Platform servers:

**Platform 6:**

* Environment variables: Update service file on each server
* Properties file: Sync properties file to all servers
* Profiles: Restart all Platform servers after profile change

**Platform 2023.2:**

* Profiles stored in MongoDB are cluster-wide
* Restart **all** Platform servers after profile change
* All servers must restart for changes to take effect

### Coordinated failover

**Plan failover procedure:**

1. Document current active AAA source
2. Identify backup AAA source to use
3. Coordinate restart timing to minimize downtime
4. Verify authentication works on each server after restart

**Rolling restart (recommended):**

* Restart servers one at a time
* Verify authentication works before restarting next server
* Reduces total downtime during failover

## Best practices

### Configuration

* **Test all AAA adapters** before creating profiles
* **Use descriptive names** for profiles indicating AAA source
* **Document AAA source priority** (primary, secondary, emergency)
* **Keep Local AAA configured** as emergency backup
* **Verify broker configuration** - only one `aaa` broker active

### Operations

* **Document failover procedures** for operations team
* **Test failover regularly** in non-production environment
* **Monitor AAA source health** to detect failures early
* **Maintain user accounts** in backup AAA sources
* **Communicate changes** to users before switching sources

### Security

* **Limit profile changes** to administrator users only
* **Audit AAA source changes** in change management system
* **Test permissions** after switching AAA sources
* **Verify authorization** works correctly with each source
* **Monitor failed authentication** attempts after switching

### High availability

* **Restart all servers** in cluster after profile changes
* **Coordinate restart timing** to minimize downtime
* **Test failover in staging** before production changes
* **Verify cluster health** after AAA source changes
* **Document AAA topology** including all sources and failover paths

## Troubleshooting

### Cannot log in after switching profiles

**Symptom:** Authentication fails after activating new profile

**Solutions:**

* Verify correct profile is active
* Check AAA adapter enabled in profile
* Verify only one AAA adapter has `aaa` broker
* Test AAA adapter connectivity independently
* Check Platform logs for authentication errors
* Verify Platform restarted after profile change

### Multiple AAA adapters causing issues

**Symptom:** Authentication inconsistent or failing

**Solutions:**

* Verify only one AAA adapter enabled per profile
* Check `brokers` array in each adapter configuration
* Ensure only one adapter has `aaa` in brokers array
* Disable unused AAA adapters
* Restart Platform after changes

### Profile changes not taking effect

**Symptom:** AAA source doesn't change after profile switch

**Solutions:**

* Verify Platform restarted after profile change
* Check active profile in Admin Essentials
* For HA: Restart **all** Platform servers in cluster
* Verify profile configuration saved successfully
* Check Platform startup logs for errors

### Emergency failover not working

**Symptom:** Cannot access Platform after AAA failure

**Solutions:**

**Platform 6:**

* Verify properties file path correct
* Check environment variables in service file
* Verify Local AAA adapter configured
* Check file permissions on properties file

**Platform 2023.2:**

* Verify properties.json path correct: `/opt/pronghorn/current/properties.json`
* Check profile name matches exactly (case-sensitive)
* Verify MongoDB accessible
* Check Local AAA adapter configured in backup profile

### HA cluster not synchronized

**Symptom:** Some servers authenticate, others don't

**Solutions:**

* Verify all servers restarted after profile change
* Check all servers reading from same MongoDB database
* Verify profile settings synchronized across cluster
* Check network connectivity between servers
* Review Platform logs on each server

## Verify AAA source

After switching AAA sources, verify authentication works:

### Log out of Platform

Log out of current session.

### Log in with test account

Attempt login with test user from new AAA source.

### Verify permissions

Check user has correct roles and permissions.

### Test multiple users

Verify authentication works for multiple user accounts.

### Check Platform logs

Review logs for authentication success messages:

```bash
# Platform 6
tail -f /var/log/itential/itential-platform.log | grep -i auth

# Platform 2023.2
tail -f /var/log/pronghorn/itential-platform.log | grep -i auth
```

### Monitor for errors

Watch for authentication errors over next 15-30 minutes.

## Next steps

#### [Configure Local AAA](/itential-platform/auth/aaa/configure-local-aaa-authentication)

Set up local authentication

#### [Configure LDAP](/itential-platform/configure/auth/ldap/configure-ldap-authentication)

Integrate with LDAP servers

#### [Configure Active Directory](/itential-platform/configure/auth/ldap/configure-ldap-authentication)

Integrate with Active Directory

#### [Authentication overview](/itential-platform/auth/overview)

Learn about Platform authentication

> Configure multiple AAA sources for redundancy and failover