Automation with Golang SDK

The Golang Software Development Kit (SDK) is a RESTful client with OAuth2 support to access the PrivX API and offers a high-level abstraction to programmatically configure your PrivX instances.

PrivX SDK composes API client from three independent layers:

• /restapi generic HTTPS transport layer
• /oauth implements OAuth2 access token grant flows
• /api/... type-safe implementation of PrivX API

Here is a typical workflow required to setup the client:

// 1. Create Authorizer and Access Token Provider
auth := oauth.WithClientID(
restapi.New(/* use restapi options to config http */),

// Use oauth2 options to config authorizer
oauth.Access(/* ... */),
oauth.Secret(/* ... */),
)

// 2. Create HTTP transport for PrivX API
curl := restapi.New(
restapi.Auth(provider),

  // Use other transport options
)

// 3. Create API client of rolestore feature
client := rolestore.New(curl)

Define the Permissions of the API Client

In order for accessing the PrivX REST API, you first need to define the permissions of the API client in PrivX.

1. Create an API-client entry in PrivX.

In the PrivX GUI, go to Administration→Deployment→Integrate with PrivX using API clients.

Click Add API Client.

1. Create and save the new API client

Provide a Name for the API client. To provide permissions, also add some Roles for the API client. Click Save to save your API client.

1. Get your API client Credentials

Back on the API clients page, expand the Credentials of your API client. These are required later for authentication setup.

SDK Configuration Providers

You can use configuration files to configure the PrivX SDK.
PrivX SDK UseConfigFile supports the following configuration-file format:

[api]

# restapi.BaseURL(...)
base_url="https://your-instance.privx.io"

# restapi.X509(...)
api_ca_crt="""Place the TLS Trust Anchor here"""

[auth]

# oauth.Access(...)
api_client_id="00000000-0000-0000-0000-000000000000"

# oauth.Secret(...)
api_client_secret="some-random-base64"

# oauth.Digest(...)
oauth_client_id="privx-external"
oauth_client_secret="another-random-base64"

Identity and Access Management

Usage of PrivX SDK requires API credential, which were discussed in the previous section, Define the permissions of the API client.
Authorizer implement OAuth2 Resource Owner Password Grant:

auth := oauth.WithClientID(/* ... */)

Alternatively, you can use API client on behalf of existing user using its credentials. Authorizer implements OAuth2 Authorization Code Grant:

auth := oauth.WithCredential(/* ... */)

If your application needs to implement a flexible auth strategy that supports both. Use following method, it dynamically chooses a right strategy depending of available credentials:

auth := oauth.With(/* ... */)

PrivX CLI

As an alternative of building a client from the ground up or just as an inspiration in how to interact with the Golang SDK, we also offer privx-cli, a command line application to use with PrivX.

Getting started with the PrivX CLI

1. Get the privx-cli application with go get github.com/SSHcom/privx-cli.

1. Create an API-client entry in PrivX so that the CLI is able to access the PrivX Rest API.

2. Create a configuration file for our settings.
   Create a config.toml file inside the root of the PrivX-CLI directory, with a supported file format described in SDK Configuration providers.

3. Log in to the client. Upon successful login, you will get an authentication token.

privx-cli login -c config.toml

1. Now you are able to use the CLI. For help and overviews:

privx-cli help

For more information about a specific command or subcommand:

privx-cli <command> --help

privx-cli <command> <subcommand> --help

An example workflow using the PrivX-CLI:

// List all local user with optional flags
privx-cli users --query <USERNAME> -c config.toml

// Create a new local user
privx-cli users create newUser.json -c config.toml

// Get local user information by user ID
privx-cli users show <USER-ID> -c config.toml

// Update a local user
privx-cli users update --uid <USER-ID> updateUser.json -c config.toml

// Delete a local user
privx-cli users delete --uid <USER-ID> -c config.toml