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

# Configure local AAA authentication

> Set up local authentication for development and testing environments

Local AAA provides simple MongoDB-based authentication for development and testing environments. User credentials are stored locally in a MongoDB collection, eliminating the need for external authentication services.

Local AAA is recommended for development and testing only. For production environments, use LDAP or SAML SSO authentication.

## Before you begin

* MongoDB installed and accessible
* Administrative access to Itential Platform
* MongoDB credentials (if authentication is enabled)

## How Local AAA works

Local AAA authenticates users against a MongoDB collection that stores:

* Usernames
* Bcrypt-hashed passwords
* Group memberships
* User profile information

Unlike external authentication providers, Local AAA maintains complete control over user data within your deployment.

## Configure Local AAA adapter

### Open adapter configuration

Navigate to **Admin Essentials > Adapters** and locate the Local AAA adapter.

### Configure database connection

Set the MongoDB connection parameters:

```json
{
  "id": "Local AAA",
  "type": "local_aaa",
  "properties": {
    "database": {
      "db": "LocalAAA",
      "url": "mongodb://127.0.0.1:27017",
      "credentials": {
        "dbAuth": false
      }
    }
  },
  "brokers": ["aaa"]
}
```

### Configure with authentication

If MongoDB uses authentication, include credentials:

```json
{
  "id": "Local AAA",
  "type": "local_aaa",
  "properties": {
    "database": {
      "db": "LocalAAA",
      "url": "mongodb://127.0.0.1:27017",
      "credentials": {
        "dbAuth": true,
        "user": "localaaa_user",
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
      }
    }
  },
  "brokers": ["aaa"]
}
```

If using `dbAuth`, create the MongoDB user in the same database specified in the `db` property.

### Enable AAA broker

Add the adapter to the AAA broker by including `"brokers": ["aaa"]` in the configuration.

### Save configuration

Click **Save** to apply the Local AAA configuration.

## Add users

### Install bcrypt-cli

Install the bcrypt command-line tool globally:

```bash
npm install --global bcrypt-cli
```

### Generate password hash

Create a bcrypt hash for the user password:

```bash
bcrypt-cli mypassword 10
$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2
```

The number `10` represents the salt rounds (higher = more secure but slower).

### Create user document

Connect to MongoDB and create a user document in the `accounts` collection:

```javascript
use LocalAAA

db.accounts.insertOne({
  "username": "admin@pronghorn",
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
  "firstname": "Admin",
  "groups": ["pronghorn_admin"],
  "activeTenant": "*",
  "tenants": []
})
```

### Create corresponding group

Create a group document for each group referenced in user accounts:

```javascript
db.groups.insertOne({
  "name": "pronghorn_users",
  "group": "pronghorn_admin"
})
```

### Configure group in Platform

Log in to Itential Platform as administrator and configure the group from **Admin Essentials > Authorization > Groups**.

## Secure MongoDB connectivity

For production-like development environments, configure MongoDB with authentication and SSL.

### Create MongoDB users

### Create admin user

```javascript
use admin

db.createUser({
  "user": "admin",
  "pwd": "secure-admin-password",
  "roles": [
    {"role": "root", "db": "admin"},
    {"role": "userAdminAnyDatabase", "db": "admin"},
    {"role": "clusterMonitor", "db": "admin"},
    {"role": "dbOwner", "db": "LocalAAA"},
    {"role": "dbOwner", "db": "pronghorn"}
  ]
})
```

### Create Platform user

```javascript
use admin

db.createUser({
  "user": "pronghorn",
  "pwd": "secure-pronghorn-password",
  "roles": [
    {"role": "dbOwner", "db": "pronghorn"},
    {"role": "dbOwner", "db": "LocalAAA"},
    {"role": "clusterMonitor", "db": "admin"}
  ]
})
```

### Create Local AAA user

```javascript
use LocalAAA

db.createUser({
  "user": "localaaa_user",
  "pwd": "secure-localaaa-password",
  "roles": [
    {"role": "dbOwner", "db": "LocalAAA"}
  ]
})
```

### Enable MongoDB authentication

### Edit mongod.conf

Open the MongoDB configuration file:

```bash
sudo vi /etc/mongod.conf
```

### Enable authentication

Add or modify the security section:

```yaml
# network interfaces
net:
  port: 27017
  bindIp: 0.0.0.0

# security
security:
  authorization: enabled
```

### Restart MongoDB

Apply the configuration changes:

```bash
sudo systemctl restart mongod
```

### Update Platform configuration

### Update properties.json

Edit the Platform properties file:

```bash
sudo vi /opt/pronghorn/current/properties.json
```

Add MongoDB credentials:

```json
{
  "id": "profile1",
  "mongoProps": {
    "credentials": {
      "dbAuth": true,
      "user": "pronghorn",
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
    },
    "db": "pronghorn",
    "url": "mongodb://127.0.0.1:27017"
  }
}
```

### Update MongoDB adapter

Navigate to **Admin Essentials > Adapters** and update the MongoDB adapter:

```json
{
  "id": "mongo",
  "properties": {
    "credentials": {
      "dbAuth": true,
      "user": "pronghorn",
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
    },
    "db": "pronghorn",
    "url": "mongodb://127.0.0.1:27017"
  }
}
```

### Update Local AAA adapter

Update the Local AAA adapter configuration:

```json
{
  "id": "Local AAA",
  "type": "local_aaa",
  "properties": {
    "database": {
      "db": "LocalAAA",
      "url": "mongodb://127.0.0.1:27017",
      "credentials": {
        "dbAuth": true,
        "user": "localaaa_user",
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
      }
    }
  },
  "brokers": ["aaa"]
}
```

### Restart Platform

Apply all configuration changes:

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

### Verify status

Check that Platform started successfully:

```bash
sudo systemctl status itential-platform
```

## Encrypt passwords

Itential recommends encrypting all passwords. You can use:

* HashiCorp Vault (recommended) - See [Configure HashiCorp Vault](/itential-platform/secrets/hashicorp/overview)
* CyberArk CCP - See [Configure CyberArk](/itential-platform/secrets/cyberark/overview)
* Legacy `$ENC` encryption (deprecated)

## User document structure

### Account document example

```json
{
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d4d"),
  "username": "admin@pronghorn",
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
  "firstname": "Admin",
  "lastname": "User",
  "email": "admin@example.com",
  "groups": ["pronghorn_admin", "developers"],
  "activeTenant": "*",
  "tenants": []
}
```

### Group document example

```json
{
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d56"),
  "name": "pronghorn_users",
  "group": "pronghorn_admin"
}
```

## Best practices

### Security

* Use bcrypt with at least 10 salt rounds for password hashing
* Enable MongoDB authentication in all environments
* Store MongoDB credentials in HashiCorp Vault or CyberArk
* Use SSL/TLS for MongoDB connections
* Limit MongoDB user permissions to minimum required

### User management

* Create separate MongoDB users for Platform and Local AAA
* Assign users to appropriate groups before first login
* Configure groups in Platform before creating user accounts
* Use email addresses as usernames for consistency

### Development workflow

* Use Local AAA for isolated development environments
* Test authentication changes before applying to production
* Maintain separate user databases for each environment
* Document custom user accounts and groups

## Troubleshooting

### Authentication failures

* Verify MongoDB is running: `sudo systemctl status mongod`
* Check database name matches adapter configuration
* Confirm user document exists in correct database
* Verify password hash is correct

### Database connection errors

* Test MongoDB connectivity: `mongosh mongodb://localhost:27017`
* Check MongoDB authentication is properly configured
* Verify credentials in adapter configuration
* Review MongoDB logs: `sudo journalctl -u mongod`

### Group assignment issues

* Confirm group documents exist in groups collection
* Verify group names in user document match group documents
* Check group configuration in Admin Essentials
* Ensure user has logged out and back in after group changes

### Invalid credentials

If you are receiving invalid credentials errors, the Local AAA user has not been set up properly, or the credentials or parameters in your properties file for the Local AAA adapter are incorrect.

Check whether the Local AAA user and password are valid:

```bash
mongo -u localaaa_user -p pronghorn LocalAAA

show users....
```

If you are logged in and can see the configured users, check the Local AAA adapter properties to verify they are set correctly.

The same check applies to `pronghorn` if Itential Platform does not start — verify the `pronghorn` user and password are valid in the `properties.json` file and in the adapter properties for MongoDB.

### User cannot log in

Use the following checklist when you encounter login problems:

* Itential Platform can only configure one AAA adapter at a time. If using LDAP or Azure, users may not be able to log in with the default credentials.
* If using LDAP or Azure, check the connection between Itential Platform and the AD server.
* Verify that software dependencies are up and running.
* Check OS and browser compatibility.
* Check user and group role and privilege access.
* Review sign-in error logs.
* If unable to determine the login failure reason, contact the [Product Support Team](https://itential.atlassian.net/servicedesk/customer/portals) for additional troubleshooting help.

## Migration to production authentication

When moving from development to production:

### Set up production authentication

Configure LDAP or SAML SSO for production environment. See:

* [Configure LDAP authentication](/itential-platform/configure/auth/ldap/configure-ldap-authentication)
* [Configure SAML SSO](/itential-platform/configure/auth/saml-sso/overview)

### Export user list

Document users and their group memberships from Local AAA.

### Create users in production

Add users to your LDAP directory or Identity Provider.

### Map groups

Create group mappings between your Identity Provider and Itential Platform groups.

### Test authentication

Verify production authentication works before decommissioning Local AAA.

### Disable Local AAA

Remove Local AAA from the AAA broker and enable production authentication.

## Next steps

#### [Manage users](/itential-platform/control-access/users-groups-roles/reference-user-accounts)

#### [Manage groups](/itential-platform/control-access/users-groups-roles/reference-groups)

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

#### [Configure SAML SSO](/itential-platform/configure/auth/saml-sso/overview)

> Set up local authentication for development and testing environments