Manage Agents

Private preview: This feature is available to select accounts. Contact your Immuta representative for details.

Register and manage agents

Create an agent

Required Immuta permission: USER_ADMIN

Register an agent in Immuta from your identity provider, by creating a new agent in Immuta, or by converting an existing user to an agent. Expand the blocks below for instructions on these methods.

Add an agent from your identity provider

1. See the how-to guide for your identity management protocol to register an existing agent in Immuta.

2. Click Identities and select Users.

3. Click the overflow menu in the Actions column of the agent you just registered and click Configure dependencies.

4. Copy the script provided in the modal that appears and and run that script in your data platform.

Create a new agent using the Immuta UI

1. Click Identities and select Agents.

2. Click New agent.

3. Enter a Name for your agent, select an Owner, and provide an optional description.

4. Click Create agent.

5. Copy the script provided in the modal that appears and run that script in your data platform.

Convert an existing user to an agent

User will lose all Immuta permissions If converting a user to an agent, all Immuta permissions will be removed. Agents can only act through APIs and cannot log in to Immuta.

1. Click Identities and select Users.

2. Click the overflow menu in the Actions column of the user you want to convert to an agent and select Convert to agent.

3. Click Convert to agent again to confirm your changes.

4. Copy the script provided in the modal that appears and run that script in your data platform.

Generate an API key for your agent

Requirement: USER_ADMIN Immuta permission or own the agent

The agent will use this API key to make requests to the Immuta API to vend and delete ephemeral roles.

With the UI

1. Click Identities and select Agents.

2. Click the name of the agent you want to generate the API for.

3. Navigate to the API Keys tab and click Generate API Key.

4. Enter an API key name and click Generate key.

This API key can now be added to your agent service so that it can use it when requesting the ephemeral role.

With the API

Copy the request example below and replace the values with your own as directed to generate the agent's API key.

curl -X 'POST' \
    'https://www.organization.immuta.com/bim/iam/{iamid}/user/{userid}/apikeys' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <USER_ADMIN_TOKEN>' \
    -d '{
    "name": "Marketing department agent API key",
    "expiration": "2027-03-23"
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {iamid} request parameter with the unique identifier of your identity provider. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the agent in Immuta, this value is bim.

3. Replace the {userid} request parameter with the unique identifier of the agent. You can get this ID through the Immuta API and using the agent's name as a search filter. Or it is presented in the Agent table.

4. Change the payload values to your own, where

   • name is the name of the agent's API key.

   • expiration is the date the API key expires.

This API key can now be added to your agent service so that it can use it when requesting the ephemeral role.

Assign groups or attributes to your agent

Requirement: USER_ADMIN Immuta permission or own the agent

Opt to assign groups and attributes to the agent, just like you would for a human user. Once these entitlements are added, they can be used in global policies to target agents and grant or limit their access to data.

1. Click Identities and select Agents.

2. Click the name of the agent you want to add groups or attributes to.

3. Navigate to the Attributes or Groups tab to add these entitlements to the agent:

   • Attributes: Click Add Attributes.

     1. Begin typing the attribute name in the Attribute text box. If the attribute already exists, select it from the dropdown list. If the attribute does not exist yet, enter the full name of the attribute, and then select it from the dropdown.

     2. In the Attribute Value text box, enter a value. If the value already exists, select it from the dropdown list. If the value does not exist, enter the full name, and then select it from the dropdown.

     3. Click Close.

   • Groups: Click Add Groups.

     1. Begin typing in the Search by Group Name text box. If you need to create a new group, follow the instructions on the Manage attributes and groups page, and then add the agent to the group.

     2. Click the name in the dropdown list to add the agent to the group.

     3. Click close.

Map the agent to external data platforms

Requirement: USER_ADMIN Immuta permission or own the agent

Map external usernames to the agent account in Immuta to ensure Immuta properly enforces policies.

The instructions below illustrate how to do this for individual agents, but you can also configure external mapping in your Identity provider connection on the app settings page.

1. Click Identities and select Agents.

2. Click the name of the agent you want to map to external data platforms.

3. Navigate to the External Mapping tab.

4. Click Edit for the data platform username you want to map to and complete the fields in the modal that appears. For guidance on what to enter in these fields, see the External user ID mapping page.

View agent activity

1. Click Identities and select Agents.

2. Click the name of the agent you want to view.

3. Click the Activity tab.

This view displays a list of vended roles, the vended role expiration dates, and the users the agent was acting on behalf of.

Disable or delete agents

Deleting agents

Only agents created in the Immuta UI can be deleted from the agents page.

Requirement: USER_ADMIN Immuta permission or own the agent

1. Click Identities and select Agents.

2. Click the overflow menu in the Action column of the agent you want to disable or delete and select Disable or Delete.

3. Click Disable or Delete again to confirm your changes.