Configure local AAA authentication

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.

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

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": false
10
      }
11
    }
12
  },
13
  "brokers": ["aaa"]
14
}

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": true,
10
        "user": "localaaa_user",
11
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
12
      }
13
    }
14
  },
15
  "brokers": ["aaa"]
16
}

Add users

$
npm install --global bcrypt-cli

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

1
use LocalAAA
2
3
db.accounts.insertOne({
4
  "username": "admin@pronghorn",
5
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
6
  "firstname": "Admin",
7
  "groups": ["pronghorn_admin"],
8
  "activeTenant": "*",
9
  "tenants": []
10
})

1
db.groups.insertOne({
2
  "name": "pronghorn_users",
3
  "group": "pronghorn_admin"
4
})

Secure MongoDB connectivity

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

Create MongoDB users

1
use admin
2
3
db.createUser({
4
  "user": "admin",
5
  "pwd": "secure-admin-password",
6
  "roles": [
7
    {"role": "root", "db": "admin"},
8
    {"role": "userAdminAnyDatabase", "db": "admin"},
9
    {"role": "clusterMonitor", "db": "admin"},
10
    {"role": "dbOwner", "db": "LocalAAA"},
11
    {"role": "dbOwner", "db": "pronghorn"}
12
  ]
13
})

1
use admin
2
3
db.createUser({
4
  "user": "pronghorn",
5
  "pwd": "secure-pronghorn-password",
6
  "roles": [
7
    {"role": "dbOwner", "db": "pronghorn"},
8
    {"role": "dbOwner", "db": "LocalAAA"},
9
    {"role": "clusterMonitor", "db": "admin"}
10
  ]
11
})

1
use LocalAAA
2
3
db.createUser({
4
  "user": "localaaa_user",
5
  "pwd": "secure-localaaa-password",
6
  "roles": [
7
    {"role": "dbOwner", "db": "LocalAAA"}
8
  ]
9
})

Enable MongoDB authentication

$
sudo vi /etc/mongod.conf

1
# network interfaces
2
net:
3
  port: 27017
4
  bindIp: 0.0.0.0
5
6
# security
7
security:
8
  authorization: enabled

$
sudo systemctl restart mongod

Update Platform configuration

$
sudo vi /opt/pronghorn/current/properties.json

1
{
2
  "id": "profile1",
3
  "mongoProps": {
4
    "credentials": {
5
      "dbAuth": true,
6
      "user": "pronghorn",
7
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
8
    },
9
    "db": "pronghorn",
10
    "url": "mongodb://127.0.0.1:27017"
11
  }
12
}

1
{
2
  "id": "mongo",
3
  "properties": {
4
    "credentials": {
5
      "dbAuth": true,
6
      "user": "pronghorn",
7
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
8
    },
9
    "db": "pronghorn",
10
    "url": "mongodb://127.0.0.1:27017"
11
  }
12
}

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": true,
10
        "user": "localaaa_user",
11
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
12
      }
13
    }
14
  },
15
  "brokers": ["aaa"]
16
}

$
sudo systemctl restart itential-platform

$
sudo systemctl status itential-platform

Encrypt passwords

Itential recommends encrypting all passwords. You can use:

• HashiCorp Vault (recommended) - See Configure HashiCorp Vault
• CyberArk CCP - See Configure CyberArk
• Legacy $ENC encryption (deprecated)

User document structure

Account document example

1
{
2
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d4d"),
3
  "username": "admin@pronghorn",
4
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
5
  "firstname": "Admin",
6
  "lastname": "User",
7
  "email": "admin@example.com",
8
  "groups": ["pronghorn_admin", "developers"],
9
  "activeTenant": "*",
10
  "tenants": []
11
}

Group document example

1
{
2
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d56"),
3
  "name": "pronghorn_users",
4
  "group": "pronghorn_admin"
5
}

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:

$
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 for additional troubleshooting help.

Migration to production authentication

When moving from development to production:

Next steps

title: Configure local AAA authentication sidebar-title: Local AAA description: Set up local authentication for development and testing environments slug: auth/aaa/configure-local-aaa-authentication

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.

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

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": false
10
      }
11
    }
12
  },
13
  "brokers": ["aaa"]
14
}

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": true,
10
        "user": "localaaa_user",
11
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
12
      }
13
    }
14
  },
15
  "brokers": ["aaa"]
16
}

Add users

$
npm install --global bcrypt-cli

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

1
use LocalAAA
2
3
db.accounts.insertOne({
4
  "username": "admin@pronghorn",
5
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
6
  "firstname": "Admin",
7
  "groups": ["pronghorn_admin"],
8
  "activeTenant": "*",
9
  "tenants": []
10
})

1
db.groups.insertOne({
2
  "name": "pronghorn_users",
3
  "group": "pronghorn_admin"
4
})

Secure MongoDB connectivity

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

Create MongoDB users

1
use admin
2
3
db.createUser({
4
  "user": "admin",
5
  "pwd": "secure-admin-password",
6
  "roles": [
7
    {"role": "root", "db": "admin"},
8
    {"role": "userAdminAnyDatabase", "db": "admin"},
9
    {"role": "clusterMonitor", "db": "admin"},
10
    {"role": "dbOwner", "db": "LocalAAA"},
11
    {"role": "dbOwner", "db": "pronghorn"}
12
  ]
13
})

1
use admin
2
3
db.createUser({
4
  "user": "pronghorn",
5
  "pwd": "secure-pronghorn-password",
6
  "roles": [
7
    {"role": "dbOwner", "db": "pronghorn"},
8
    {"role": "dbOwner", "db": "LocalAAA"},
9
    {"role": "clusterMonitor", "db": "admin"}
10
  ]
11
})

1
use LocalAAA
2
3
db.createUser({
4
  "user": "localaaa_user",
5
  "pwd": "secure-localaaa-password",
6
  "roles": [
7
    {"role": "dbOwner", "db": "LocalAAA"}
8
  ]
9
})

Enable MongoDB authentication

$
sudo vi /etc/mongod.conf

1
# network interfaces
2
net:
3
  port: 27017
4
  bindIp: 0.0.0.0
5
6
# security
7
security:
8
  authorization: enabled

$
sudo systemctl restart mongod

Update Platform configuration

$
sudo vi /opt/pronghorn/current/properties.json

1
{
2
  "id": "profile1",
3
  "mongoProps": {
4
    "credentials": {
5
      "dbAuth": true,
6
      "user": "pronghorn",
7
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
8
    },
9
    "db": "pronghorn",
10
    "url": "mongodb://127.0.0.1:27017"
11
  }
12
}

1
{
2
  "id": "mongo",
3
  "properties": {
4
    "credentials": {
5
      "dbAuth": true,
6
      "user": "pronghorn",
7
      "passwd": "$SECRET_mongodb-creds $KEY_pronghorn-password"
8
    },
9
    "db": "pronghorn",
10
    "url": "mongodb://127.0.0.1:27017"
11
  }
12
}

1
{
2
  "id": "Local AAA",
3
  "type": "local_aaa",
4
  "properties": {
5
    "database": {
6
      "db": "LocalAAA",
7
      "url": "mongodb://127.0.0.1:27017",
8
      "credentials": {
9
        "dbAuth": true,
10
        "user": "localaaa_user",
11
        "passwd": "$SECRET_mongodb-creds $KEY_localaaa-password"
12
      }
13
    }
14
  },
15
  "brokers": ["aaa"]
16
}

$
sudo systemctl restart itential-platform

$
sudo systemctl status itential-platform

Encrypt passwords

Itential recommends encrypting all passwords. You can use:

• HashiCorp Vault (recommended) - See Configure HashiCorp Vault
• CyberArk CCP - See Configure CyberArk
• Legacy $ENC encryption (deprecated)

User document structure

Account document example

1
{
2
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d4d"),
3
  "username": "admin@pronghorn",
4
  "password": "$2a$10$5KXKzv9Ech1w2nOSSPWCMuaqOS6aFCpKZV6IzfaYRRgN/xkwXYso2",
5
  "firstname": "Admin",
6
  "lastname": "User",
7
  "email": "admin@example.com",
8
  "groups": ["pronghorn_admin", "developers"],
9
  "activeTenant": "*",
10
  "tenants": []
11
}

Group document example

1
{
2
  "_id": ObjectId("5b6f9fc3fe38e3bd73795d56"),
3
  "name": "pronghorn_users",
4
  "group": "pronghorn_admin"
5
}

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:

$
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 for additional troubleshooting help.

Migration to production authentication

When moving from development to production:

Next steps