CLI Authentication

Every use of socotra-app CLI tool must be authenticated with Marketplace API.

socotra-app authentication is following traditional Client-Id/API-Key ( also known as Client Secret) keypair approach.

Each keypair is specific to an organization where it was generated and enables CLI access only to API endpoints in Publish API.

Unlike website authentication with JWT tokens, keypair-based authentication doesn't expire and can be used in scripts or CI/CD pipelines. Organizations can generate as many API keypairs as needed.

With admin priviledges, API key can be explicitly re-generated, which is useful for organizing periodic key rotation, often prescribed by organization's security policies.

Keypair creation

To create a new CLI keypair, organization admin must use Merketplace's website interface available in Dashboard -> API Keys. Admin needs to provide a name for a keypair, which is useful to identify such keypair purposes later and system will generate random Client-Id and random API-Key values.

Note

Steps

1. Provide a name for a keypair:

2. Save generated Id and secret securely for later use.

Authenticate socotra-app using CLI options

Basic example of how developer can authenticate socotra-app CLI commands on every call is to pass Client-ID and API-key values as command-line options

# authenticate using in-line options
socotra-app publish docker minimal-app:latest --client-id <Client-ID> --client-secret <API-Key>

Although this is a valid use-case to provide auth details for a cli call, it has certain drawbacks:

• CLI commands become quite long and cumbersome to input.
• Client-Id and API-Key are being recorded in shell's command history.
  • This behaviour may cause security problems later, as these sensitive values will be stored in shell's history as plain text and can be easily viewed or recovered (if someone would gain unauthorized access to shell's history on developer's machine).

There are some ways to prevent command to be recorded in shell's history that developer may already know or use. Such as prepending command with whitespace and configuring bash's HISTIGNORE or HISTCONTROL flags in certain way.

# this command recorded in shell's history with default bash configuration
socotra-app publish docker minimal-app:latest --client-id <Client-ID> --client-secret <API-Key>
# this command starts with <whitespace> and will not be recorded in history by default
  socotra-app publish docker minimal-app:latest --client-id <Client-ID> --client-secret <API-Key>

But there are easier and more secure ways to provide auth details for socotra-app CLI commands.

Authenticate socotra-app using environment variables

One of the common authentication needs is to establish an authenticated session in which socotra-app cli can be used to perform certain actions from a stateless environment (e.g. docker container, bastion ssh session, stateless CI/CD agent instance).

To address such scenario, on every invocation, socotra-app CLI looks for the following environment variables for a keypair values:

• SMP_CLIENT_ID - Client-Id value.
• SMP_CLIENT_SECRET - API-Key value.

Developer can specify, in a shell or using CI/CD capabilities, all necessary session authentication information for CLI to work:

# start commands with whitespace to avoid secrets to be recorded in shell history
 export SMP_CLIENT_ID=<Client-Id>
 export SMP_CLIENT_SECRET=<API-Key>

CLI would automatically read these values and use them as authentication credentials when calling Publish API endpoints.

To cleanup environment vars, when session is no longer neede, use following shell commands:

unset SMP_CLIENT_ID
unset SMP_CLIENT_SECRET

Authentication using System's keychain

It's not always convenient for a developer to use env variables for CLI authentication, as they may often switch between terminals, ides and sessions.

To address this use case, socotra-app CLI supports system's keychain interface to store Client-Id and API-Key values securely. It uses keytar package to read and write app-specific keys in system's keychain.

To store Client-Id and API-Key securely, developer can use socotra-app interactive login process to provide Client-Id and API-key values:

# interactive login flow
socotra-app login

Which will show an interactive flow with prompts to input Client-Id and API-key

   _____                  __                         ___
  / ___/____  _________  / /__________ _            /   |  ____  ____
  \__ \/ __ \/ ___/ __ \/ __/ ___/ __ `/  ______   / /| | / __ \/ __ \
 ___/ / /_/ / /__/ /_/ / /_/ /  / /_/ /  /_____/  / ___ |/ /_/ / /_/ /
/____/\____/\___/\____/\__/_/   \__,_/           /_/  |_/ .___/ .___/
                                                       /_/   /_/
Marketplace / © 2023 Socotra, Inc / support@socotra.com / v1.3.0
? Enter the Client ID: <Client-Id>
? Enter Client Secret: <API-Key>

Alternatively, to skip interactive cli prompt, developer can specify Client-Id and Client Secret as tool parameters:

# non-interactive authentication written to system's keychain (starts with space to avoid shell's history)
 socotra-app login --client-id <Client-ID> --client-secret <API-Key>

Credentials priority

In the situations when socotra-cli is called with multiple different authentication options, such as - inline, env variables and system's keychain all have valid Client-Id and API-Key values, CLI uses the following priority order (lower number means higher priority).

1. In-line CLI values - this option has the highest priority and will be used even if env variables are present.
2. Environment variables - This option is tried if no in-line auth values has been provided.
3. System's keychain - This option is tried if no auth details provided via inline or env variables.

If no valid auth details are provided to socotra-app CLI using one of the above methods - an API call with no authentication will be send to Publish API. If a taret enpoint expects API auth details - such call will receive "403 Forbidden" status code response.

Note: