Directory Agent

Running a custom directory agent

Introduction

Nametag allows you to run a remote agent to perform directory integration operations on your behalf. You might want to run a directory agent if:

You don’t want to share your directory credentials with Nametag.
You want to customize how Nametag performs directory operations, such as filtering the available accounts, imposing your own authorization rules, or performing custom logging or auditing.
You want to integrate with a directory service that is not supported by Nametag.

Installing the Nametag CLI

The Nametag CLI is open source. You can install from source, or download a pre-built binary or docker container. See the CLI documentation for details. If this is your first time using the CLI, authenticate your computer with nametag auth login.

Registering a directory agent

To run a directory agent, you must first register it with Nametag. You can register an agent by running:

$ nametag directory agent register -e *ENV_ID*

Invoking this command will create a new directory and return an *AGENT_TOKEN* suitable for use with the agent. The output will be like:

Created a new directory: ca94b5d2-53e9-4bbe-b383-5826ebc79575
You can run an agent for this directory with:
  export NAMETAG_AGENT_TOKEN="*AGENT_TOKEN*"
  nametag directory agent [provider]
See 'nametag directory agent --help' for more options.

Regenerating a directory agent token

Regenerate the token if the original has been lost or compromised.

$ nametag directory agent regenerate -d *DIRECTORY_ID*

This command creates a new token for the existing directory. The output will look like:

You can run an agent for this directory with:
  export NAMETAG_AGENT_TOKEN="*AGENT_TOKEN*"
  nametag directory agent [provider]
See 'nametag directory agent --help' for more options.

Running a directory agent

To run the directory agent, use the token you obtained in the previous step. For example to run the Okta agent using the client ID and client secret:

$ NAMETAG_AGENT_TOKEN="*AGENT_TOKEN*" \
  OKTA_CLIENT_ID="*OKTA_CLIENT_ID*" \
  OKTA_CLIENT_SECRET="*OKTA_CLIENT_SECRET*" \
  OKTA_URL="*OKTA_URL*" \
   nametag directory agent okta

Alternatively, you can run the Okta agent using an API token:

$ NAMETAG_AGENT_TOKEN="*AGENT_TOKEN*" \
  OKTA_TOKEN="*OKTA_TOKEN*" \
  OKTA_URL="*OKTA_URL*" \
   nametag directory agent okta

You can also run the directory agent using a docker container:

$ docker run \
    -e NAMETAG_AGENT_TOKEN="*AGENT_TOKEN*" \
    -e OKTA_URL="https://example.okta.com" \
    -e OKTA_TOKEN="*OKTA_TOKEN*" \
    nametaginc/cli:latest \
    nametag directory agent okta

You should configure this service to run as a daemon on your system. It is perfectly safe, and perhaps even advisable, to run more than one instance of the agent across multiple systems. A second instance gives you redundancy if a host goes down, and it adds request capacity as Nametag spreads requests across every connected agent.

Concurrency

A single agent serves several requests at once. It maintains independent lanes, each one a separate websocket connection to Nametag and a separate worker process on your host.

The default is three lanes. Set --max-concurrent-requests to raise it, up to a maximum of 16:

$ nametag directory agent okta --max-concurrent-requests 4

The same value can be given as the NAMETAG_AGENT_MAX_CONCURRENT_REQUESTS environment variable, which the flag overrides when you set both.

Each lane starts its own worker process and consumes its own directory resources such as a separate connection or session against your directory service. Size the value for what your directory and the agent’s host can carry.

If a worker process fails, the agent stops every lane and exits so your process supervisor can restart the whole installation in a known state. A lane whose websocket drops attempts to reconnect on its own without disturbing the others.

Connectivity

The agent makes one outbound websocket connection per lane to nametag.co over HTTPS on port tcp/443. It will also need to be able to communicate outbound to your directory service.

Customizing the directory agent

When you specify --command to nametag directory agent, it runs the command you specify to perform directory operations. Requests are routed from Nametag to the agent process and then relayed to the standard input of the command. The command emits its responses to the standard output, which the agent relays back to Nametag. You can implement your own filters, authorization rules, or logging by writing a custom command that reads from standard input and writes to standard output.

Your command is started once per lane, so several copies of it run side by side and each one handles a single request at a time. Requests carry no affinity to a particular lane either, so anything a worker must remember between requests — a pagination cursor, for example — belongs in the request and response fields the protocol provides for it rather than in the worker’s memory. If your worker cannot run more than once on a host, start the agent with --max-concurrent-requests 1.

For example, you could write a custom command that filters the accounts returned by the Okta worker:

$ nametag directory agent register --command "nametag directory agent okta"

For details on the agent protocol, see the Directory Agent Protocol Reference