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:
/restapigeneric HTTPS transport layer
/oauthimplements 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)
In order for accessing the PrivX REST API, you first need to define the permissions of the API client in PrivX.
- Create an API-client entry in PrivX.
- Create and save the new API client
- Get your API client Credentials
You can use configuration files to configure the 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"
The required TLS Trust Anchor can be found at the bottom of the page Administration > Deployment > Integrate With PrivX Using API Clients.
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(/* ... */)
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.
- Get the privx-cli application with
go get github.com/SSHcom/privx-cli.
go getinstalls the application to $GOPATH/bin. This directory shall be accessible to your user and be part of the PATH environment variable. Please see the Golang instructions for more information.
Create an API-client entry in PrivX so that the CLI is able to access the PrivX Rest API.
Create a configuration file for our settings.
config.tomlfile inside the root of the PrivX-CLI directory, with a supported file format described in SDK Configuration providers.
Log in to the client. Upon successful login, you will get an authentication token.
privx-cli login -c config.toml
- Now you are able to use the CLI. For help and overviews:
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
The privx-cli is still in the early stage of development, meaning that it's not covering a lot of PrivX API endpoints to interact with. We are still working on it and new commands will be added to the CLI in the near future.
Updated about 1 year ago