> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/aerospike.md).

# Aerospike connector

This section describes how to configure the Aerospike connector to connect with the Aerospike NoSQL, key-value, and document-oriented database.

Aerospike is a **NoSQL, key-value, and document-oriented database**, not a relational one — so it lacks traditional RDBMS concepts like roles, privileges, or users (as in PostgreSQL or Oracle). However, the **Enterprise Edition** provides **Access Control and Security features** that enable admin, user, and role-level access — and that is what the Aerospike connector manages.

For more information, visit the [Aerospike blog portal](https://aerospike.com/blog/aerospike-data-browser/).

| Operation                           | Supported                        |
| ----------------------------------- | -------------------------------- |
| Create user                         | ✅                                |
| Reset password                      | ✅                                |
| Delete user                         | ✅                                |
| Search users                        | ✅ (`show users`, single user)    |
| Search groups (Aerospike **roles**) | ✅ (`show roles`, single role)    |
| Group create/delete                 | ❌ Roles are managed in Aerospike |
| Test connection                     | ✅                                |

## Use cases

* Managing **Aerospike Enterprise database accounts** from OpenIAM — create users, assign their access roles, reset passwords, and remove them.
* **Importing Aerospike users and roles** into OpenIAM for visibility and access review.
* Requires Aerospike **Enterprise Edition** — Community Edition has no access-control model to manage.

## Versions and compatibility

The end application is **Aerospike Enterprise Edition**. The edition matters more than the version: access control is an Enterprise feature, and Community Edition has no users, roles or privileges for a connector to manage at all.

<table><thead><tr><th width="202">Property</th><th>Value</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>Aerospike <strong>Enterprise Edition</strong>, with Access Control enabled</td></tr><tr><td><strong>Not supported</strong></td><td>Aerospike Community Edition — it has no access-control model</td></tr><tr><td><strong>Managed objects</strong></td><td>Aerospike users, and the roles granted to them</td></tr><tr><td><strong>Roles</strong></td><td>Created in Aerospike; the connector reads and assigns them but does not create them</td></tr></tbody></table>

## Prerequisites

* Aerospike **Enterprise Edition** with Access Control enabled.
* An Aerospike admin account for the connector.
* Network access from the connector host to the Aerospike host/port.

## Installing the connector

Deploy the connector as with other OpenIAM connectors: enable its service in the Kubernetes deployment configuration, or run its JAR under RPM — see [Connectors via RPM](/installation/rpm/rpm-single-node/add-a-connector.md).

## Starting, stopping, and restarting

Manage the connector like any OpenIAM connector service for your deployment type: the systemd connector unit under RPM, or the deployment under Kubernetes.

## Verifying the connector is running

{% stepper %}
{% step %}
In the Webconsole, open the managed system — the **Running connector status** indicator must be green.
{% endstep %}

{% step %}
Click **Test Connection** — it must return success.
{% endstep %}

{% step %}
Run the **Aerospike User Example** sync with `*` and confirm results in **Synchronization History**.
{% endstep %}
{% endstepper %}

## Troubleshooting

| Symptom                           | Likely cause                                                 | Resolution                                                                                                |
| --------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Connection status not green       | Wrong host/port/credentials, or Access Control not available | Verify the managed-system fields; confirm you are running Aerospike **Enterprise** with security enabled. |
| Sync returns an error             | Unsupported query                                            | Only `show users` / `show roles` / `*` / single-object queries are supported.                             |
| User created with unexpected name | Username pattern                                             | Usernames are generated as `<firstname-lastname>` and are case-sensitive.                                 |

See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes).

## Registering the connector in OpenIAM

The connector and the **Aerospike Managed System** ship pre-registered. If registering manually, add the connector under **Provisioning → Connectors** with its queue name and attach it to the managed system — see [Registering the connector](/administration-guide/lifecycle/connectors-and-managed-systems.md).

## Configuring the managed system

Open the **Aerospike Managed System** under **Provisioning → Managed system** and fill in:

<table><thead><tr><th width="160">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong>Host URL</strong></td><td>The Aerospike host. On a single-node Docker deployment this is the bridge address, for example <code>172.17.0.1</code></td></tr><tr><td><strong>Port</strong></td><td><code>3000</code>, Aerospike's default client port</td></tr><tr><td><strong>Login Id</strong></td><td>An Aerospike admin account</td></tr><tr><td><strong>Password</strong></td><td>That account's password</td></tr></tbody></table>

Save, then check the **Running connectors status** column on the Managed System dashboard. Green means the connector answered; *No active connectors found* means it is not reachable on its queue.

## Attribute mapping and policy map

User creation maps the OpenIAM user to an Aerospike account. The username is built as `<firstname-lastname>` and is **case-sensitive**. Access is granted through OpenIAM roles, each of which corresponds to an Aerospike role.

{% stepper %}
{% step %}
**Create a role for the Aerospike access**

**Access Control → Role → Create a new role**. Set **Role type** to *Provision Role*, give it a name such as `Aerospike Role`, set **Role Managed System** to the Aerospike managed system, and leave **Status** as *Active*.
{% endstep %}

{% step %}
**Create the user**

Fill in **First Name**, **Last Name**, **Metadata Type** and an email address. The first and last names are what the Aerospike username is derived from, so they decide the account name.
{% endstep %}

{% step %}
**Assign the role and save**

On **Access Rules**, pick the Aerospike managed system and the role created above, then save. The user's **User Identities** panel then lists two rows — the OpenIAM identity and the Aerospike one — and the Aerospike row reaches *Provision Status* **SAVED** and *Status* **ENABLED** once the connector has done the work.
{% endstep %}
{% endstepper %}

## Reconciliation and synchronization

Two synchronization configurations ship with the connector, one for users and one for roles. They differ only in object type, filter and scripts.

| Setting                    | **Aerospike User Example**                                      | **Aerospike Group Example**                                       |
| -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Synchronize object**     | User                                                            | Group                                                             |
| **OpenIAM field name**     | `PRINCIPAL NAME`                                                | `NAME (for non-user objects only)`                                |
| **Source attribute name**  | `username`                                                      | `groupname`                                                       |
| **Validation rule**        | `/sync/user/aerospike/AerospikeUserSampleValidation.groovy`     | `/sync/group/aerospike/AerospikeGroupSampleValidation.groovy`     |
| **Transformation rule**    | `/sync/user/aerospike/AerospikeUserSampleTransformation.groovy` | `/sync/group/aerospike/AerospikeGroupSampleTransformation.groovy` |
| **Attribute names lookup** | `/sync/user/aerospike/AerospikeUserSyncAttributes.groovy`       | `/sync/group/aerospike/AerospikeGroupSyncAttributes.groovy`       |

Set the search string in **SQL Query / Directory Filter**. Only these forms are accepted, and anything else raises an error:

| To find    | Users                  | Roles                  |
| ---------- | ---------------------- | ---------------------- |
| Everything | `show users` or `*`    | `show roles` or `*`    |
| One record | `show user <username>` | `show role <rolename>` |

Use **Test connection** to validate, then **Save**. Synchronization runs in the background, and **Synchronization History** records each run as three entries — `SYNCHRONIZATION`, `PROVISIONING_USER_SEARCH` or `PROVISIONING_GROUP_SEARCH`, and `SYNCHRONIZATION_THREAD`.

### What a synchronized record looks like

Opening a history entry shows the request body for each object the run processed. A user:

{% code overflow="wrap" %}

```json
{
    username: "Aerospike-User",
    roles: "read",
    connectionsInUse: "0"
}
```

{% endcode %}

And a role, which carries the Aerospike privilege that defines it:

{% code overflow="wrap" %}

```json
{
    groupname: "data-admin",
    privilege: "DATA_ADMIN",
    value: "data-admin",
    namespace: "null",
    setName: "null",
    readQuota: "0",
    writeQuota: "0"
}
```

{% endcode %}

{% hint style="info" %}
`namespace` and `setName` arrive as the **string** `"null"` rather than as a JSON null when the role is not scoped to one, so a transformation script testing for an absent value has to compare against that string.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/connector-configuration/aerospike.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.