Skip to content

Commit

Permalink
Merge pull request #32 from 1Password/feature/improve-docs
Browse files Browse the repository at this point in the history 
Improve documentation
  • Loading branch information
@edif2008
edif2008 authored May 12, 2022
2 parents 7011bce + c1d4038 commit 8cf69f9
Showing 1 changed file with 293 additions and 35 deletions.
328 changes: 293 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,293 @@
# 1Password Connect Go SDK

The 1Password Connect Go SDK provides access to the 1Password Connect API hosted on your infrastructure. The library is intended to be used by your applications, pipelines, and other automations to simplify accessing items stored in your 1Password vaults.

## Installation

[![Go Reference](https://pkg.go.dev/badge/github.com/1Password/connect-sdk-go.svg)](https://pkg.go.dev/github.com/1Password/connect-sdk-go)
[![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go)](https://goreportcard.com/report/github.com/1Password/connect-sdk-go)
[![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg)](https://github.com/1Password/connect-sdk-go/releases/)

The 1Password Connect Go SDK provides access to the [1Password Connect](https://support.1password.com/secrets-automation/) API, to facilitate communication with the Connect server hosted on your infrastructure and 1Password. The library is intended to be used by your applications, pipelines, and other automations to simplify accessing items stored in your 1Password vaults.

<details>
<summary>Table of Contents</summary>

* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Usage](#usage)
+ [Quickstart](#quickstart)
+ [Creating an API Client](#creating-an-api-client)
+ [Model Objects](#model-objects)
+ [Item CRUD](#item-crud)
- [Retrieving list of vaults that the Connect token has permission to read](#retrieving-list-of-vaults-that-the-connect-token-has-permission-to-read)
- [Retrieving all items in a vault](#retrieving-all-items-in-a-vault)
- [Retrieving item by title](#retrieving-item-by-title)
- [Retrieving items by vault and item UUID](#retrieving-items-by-vault-and-item-uuid)
- [Creating items in a vault](#creating-items-in-a-vault)
- [Update and Item](#update-and-item)
- [Delete an item](#delete-an-item)
- [Retrieving a file from an item](#retrieving-a-file-from-an-item)
- [Retrieving the contents of a file from an item](#retrieving-the-contents-of-a-file-from-an-item)
+ [Unmarshalling into a Struct](#unmarshalling-into-a-struct)
- [Example Struct](#example-struct)
+ [Environment Variables](#environment-variables)
+ [Errors](#errors)
* [Development](#development)
+ [Building](#building)
+ [Running Tests](#running-tests)
* [Security](#security)
</details>

## Prerequisites

- [1Password Connect](https://support.1password.com/secrets-automation/#step-2-deploy-a-1password-connect-server) deployed in your infrastructure

## Installation and Importing
To download and install the 1Password Connect Go SDK, as well as its dependencies:
```sh
go get github.com/1Password/connect-sdk-go
```

To import the 1Password Connect SDK in your Go project:
```go
import (
"github.com/1Password/connect-sdk-go/connect"
"github.com/1Password/connect-sdk-go/onepassword"
)
```

## Usage

### Environment Variables
Below, you can find a selection of the most used functionality of the Connect Go SDK. For more detailed information about the content of the SDK, please refer to the [GoDocs](https://pkg.go.dev/github.com/1Password/connect-sdk-go).

### Quickstart

Reading a secret:
```go
import "github.com/1Password/connect-sdk-go/connect"

func main () {
client := connect.NewClient("<your_connect_host>", "<your_connect_token>")
item, err := client.GetItem("<item-uuid>", "<vault-uuid>")
if err != nil {
log.Fatal(err)
}
}
```

Writing a secret:
```go
import (
"github.com/1Password/connect-sdk-go/connect"
"github.com/1Password/connect-sdk-go/onepassword"
)

func main () {
client := connect.NewClient("<your_connect_host>", "<your_connect_token>")
item := &onepassword.Item{
Title: "Secret String",
Category: onepassword.Login,
Fields: []*onepassword.ItemField{{
Value: "mysecret",
Type: "STRING",
}},
}

| Variable | Description | Feature |
|:-------------------|:------------|------:|
| `OP_CONNECT_TOKEN` | The API token to be used to authenticate the client to a 1Password Connect API. | [API Client](#/Creating-an-api-client) |
| `OP_CONNECT_HOST` | The hostname of the 1Password Connect API | [API Client](#/Creating-an-api-client) |
| `OP_VAULT` | If the `opvault` tag is not set the client will default to this vault UUID | [Unmarshalling](#/Unmarshalling-into-a-struct) |
postedItem, err := client.CreateItem(item, "<vault-uuid>")
if err != nil {
log.Fatal(err)
}
}
```

### Creating an API Client

`connect.Client` instances require two pieces of configuration. A token and a hostname. There are three constructor methods provided by this library for creating your client.
A 1Password Connect client (`connect.Client`) is required to make requests to the Connect server via the 1Password Go SDK.
The client is configured with a token and a hostname. Three constructor methods that allow for creating the 1Password Connect client are provided.

* `connect.NewClient` – Accepts a hostname and a token value.
```go
package main

import "github.com/1Password/connect-sdk-go/connect"

func main () {
client := connect.NewClient("<your_connect_host>", "<your_connect_token>")
}
```

* `connect.NewClientFromEnvironment` – Fetches the hostname and token value from the environment, and expects these to be passed as environment variables (`OP_CONNECT_HOST` and `OP_CONNECT_TOKEN`, respectively).

Assuming that `OP_CONNECT_TOKEN` and `OP_CONNECT_HOST` have been set as environment variables, the `connect.NewClientFromEnvironment` can be invoked as such:
```go
package main

import "github.com/1Password/connect-sdk-go/connect"

func main () {
client, err:= connect.NewClientFromEnvironment()
if err != nil {
panic(err)
}
}
```

* `connect.NewClientWithUserAgent` – Accepts a hostname, a token value, and a custom User-Agent string for identifying the client to the 1Password Connect API:
```go
package main

import "github.com/1Password/connect-sdk-go/connect"

func main () {
client := connect.NewClientWithUserAgent("<your_connect_host>", "<your_connect_token>", "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_2 like Mac OS X) AppleWebKit/603.2.4 (KHTML, like Gecko) FxiOS/8.1.1b4948 Mobile/14F89 Safari/603.2.4")
}
```

### Model Objects

The `onepassword.Item` model represents items and `onepassword.Vault` represents vaults, in 1Password.

### Item CRUD

The `connect.Client` supports methods for:

#### Retrieving a list of vaults that the Connect token has permission to read
```go
vaults, err := client.GetVaults()
if err != nil {
log.Fatal(err)
}
```

- `connect.NewClient` – Accepts a hostname and a token value.
- `connect.NewClientFromEnvironment` – Fetches the hostname and token value from the environment
- `connect.NewClientWithUserAgent` – Accepts a hostname, a token value, and a custom User-Agent string for identifying the client to the 1Password Connect API
#### Retrieving a vault:
```go
vault, err := client.GetVault("vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Retrieving all items in a vault
```go
items, err := client.GetItems("vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Retrieving an item by title
To retrieve all items in a vault with a given title:
```go
items, err := client.GetItemsByTitle("items-title", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

In case the item title is unique for a vault, another function is available as well, returning only one item, instead of a slice:
```go
item, err := client.GetItemByTitle("item-title", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Retrieving items by vault UUID and item UUID
```go
item, err := client.GetItem("item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Creating an item in a vault
```go
item := &onepassword.Item{
Title: "Secret String",
Category: onepassword.Login,
Tags: []string{"1password-connect"},
Fields: []*onepassword.ItemField{{
Value: "mysecret",
Type: "STRING",
}},
}

postedItem, err := client.CreateItem(item, "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Updating an item
```go
item, err := client.GetItem("item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}

item.Title = "new title"
client.UpdateItem(item, "vault-uuid")
```

#### Deleting an item
```go
item, err := client.GetItem("item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}

err = client.DeleteItem(item, "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Deleting an item by UUID
```go
err := client.DeleteItemByID("item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Retrieving a file from an item
```go
file, err := client.GetFile("<file-uuid>", "item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Retrieving the contents of a file from an item
```go
file, err := client.GetFile("file-uuid", "item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}

content, err := client.GetFileContent(file)
if err != nil {
log.Fatal(err)
}
```

#### Retrieving all files under an item
```go
files, err := client.GetFiles("item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}
```

#### Downloading a file
```go
file, err := client.GetFile("file-uuid", "item-uuid", "vault-uuid")
if err != nil {
log.Fatal(err)
}

path, err := client.DownloadFile(file, "local/path/to/file", true)
if err != nil {
log.Fatal(err)
}
```

### Unmarshalling into a Struct

Expand Down Expand Up @@ -54,7 +317,7 @@ import (
type Config struct {
Username string `opitem:"Demo TF Database" opfield:"username"`
Password string `opitem:"Demo TF Database" opfield:"password"`
Host string `opitem:"Demo TF Database" opsection:"details" opfield:"hostname"`
Host string `opitem:"Demo TF Database" opsection:"details" opfield:"hostname"`
APIKey onepassword.Item `opvault:"7vs66j55o6md5btwcph272mva4" opitem:"API Key"`
}

Expand All @@ -74,7 +337,6 @@ package main

import "github.com/1Password/connect-sdk-go/connect"


type Config struct {
Username string `opfield:"username"`
Password string `opfield:"password"`
Expand All @@ -90,22 +352,13 @@ func main () {
err = client.LoadStructFromItem(&c, "4bc73kao58g2usb582ndn3w4", "7vs66j55o6md5btwcph272mva4") // retrieve using item uuid
}
```
### Model Objects

The `onepassword.Item` model represents Items and `onepassword.Vault` represent Vaults in 1Password

### Item CRUD

The `connect.Client` also supports methods for:
### Environment Variables

- listing Vaults
- listing items in a Vault
- searching by Item Title
- Retrieving Item by Vault and Item UUID
- Creating Items in a Vault
- Updating Items
- Deleting Items
- Retrieving and Downloading Files
The Connect Go SDK makes use of the following environment variables:
* `OP_CONNECT_TOKEN`: the API token to be used to authenticate the client to your 1Password Connect instance. Used in order to authenticate via the `connect.NewClientFromEnvironment` function.
* `OP_CONNECT_HOST`: the hostname of your 1Password Connect instance. Used in order to authenticate via the `connect.NewClientFromEnvironment` function.
* `OP_VAULT`: a vault UUID. Used as default vault in the `LoadStruct`, `LoadStructFromItemByTitle` and `LoadStructFromItem` functions, for all fields where the `opvault` tag is not set.

### Errors
All errors returned by Connect API are unmarshalled into a `onepassword.Error` struct:
Expand All @@ -129,23 +382,28 @@ if err != nil{
}
}
```

## Development

### Building

To build all packages run
To build all packages:

```sh
go build ./...
make build
```

### Running Tests

To run all tests and see test coverage run
Run all tests:

```sh
make test
```

Run all tests with code coverage:

```sh
go test -v ./... -cover
make test/coverage
```

## Security
Expand Down

0 comments on commit 8cf69f9

Please sign in to comment.