@leisurelink/authentic-cli

authentic-cli

Command line interface and utilities for working with the authentic-api and LeisureLink's federated security.

Installation

First, install a bunch of dependencies as documented on the Node Development Setup Guide.

Then, use npm to install the CLI directly from this repository. It is recommended that you install the CLI globally.

$ npm install @leisurelink/authentic-cli # or npm install -g git+ssh://[e-mail]/LeisureLink/authentic-cli.git

You can verify installation by running authentic with no options or command.

$ authentic

The command above should display usage information.

Concepts

The Authentic API and CLI both require that the other endpoint authenticate itself by signing all communication. To execute any command that communicates with Authentic API, you must provide the CLI with input to perform the following tasks:

1. Identify the CLI as an Endpoint
2. Authenticate the API
3. Identify Yourself as a User

Identify the CLI as an Endpoint

The CLI can impersonate any endpoint. You must indicate which endpoint you want it to impersonate by supplying an endpoint key id. The CLI will include the supplied endpoint key id in messages it sends to the API. You must also supply a private key that the CLI can use to sign messages it sends to the API. The API will use the endpoint key id to lookup a previously registered public key that it will use to verify the signature of the message. This process is how the API authenticates the endpoint that is calling it.

NOTE: The CLI uses 'scripts/internal' as a default endpoint key id if another value is not provided. This identifies it as the 'scripts' endpoint and is correct for most situations. You'll only want to override this default when you need to impersonate another endpoint. In that case you'll supply that endpoint's endpoint key id and private key.

Authenticate the API

You must supply a public key that the CLI can use to verify the signature included in the response from the API. This process is how the CLI authenticates the API it is calling.

Identify Yourself as a User

Authenticating the CLI as an endpoint will only authorize commands for which that endpoint has been granted permission. The 'scripts' endpoint the CLI identifies itself as by default has very limited permission (only 'auth'). To really do anything, you must identify yourself as a user by supplying your username and password. The API will then authorize commands for which you have been granted permission instead of those for which the endpoint has been granted permission.

Obtaining Keys and User Accounts

For information about setting up a new installation of the Authentic API and gaining CLI access to it, see the Getting Started section of the Authentic API README file. To gain CLI access to an existing installation of Authentic API in another environment, email [e-mail].

Usage

Authentic CLI loads values for its inputs from several sources in the following order:

1. Defaults
2. Profile
3. Environment variables
4. Command-line arguments

Values loaded from later sources will override those from sources loaded earlier.

The recommended way to use the CLI manually is to configure one or many profiles and load one by using the profile option to execute a command. To use the CLI from within a script, it may be best to use command line arguments or environment variables.

Defaults

The CLI contains hardcoded default values for inputs when a reasonable default exists. These defaults are also suggested when configuring a new profile. There are no default values for host, issuer-key, or key.

Profile

Use the configure command to create one or more user-specific profiles:

$ authentic configure

The CLI will prompt for the required values and store them in a configuration file (located at ~/.authentic).

You can then use the --profile option instead of specifying a value for each input with every call (example). Authentic always loads the "default" profile, allowing for environment variables and command line arguments to override profile-specified values.

Commands and Inputs

All commands and inputs are described below. This information is also available via a help command:

$ authentic --help

  Usage: authentic [options] [command]


  Commands:

    create-user [options] [principalId] [firstName] [lastName] [email]  Creates a user principal; the principalId is analagous to user-name and must be unique within the system.
    delete-user [systemId]                                              Delete a user principal; the systemId is the system generated identifier for the principal.
    create-password [systemId] [password]                               Creates a password for the specified principal
    user-query [options] [pattern]                                      Queries users by the specified pattern.
    create-endpoint [principalId]                                       Creates an endpoint for the specified principalId.
    delete-endpoint [principalId]                                       Delete an endpoint for the specified principalId.
    add-apikey [principalId] [apiKey]                                   Add an api key for the specified principalId
    delete-apikey [apiKey]                                              Delete an api key.
    get-endpoint [principalId]                                          Gets an endpoint.
    get-endpoint-key [principalId] [keyId]                              Gets an endpoint key.
    add-endpoint-key [principalId] [keyId] [keyPath]                    Adds an endpoint key for the specified principal.
    add-claimset-spec [csPath]                                          Adds a claimset spec for a particular claimset specification id.
    get-claimset-spec [csid]                                            Gets a registered claimset spec.
    set-endpoint-claim [principalId] [claimId] [value]                  Sets an endpoint claim to a value
    remove-endpoint-claim [principalId] [claimId]                       Sets an endpoint claim to a value
    register-endpoint [principalId] [keyId] [keyPath]                   Registers the endpoint with the specified keyId and keyPath.
    configure                                                           Configures a new profile, or the default profile for the current user

  Utilities for communicating with LeisureLink's authentic-api from the command line. Many of the supported commands have additional options: 'authentic [command] --help' to view the specifics.

  Options:

    -h, --help                     output usage information
    -V, --version                  output the version number
    --profile <profile>            Use a specific profile from your credential file
    -H, --host <host>              the authentic-api host uri, env: AUTHENTIC_HOST, default: http://localhost:8081.
    -K, --issuer-key <issuer-key>  path to the authentic-api host's public key, env: JWT_ISSUER_KEY_PATH
    -I, --issuer <issuer>          the JWT issuer, env: JWT_ISSUER, default: test
    -A, --audience <audience>      the JWT audience, env: JWT_AUDIENCE, default: test
    -i, --id <id>                  the CLI endpoint's id, env: ENDPOINT_ID, default: scripts/internal
    -k, --key <key>                path to the CLI endpoint's key, env: ENDPOINT_KEY_PATH
    -l, --lang <lang>              the CLI's lang, default: en-US
    -u, --user-name <user-name>    the user with authority to perform the operation
    -p, --password <password>      the user's password
    -v, --verbose                  turns on verbose logging

About Issuer and Audience

tl;dr - No need to specify these.

Authentic API returns a JSON Web Token (JWT) as the result of a user authentication call. The JWT contains an issuer claim, identifying who issued the token, and an audience claim, identifying who is intended to process the JWT. The issuer and audience inputs to the CLI allow you to specify which values the JWT should contain in order to be considered valid. Currently the CLI ignores the fact that the JWT is not valid due to the issuer and audience not matching what you said you would accept. So you can let the CLI use the default values and work effectively with any deployment of Authentic API.

Examples

Query for an endpoint

$ authentic --key cli-key.pem --issuer-key authentic-key.pub --host http://localhost:3000 \
    -u admin -p soopersekritpass \
    get-endpoint authentic

Create a new endpoint

$ authentic --key cli-key.pem -issuer-key authentic-key.pub --host http://localhost:3000 \
    -u admin -p soopersekritpass \
    create-endpoint my-new-api

Add key to endpoint

$ openssl genrsa -out ./my-new-api-key.pem 2048
$ openssl rsa -pubout -in ./my-new-api-key.pem -out ./my-new-api-key.pub
$ authentic -k cli-key.pem -K authentic-key.pub -H http://localhost:3000 \
    -u admin -p soopersekritpass \
    add-endpoint-key my-new-api my-new-api-key ./my-new-api-key.pub

Query for an endpoint using environment variables

$ ENDPOINT_KEY_PATH=cli-key.pem
$ JWT_ISSUER_KEY_PATH=authentic-key.pub
$ AUTHENTIC_HOST=https://localhost:3000
$ authentic -u admin -p soopersekritpass \
    get-endpoint authentic

Query for an endpoint using profile

$ authentic --profile dev \
    -u admin -p soopersekritpass \
    get-endpoint authentic