Directory Agent

Caution: This feature is in beta. While we do not expect these interfaces to change, they might. If you have any issues, please report them to help@nametag.co.

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 for the directory agent if the original token has been lost or forgotten. This action creates a new token.

$ nametag directory agent regenerate -d DIRECTORY-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:

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 the OKTA 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, for redundancy.

Connectivity

The agent makes an outbound websocket connection 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.

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