​
Prerequisites

To get the most out of this guide, you will need to:

​
Installation

Through homebrew:

  brew tap hoophq/brew https://github.com/hoophq/brew
  brew install hoop

To upgrade it:

  brew upgrade hoop

​
Authentication

The authentication process requires either an access token or an API key to interact with the gateway. The following sections outline the various authentication scenarios when using the command line interface.

The authentication process requires knowning the gateway instance URL where the Hoop gateway is running. Our managed instances are hosted under the URL:

https://use.hoop.dev

Contact your administrator if you have a self hosted installation and don’t know this information.

​
Connection Usage Scenario

This authentication method is recommended for users who need to regularly access and manage resources within their permission scope. Users will authenticate to obtain a valid access token, which remains active based on your identity provider’s expiration policy.

This command should be executed only once in your machine. It creates and wipes the file $HOME/.hoop/config.toml in your local machine

hoop config create --api-url https://yourgateway-domain.tld

This command must be executed every time the token expires or the command above is executed.

hoop login

​
Automation Usage Scenario

​
Programmatic API Access

This authentication method is designed for administrators who need programmatic access to the API for tasks such as managing connections, configuring policies, or executing operations within automation pipelines.

Programmatic access requires static authentication credentials that can be obtained through the following methods:

​
Static API Key

A Static API Key provides persistent authentication by setting an environment variable in the gateway with a secure random string.

Configure the token in your local configuration using this command:

HOOP_TOKEN=<api-key> hoop config create --api-url https://yourgateway-domain.tld

​
Service Account

Service Account authentication is available if your identity provider supports the OAuth2 Client Credentials Grant type.

export HOOP_TOKEN="$(/tmp/issue-client-credentials-token-from-idp.sh)"
hoop config create --api-url https://yourgateway-domain.tld

Access tokens obtained from your identity provider typically have an expiration period. To maintain continuous access, create a script that can generate fresh access tokens as needed.

​
Using Environment Variables

Another way to use the command line is by exporting the following environment variables:

export HOOP_APIURL=https://use.hoop.dev
export HOOP_GRPCURL=grpcs://use.hoop.dev:8443
export HOOP_TOKEN=<your-access-token-or-api-key>
export HOOP_TLSCA=file:///path/to/ca.pem
# test it
hoop admin get userinfo

When using environment variables, it will ignore the local configuration file $HOME/.hoop/config.yaml

​
Managing Configuration

  • Configure your Gateway URL and clear any existent configuration
hoop config create --api-url https://yourgateway-domain.tld
  • Configure the Gateway URL and the gRPC URL
hoop config create
  --api-url https://yourgateway-domain.tld \
  --grpc-url grpcs://yourgateway-domain.tld:443

This flag is optional and used only to interact with connections. The --grpc-url is obtained automatically from the Api when a user Sign In (issue the hoop login command)

  • Configure the Gateway URL, the gRPC URL and the TLS Certificate Root Certificate
hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca=file:///tmp/ca.pem

# inline configuration
hoop config create
  --api-url https://yourgateway-domain.tld \
  --tls-ca="base64://$(cat /tmp/ca.pem |base64)"

This option should be used if your gateway is running with self signed certificates.

  • Show API_URL, GRPC_URL and TLS_CA configuration
hoop config view
  • Show all configuration with the access token (contains sensitive information)
hoop config view --raw
  • Show sections of configuration
hoop config view api_url
hoop config view grpc_url
hoop config view token
hoop config view tls_ca
  • Wipe Local Configuration
hoop config clear

​
Interacting with Resources

The hoop connect command allows you to create an interactive session with a remote resource. The resource include the interactive terminal console or native protocols.

​
Terminal Console

  • docker exec
  • bash
  • ssh
  • rails console
  • python console
  • kubectl exec
  • aws ecs execute-command
hoop connect bash-console
connection: bash-console | session: 53ed53f9-a5f9-45e9-bbf5-becd1f44f41e
root@5601881aa15e:/app#

​
Terminal Ad Hoc Executions

Permit triggering ad hoc executions on a connection.

  • Issue the command env to a connection with the bash as interpreter
hoop exec bash -i 'env'
  • Run the script /tmp/myscript.sh using bash as the interpreter
hoop exec bash -f /tmp/myscript.sh
  • Run the script /tmp/myscript.sh by reading it from the standard input using bash as interpreter
hoop exec bash <<EOF
env |grep -i 'id'
EOF

​
Native Protocols

The connect feature can be used to interact with native protocols such as databases, SSH, HTTP and TCP. The port is forwarded locally to the end-user, providing a secure connection to remote services.

$ hoop connect pg-prod
connection: pg-prod | session: 4619c80f-7166-487c-8c9f-9609e59ae5d6

--------------------postgres-credentials--------------------
      host=127.0.0.1 port=5433 user=noop password=noop
------------------------------------------------------------
ready to accept connections!

The connection is established through a secure tunnel by an encrypted channel when the gateway is setup with TLS. The user identity is always validated when interacting with such resources.