Skip to content

Runbook: Virtual User & IP Allowlist Management

Manage virtual users and IP-to-user mappings on the Research Assistant. Virtual users are named identities that the system assigns to requests arriving from registered IP addresses, allowing those requests to authenticate without end-user credentials.

Prerequisite: complete CLI Setup before proceeding.

Background

Two entities are managed here:

  • Virtual users — named identities (e.g. "Acme Field Office"). Each maps to a set of IP addresses that are permitted to use it.
  • IP mappings — associations between a source IP address and a virtual user. When a request arrives from a registered IP, the backend issues a short-lived JWT identifying that virtual user.

Virtual User Management

All commands below target PROD. Swap --profile prod for --profile uat to target UAT.

List all virtual users

altaforge-ra-cli --profile prod api admin virtual-user list

Output is a JSON array. The id field is the USER_ID required by other commands.

[
  { "id": 1, "name": "Acme Field Office" },
  { "id": 2, "name": "Regional Support Hub" }
]

Add a virtual user

altaforge-ra-cli --profile prod api admin virtual-user add "Location Name"

The new user is printed as JSON. Note the id — you will need it when mapping IPs.

Rename a virtual user

altaforge-ra-cli --profile prod api admin virtual-user update <USER_ID> "New Display Name"

Delete a virtual user

altaforge-ra-cli --profile prod api admin virtual-user delete <USER_ID>

Warning: You cannot delete a virtual user while it still has IP mappings. Run ip-mapping list and delete the relevant mappings first.

IP Mapping Management

List all IP mappings

altaforge-ra-cli --profile prod api admin ip-mapping list

Output is a JSON array. The id field is the MAPPING_ID required to delete a mapping.

[
  { "id": 3, "ipAddress": "203.0.113.10", "virtualUserId": 1 },
  { "id": 4, "ipAddress": "203.0.113.11", "virtualUserId": 1 }
]

Map an IP to a virtual user

altaforge-ra-cli --profile prod api admin ip-mapping add <IP_ADDRESS> <USER_ID>

Example — map 203.0.113.10 to virtual user with ID 1:

altaforge-ra-cli --profile prod api admin ip-mapping add 203.0.113.10 1

Remove an IP mapping

altaforge-ra-cli --profile prod api admin ip-mapping delete <MAPPING_ID>

Use ip-mapping list first to find the MAPPING_ID for the address you want to remove.

Verify an IP Mapping

After adding an IP mapping, confirm it is working by requesting an IP allowlist token from that IP:

altaforge-ra-cli --profile prod api admin auth get-ip-token --decode

This calls POST /auth/ip-token using the machine's outbound IP. The backend issues a short-lived JWT if the calling IP is registered. A decoded token containing a name claim matching the expected virtual user name (and a sub claim containing the virtual user ID) confirms the mapping is working. A 401 Unauthorized response means the IP is not registered or the mapping has not propagated yet (wait a few seconds and retry).

Note: This call does not require a bearer token — it is the mechanism that end-user requests use to obtain one.

Common Workflows

Onboard a new office or IP address

  1. Confirm the public IP for the new location with the requestor.
  2. Check whether a virtual user for that location already exists: 
    altaforge-ra-cli --profile prod api admin virtual-user list
  3. If no matching user exists, create one: 
    altaforge-ra-cli --profile prod api admin virtual-user add "Location Name"
    Note the id in the output.
  4. Map the IP to the virtual user: 
    altaforge-ra-cli --profile prod api admin ip-mapping add <IP_ADDRESS> <USER_ID>
  5. Verify with get-ip-token from that IP, or ask the requestor to confirm access.

Remove an IP address (e.g. office relocation)

  1. Find the mapping ID: 
    altaforge-ra-cli --profile prod api admin ip-mapping list
  2. Delete the mapping: 
    altaforge-ra-cli --profile prod api admin ip-mapping delete <MAPPING_ID>
  3. If the virtual user is no longer needed, delete it: 
    altaforge-ra-cli --profile prod api admin virtual-user delete <USER_ID>

Apply the same change to UAT first

Replace --profile prod with --profile uat in any command above. UAT and PROD are independent; changes to one do not affect the other.

Escalation

If a command returns an unexpected error, escalate to the development team with:

  • The exact command run.
  • The full error output.
  • The environment (UAT or PROD) and approximate time.