Command line interface and utilities for working with the authentic-api and LeisureLink's federated security.
npm install @leisurelink/authentic-cliCommand line interface and utilities for working with the authentic-api and LeisureLink's federated security.
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.
``bash`
$ npm install @leisurelink/authentic-cli # or npm install -g git+ssh://git@github.com/LeisureLink/authentic-cli.git
You can verify installation by running authentic with no options or command.
`bash`
$ authentic
The command above should display usage information.
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
1. Authenticate the API
1. Identify Yourself as a User
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.*
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.
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.
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 devops@leisurelink.com.
Authentic CLI loads values for its inputs from several sources in the following order:
1. Defaults
1. Profile
1. Environment variables
1. 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.
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.
Use the configure command to create one or more user-specific profiles:
`bash`
$ 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.
All commands and inputs are described below. This information is also available via a help command:
`bash
$ 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
-H, --host
-K, --issuer-key
-I, --issuer
-A, --audience
-i, --id
-k, --key
-l, --lang
-u, --user-name
-p, --password
-v, --verbose turns on verbose logging
`
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.
`bash`
$ authentic --key cli-key.pem --issuer-key authentic-key.pub --host http://localhost:3000 \
-u admin -p soopersekritpass \
get-endpoint authentic
`bash`
$ authentic --key cli-key.pem -issuer-key authentic-key.pub --host http://localhost:3000 \
-u admin -p soopersekritpass \
create-endpoint my-new-api
`bash`
$ 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
`bash`
$ 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
`bash``
$ authentic --profile dev \
-u admin -p soopersekritpass \
get-endpoint authentic