From 0705abdbc706c152c697794cb25127063b3ec9e6 Mon Sep 17 00:00:00 2001 From: Horia Culea Date: Tue, 26 Oct 2021 11:44:34 +0200 Subject: [PATCH 01/17] Add badges --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index e687b14..778d6fb 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # 1Password Connect Go SDK +[![GoDoc](https://godoc.org/github.com/1Password/connect-sdk-go?status.svg)][godoc] +[![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go)][goreportcard] +[![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg)][latest-version] + 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 From 920ab44391f54826368ccca03e4f54d50738fd95 Mon Sep 17 00:00:00 2001 From: Horia Culea Date: Tue, 26 Oct 2021 11:45:46 +0200 Subject: [PATCH 02/17] Fix badges --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 778d6fb..0582e55 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 1Password Connect Go SDK -[![GoDoc](https://godoc.org/github.com/1Password/connect-sdk-go?status.svg)][godoc] -[![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go)][goreportcard] -[![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg)][latest-version] +![GoDoc](https://godoc.org/github.com/1Password/connect-sdk-go?status.svg) +![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go) +![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg) 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. From 324c6b14f9f75c69344d972f2faf1003e4787d4f Mon Sep 17 00:00:00 2001 From: Horia Culea Date: Tue, 26 Oct 2021 12:08:48 +0200 Subject: [PATCH 03/17] Fix badges --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0582e55..37fe362 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![GoDoc](https://godoc.org/github.com/1Password/connect-sdk-go?status.svg) ![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go) -![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg) +[![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg)](latest-version) 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. From e2062dca9155437ec7584acda381941a485eeacb Mon Sep 17 00:00:00 2001 From: Horia Culea Date: Tue, 26 Oct 2021 12:15:46 +0200 Subject: [PATCH 04/17] Fix badges --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 37fe362..8668cd5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 1Password Connect Go SDK -![GoDoc](https://godoc.org/github.com/1Password/connect-sdk-go?status.svg) -![Go Report Card](https://goreportcard.com/badge/github.com/1Password/connect-sdk-go) -[![Version](https://img.shields.io/github/release/1Password/connect-sdk-go.svg)](latest-version) +[![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 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. From 1a7cc94a842781d10cb7b2a577210aa9530296e4 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 26 Oct 2021 12:57:38 +0200 Subject: [PATCH 05/17] First bit of documentation --- README.md | 45 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8668cd5..375cc44 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ [![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 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. +The 1Password Connect Go SDK provides access to the 1Password Connect API, to facilitate communication with the Connect server 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 - +To download and install the 1Password Connect Go SDK, as well as its dependencies: ```sh go get github.com/1Password/connect-sdk-go ``` @@ -16,19 +16,44 @@ go get github.com/1Password/connect-sdk-go ### Environment Variables -| 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) | +In order to use the Connect Go SDK, the following environment variables need to be set priorly: +* `OP_CONNECT_TOKEN`: the API token to be used to authenticate the client to your 1Password Connect instance. Used in order to successfully authenticate with the `connect.NewClientFromEnvironment` function. +* `OP_CONNECT_HOST`: the hostname of your 1Password Connect instance. Used in order to successfully authenticate with the `connect.NewClientFromEnvironment` function. +* `OP_VAULT`: a vault UUID. Used as default vault in the `LoadConfig` function, for all fields where the `.opvault` tag is not set. ### 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. -- `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 +* `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("http://localhost:8080", "eyA73ycbAY72") +} +``` +* `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): +```sh +export OP_CONNECT_TOKEN=eyA73ycbAY72 +export OP_CONNECT_HOST=http://localhost:8080 +``` +Now, the function 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 ### Unmarshalling into a Struct From 674b36b60f18731ea1dd614bfc2d9015bd59b4cd Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 26 Oct 2021 14:30:32 +0200 Subject: [PATCH 06/17] Add examples for functions --- README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 76 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 375cc44..5177c22 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,11 @@ go get github.com/1Password/connect-sdk-go ## Usage +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). + ### Environment Variables -In order to use the Connect Go SDK, the following environment variables need to be set priorly: +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 successfully authenticate with the `connect.NewClientFromEnvironment` function. * `OP_CONNECT_HOST`: the hostname of your 1Password Connect instance. Used in order to successfully authenticate with the `connect.NewClientFromEnvironment` function. * `OP_VAULT`: a vault UUID. Used as default vault in the `LoadConfig` function, for all fields where the `.opvault` tag is not set. @@ -53,8 +55,18 @@ func main () { } } ``` -* `connect.NewClientWithUserAgent` – Accepts a hostname, a token value, and a custom User-Agent string for identifying the client to the 1Password Connect API +* `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("http://localhost:8080", "eyJhbGciOiJFUzI1NiI", "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") +} +``` +[comment]: <> (The following subsection will be modified upon the merging of PR #31) ### Unmarshalling into a Struct Users can define tags on a struct and have the `connect.Client` unmarshall item data directly in them. Supported field tags are: @@ -103,13 +115,68 @@ The `onepassword.Item` model represents Items and `onepassword.Vault` represent The `connect.Client` also supports methods for: -- 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 +* listing Vaults +```go + vaults, err := client.GetVaults() + if err != nil { + log.Fatal(err) + } +``` +* listing items in a Vault +```go + items, err := client.GetItems("") + if err != nil { + log.Fatal(err) + } +``` +* searching by Item Title +```go + item, err := client.GetItemByTitle("", "") + if err != nil { + log.Fatal(err) + } +``` +* Retrieving Item by Vault and Item UUID +```go + item, err := client.GetItem("", "") + if err != nil { + log.Fatal(err) + } +``` +* Creating Items in a Vault +```go + item := &onepassword.Item{ + Fields: []*onepassword.ItemField{{ + Value: "mysecret", + Type: "STRING", + }}, + Tags: []string{"1password-connect"}, + Category: onepassword.Login, + Title: "Secret String", + } + + postedItem, err := client.CreateItem(item, "") + if err != nil { + log.Fatal(err) + } +``` +* Updating Items +```go + item, err := client.GetItem("", "") + if err != nil { + log.Fatal(err) + } + item.Title = "new title" + client.UpdateItem(item, "") +``` +* Deleting Items +```go + item, err := client.GetItem("", "") + if err != nil { + log.Fatal(err) + } + err = client.DeleteItem(item, "vault-uuid") +``` ### Errors All errors returned by Connect API are unmarshalled into a `onepassword.Error` struct: From 93fcc07bea290a5eb2553853ec49c14587708e98 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 26 Oct 2021 14:33:29 +0200 Subject: [PATCH 07/17] Fix typo --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5177c22..f072b28 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ Below, you can find a selection of the most used functionality of the Connect Go ### Environment Variables 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 successfully authenticate with the `connect.NewClientFromEnvironment` function. -* `OP_CONNECT_HOST`: the hostname of your 1Password Connect instance. Used in order to successfully authenticate with the `connect.NewClientFromEnvironment` function. +* `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 `LoadConfig` function, for all fields where the `.opvault` tag is not set. ### Creating an API Client @@ -109,7 +109,7 @@ func main() { ### Model Objects -The `onepassword.Item` model represents Items and `onepassword.Vault` represent Vaults in 1Password +The `onepassword.Item` model represents items and `onepassword.Vault` represents vaults, in 1Password. ### Item CRUD From 199032449287b8f628ed265ee4f14a0181d2e303 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 26 Oct 2021 15:44:24 +0200 Subject: [PATCH 08/17] Update README.md --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index f072b28..44acb6b 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,13 @@ The `connect.Client` also supports methods for: } ``` * searching by Item Title +```go + items, err := client.GetItemsByTitle("", "") + if err != nil { + log.Fatal(err) + } +``` +In case the item title is unique to the item, another function is available as well, returning only one item, instead of a slice: ```go item, err := client.GetItemByTitle("", "") if err != nil { From 0f8ca2ecb9f910e548ac6ec38d4357557f53cbd4 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 26 Oct 2021 16:39:42 +0200 Subject: [PATCH 09/17] Add file related functions --- README.md | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 44acb6b..6f5b310 100644 --- a/README.md +++ b/README.md @@ -115,21 +115,21 @@ The `onepassword.Item` model represents items and `onepassword.Vault` represents The `connect.Client` also supports methods for: -* listing Vaults +* Retrieving vaults ```go vaults, err := client.GetVaults() if err != nil { log.Fatal(err) } ``` -* listing items in a Vault +* Retrieving items in a vault ```go items, err := client.GetItems("") if err != nil { log.Fatal(err) } ``` -* searching by Item Title +* Retrieving items by their title ```go items, err := client.GetItemsByTitle("", "") if err != nil { @@ -143,14 +143,14 @@ In case the item title is unique to the item, another function is available as w log.Fatal(err) } ``` -* Retrieving Item by Vault and Item UUID +* Retrieving items by vault and item UUID ```go item, err := client.GetItem("", "") if err != nil { log.Fatal(err) } ``` -* Creating Items in a Vault +* Creating items in a vault ```go item := &onepassword.Item{ Fields: []*onepassword.ItemField{{ @@ -167,7 +167,7 @@ In case the item title is unique to the item, another function is available as w log.Fatal(err) } ``` -* Updating Items +* Updating items ```go item, err := client.GetItem("", "") if err != nil { @@ -176,7 +176,7 @@ In case the item title is unique to the item, another function is available as w item.Title = "new title" client.UpdateItem(item, "") ``` -* Deleting Items +* Deleting items ```go item, err := client.GetItem("", "") if err != nil { @@ -184,6 +184,24 @@ In case the item title is unique to the item, another function is available as w } err = client.DeleteItem(item, "vault-uuid") ``` +* Retrieving files +```go + file, err := client.GetFile("", "item-uuid", "vault-uuid") + if err != nil { + log.Fatal(err) + } +``` +* Retrieving the contents of files +```go + file, err := client.GetFile("", "item-uuid", "vault-uuid") + if err != nil { + log.Fatal(err) + } + content, err := client.GetFileContent(file) + if err != nil { + log.Fatal(err) + } +``` ### Errors All errors returned by Connect API are unmarshalled into a `onepassword.Error` struct: From cd487101ffa44d44afb75e0539242096f8b414e8 Mon Sep 17 00:00:00 2001 From: jillianwilson Date: Tue, 16 Nov 2021 14:55:20 -0400 Subject: [PATCH 10/17] Resructuring the readme --- README.md | 202 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 133 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 6f5b310..332f21a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,41 @@ [![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 API, to facilitate communication with the Connect server 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. +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. + +
+ Table of Contents + + - [1Password Connect Go SDK](#1password-connect-go-sdk) + * [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) +
+ +## Prerequisites + +- [1Password Connect](https://support.1password.com/secrets-automation/#step-2-deploy-a-1password-connect-server) deployed in your infrastructure ## Installation To download and install the 1Password Connect Go SDK, as well as its dependencies: @@ -16,16 +50,32 @@ go get github.com/1Password/connect-sdk-go 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). -### Environment Variables +Import the 1Password Connect SDK: -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 `LoadConfig` function, for all fields where the `.opvault` tag is not set. +```go +import ( + "github.com/secrethub/secrethub-go/pkg/secrethub" +) +``` + +### Quickstart +Reading a secret: +```go +import "github.com/1Password/connect-sdk-go/connect" + +func main () { + client := connect.NewClient("", "") + item, err := client.GetItem("", "") + 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 !password 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 are provided by that allow for creating the 1Password Connect client. * `connect.NewClient` – Accepts a hostname and a token value. ```go @@ -34,15 +84,13 @@ package main import "github.com/1Password/connect-sdk-go/connect" func main () { - client := connect.NewClient("http://localhost:8080", "eyA73ycbAY72") + client := connect.NewClient("", "") } ``` -* `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): -```sh -export OP_CONNECT_TOKEN=eyA73ycbAY72 -export OP_CONNECT_HOST=http://localhost:8080 -``` -Now, the function can be invoked as such: + +* `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 @@ -55,6 +103,7 @@ func main () { } } ``` + * `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 @@ -62,50 +111,11 @@ package main import "github.com/1Password/connect-sdk-go/connect" func main () { - client := connect.NewClientWithUserAgent("http://localhost:8080", "eyJhbGciOiJFUzI1NiI", "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") + client := connect.NewClientWithUserAgent("", "", "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") } ``` [comment]: <> (The following subsection will be modified upon the merging of PR #31) -### Unmarshalling into a Struct - -Users can define tags on a struct and have the `connect.Client` unmarshall item data directly in them. Supported field tags are: - -- `opvault` – The UUID of the vault the item should come from -- `opitem` – The title of the Item -- `opfield` – The item field whose value should be retrieved - -#### Example Struct - -This example struct will retrieve 3 fields from one Item and a whole Item from another vault - -```go -package main - -import ( - "github.com/1Password/connect-sdk-go/connect" - "github.com/1Password/connect-sdk-go/onepassword" -) - -type Config struct { - Database string `opitem:"Demo TF Database" opfield:".database"` - Username string `opitem:"Demo TF Database" opfield:".username"` - Password string `opitem:"Demo TF Database" opfield:".password"` - APIKey onepassword.Item `opvault:"7vs66j55o6md5btwcph272mva4" opitem:"API Key"` -} - -var client connect.Client - -func main() { - client, err := connect.NewClientFromEnvironment() - if err != nil { - panic(err) - } - - connect.Load(client, &c) -} - -``` ### Model Objects @@ -115,42 +125,43 @@ The `onepassword.Item` model represents items and `onepassword.Vault` represents The `connect.Client` also supports methods for: -* Retrieving vaults +#### Retrieving list of vaults that the Connect token has permission to read ```go vaults, err := client.GetVaults() if err != nil { log.Fatal(err) } ``` -* Retrieving items in a vault +#### Retrieving all items in a vault ```go items, err := client.GetItems("") if err != nil { log.Fatal(err) } ``` -* Retrieving items by their title +#### Retrieving item by title +To retrieve all items in a vault with a given title: ```go items, err := client.GetItemsByTitle("", "") if err != nil { log.Fatal(err) } ``` -In case the item title is unique to the item, another function is available as well, returning only one item, instead of a slice: +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("", "") if err != nil { log.Fatal(err) } ``` -* Retrieving items by vault and item UUID +#### Retrieving items by vault and item UUID ```go item, err := client.GetItem("", "") if err != nil { log.Fatal(err) } ``` -* Creating items in a vault +#### Creating items in a vault ```go item := &onepassword.Item{ Fields: []*onepassword.ItemField{{ @@ -167,7 +178,7 @@ In case the item title is unique to the item, another function is available as w log.Fatal(err) } ``` -* Updating items +#### Update and Item ```go item, err := client.GetItem("", "") if err != nil { @@ -176,7 +187,7 @@ In case the item title is unique to the item, another function is available as w item.Title = "new title" client.UpdateItem(item, "") ``` -* Deleting items +#### Delete an item ```go item, err := client.GetItem("", "") if err != nil { @@ -184,14 +195,14 @@ In case the item title is unique to the item, another function is available as w } err = client.DeleteItem(item, "vault-uuid") ``` -* Retrieving files +#### Retrieving a file from an item ```go file, err := client.GetFile("", "item-uuid", "vault-uuid") if err != nil { log.Fatal(err) } ``` -* Retrieving the contents of files +#### Retrieving the contents of a file from an item ```go file, err := client.GetFile("", "item-uuid", "vault-uuid") if err != nil { @@ -203,6 +214,54 @@ In case the item title is unique to the item, another function is available as w } ``` +### Unmarshalling into a Struct + +Users can define tags on a struct and have the `connect.Client` unmarshall item data directly in them. Supported field tags are: + +- `opvault` – The UUID of the vault the item should come from +- `opitem` – The title of the Item +- `opfield` – The item field whose value should be retrieved + +#### Example Struct + +This example struct will retrieve 3 fields from one Item and a whole Item from another vault + +```go +package main + +import ( + "github.com/1Password/connect-sdk-go/connect" + "github.com/1Password/connect-sdk-go/onepassword" +) + +type Config struct { + Database string `opitem:"Demo TF Database" opfield:".database"` + Username string `opitem:"Demo TF Database" opfield:".username"` + Password string `opitem:"Demo TF Database" opfield:".password"` + APIKey onepassword.Item `opvault:"7vs66j55o6md5btwcph272mva4" opitem:"API Key"` +} + +var client connect.Client + +func main() { + client, err := connect.NewClientFromEnvironment() + if err != nil { + panic(err) + } + + connect.Load(client, &c) +} + +``` + +### Environment Variables + +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 `LoadConfig` function, for all fields where the `.opvault` tag is not set. + + ### Errors All errors returned by Connect API are unmarshalled into a `onepassword.Error` struct: ```go @@ -225,23 +284,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 From 0c4de3a3c4f485845537051b765df5cfd39a1a07 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:07:59 +0000 Subject: [PATCH 11/17] Add correct imports --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 332f21a..5f83029 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,8 @@ Import the 1Password Connect SDK: ```go import ( - "github.com/secrethub/secrethub-go/pkg/secrethub" + "github.com/1Password/connect-sdk-go/connect" + "github.com/1Password/connect-sdk-go/onepassword" ) ``` From ed75b0dd0e92482ba23b769a1609efca62a9f881 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:13:45 +0000 Subject: [PATCH 12/17] Add quickstart for writing a secret --- README.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5f83029..6ce04e8 100644 --- a/README.md +++ b/README.md @@ -40,18 +40,13 @@ The 1Password Connect Go SDK provides access to the [1Password Connect](https:// - [1Password Connect](https://support.1password.com/secrets-automation/#step-2-deploy-a-1password-connect-server) deployed in your infrastructure -## Installation +## 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 ``` -## Usage - -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). - -Import the 1Password Connect SDK: - +To import the 1Password Connect SDK in your Go project: ```go import ( "github.com/1Password/connect-sdk-go/connect" @@ -59,6 +54,10 @@ import ( ) ``` +## Usage + +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: @@ -73,6 +72,29 @@ func main () { } } ``` + +Writing a secret: +```go +import "github.com/1Password/connect-sdk-go/connect" + +func main () { + client := connect.NewClient("", "") + item := &onepassword.Item{ + Fields: []*onepassword.ItemField{{ + Value: "mysecret", + Type: "STRING", + }}, + Category: onepassword.Login, + Title: "Secret String", + } + + postedItem, err := client.CreateItem(item, "") + if err != nil { + log.Fatal(err) + } +} +``` + ### Creating an API Client A !password Connect client (`connect.Client`) is required to make requests to the Connect server via the 1Password Go SDK. From 0300fa5b28e965925c06e192a862a4310a7b71da Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:15:09 +0000 Subject: [PATCH 13/17] Add proper imports in readme --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6ce04e8..e4d07a9 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,10 @@ func main () { Writing a secret: ```go -import "github.com/1Password/connect-sdk-go/connect" +import ( + "github.com/1Password/connect-sdk-go/connect" + "github.com/1Password/connect-sdk-go/onepassword" +) func main () { client := connect.NewClient("", "") From c58373b29fd038b2e1d2221291634f11f7231b20 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:19:26 +0000 Subject: [PATCH 14/17] Update README.md --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e4d07a9..bffe71a 100644 --- a/README.md +++ b/README.md @@ -100,8 +100,8 @@ func main () { ### Creating an API Client -A !password 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 are provided by that allow for creating the 1Password Connect 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 @@ -116,7 +116,7 @@ func main () { * `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: +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 @@ -141,8 +141,6 @@ func main () { } ``` -[comment]: <> (The following subsection will be modified upon the merging of PR #31) - ### Model Objects The `onepassword.Item` model represents items and `onepassword.Vault` represents vaults, in 1Password. From 1714d037cfd5a63a9649ff7aed976e1424388113 Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:22:50 +0000 Subject: [PATCH 15/17] Update README.md --- README.md | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index bffe71a..c5d1ca7 100644 --- a/README.md +++ b/README.md @@ -244,11 +244,16 @@ Users can define tags on a struct and have the `connect.Client` unmarshall item - `opvault` – The UUID of the vault the item should come from - `opitem` – The title of the Item +- `opsection` - The section where the required field is located - `opfield` – The item field whose value should be retrieved +All retrieved fields require at least the `opfield` and `opitem` tags, while all retrieved items require the `opitem` tag. Additionally, a custom vault can be specified by setting the `opvault` tag. +In case this is not set, the SDK will use the value of the `OP_VAULT` environment variable as the default UUID. +If a field is within a section, the `opsection` tag is required as well. Please note that one cannot retrieve a section in itself. + #### Example Struct -This example struct will retrieve 3 fields from one Item and a whole Item from another vault +This example struct will retrieve 3 fields from one item and a whole item from another vault: ```go package main @@ -259,23 +264,43 @@ import ( ) type Config struct { - Database string `opitem:"Demo TF Database" opfield:".database"` - Username string `opitem:"Demo TF Database" opfield:".username"` - Password string `opitem:"Demo TF Database" opfield:".password"` + 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"` APIKey onepassword.Item `opvault:"7vs66j55o6md5btwcph272mva4" opitem:"API Key"` } -var client connect.Client - func main() { client, err := connect.NewClientFromEnvironment() if err != nil { panic(err) } - - connect.Load(client, &c) + c := Config{} + err = client.LoadStruct(&c) } +``` +Additionally, fields of the same item can be added to a struct at once, without needing to specify the `opitem` or `opvault` tags: +```go +package main + +import "github.com/1Password/connect-sdk-go/connect" + + +type Config struct { + Username string `opfield:"username"` + Password string `opfield:"password"` +} + +func main () { + client, err := connect.NewClientFromEnvironment() + if err != nil { + panic(err) + } + c := Config{} + err = client.LoadStructFromItemByTitle(&c, "Demo TF Database", "7vs66j55o6md5btwcph272mva4") // retrieve using item title + err = client.LoadStructFromItem(&c, "4bc73kao58g2usb582ndn3w4", "7vs66j55o6md5btwcph272mva4") // retrieve using item uuid +} ``` ### Environment Variables @@ -283,7 +308,7 @@ func main() { 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 `LoadConfig` function, for all fields where the `.opvault` tag is not set. +* `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 From fb0e904e83a9f6af42cfe0e314bd5dada7a6b17a Mon Sep 17 00:00:00 2001 From: Horia Culea <45151601+hculea@users.noreply.github.com> Date: Tue, 30 Nov 2021 11:40:43 +0000 Subject: [PATCH 16/17] Update README.md --- README.md | 67 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 51 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index c5d1ca7..95441f6 100644 --- a/README.md +++ b/README.md @@ -147,45 +147,52 @@ The `onepassword.Item` model represents items and `onepassword.Vault` represents ### Item CRUD -The `connect.Client` also supports methods for: +The `connect.Client` supports methods for: -#### Retrieving list of vaults that the Connect token has permission to read +#### Retrieving a list of vaults that the Connect token has permission to read ```go vaults, err := client.GetVaults() if err != nil { log.Fatal(err) } ``` +#### 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("") + items, err := client.GetItems("vault-uuid") if err != nil { log.Fatal(err) } ``` -#### Retrieving item by title +#### Retrieving an item by title To retrieve all items in a vault with a given title: ```go - items, err := client.GetItemsByTitle("", "") + 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, err := client.GetItemByTitle("item-title", "vault-uuid") if err != nil { log.Fatal(err) } ``` -#### Retrieving items by vault and item UUID +#### Retrieving items by vault UUID and item UUID ```go - item, err := client.GetItem("", "") + item, err := client.GetItem("item-uuid", "vault-uuid") if err != nil { log.Fatal(err) } ``` -#### Creating items in a vault +#### Creating an item in a vault ```go item := &onepassword.Item{ Fields: []*onepassword.ItemField{{ @@ -197,27 +204,37 @@ In case the item title is unique for a vault, another function is available as w Title: "Secret String", } - postedItem, err := client.CreateItem(item, "") + postedItem, err := client.CreateItem(item, "vault-uuid") if err != nil { log.Fatal(err) } ``` -#### Update and Item +#### Updating an item ```go - item, err := client.GetItem("", "") + item, err := client.GetItem("item-uuid", "vault-uuid") if err != nil { log.Fatal(err) } item.Title = "new title" - client.UpdateItem(item, "") + client.UpdateItem(item, "vault-uuid") ``` -#### Delete an item +#### Deleting an item ```go - item, err := client.GetItem("", "") + 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 @@ -228,7 +245,7 @@ In case the item title is unique for a vault, another function is available as w ``` #### Retrieving the contents of a file from an item ```go - file, err := client.GetFile("", "item-uuid", "vault-uuid") + file, err := client.GetFile("file-uuid", "item-uuid", "vault-uuid") if err != nil { log.Fatal(err) } @@ -237,6 +254,24 @@ In case the item title is unique for a vault, another function is available as w 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 From c1d403818c9c1b08ec45d5325e67975c0e9b86bb Mon Sep 17 00:00:00 2001 From: Eddy Filip Date: Wed, 11 May 2022 11:57:54 +0200 Subject: [PATCH 17/17] Apply formatting to the README These help for visual formatting and content editing. --- README.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5c44186..4cc7f6d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ The 1Password Connect Go SDK provides access to the [1Password Connect](https://
Table of Contents - - [1Password Connect Go SDK](#1password-connect-go-sdk) * [Prerequisites](#prerequisites) * [Installation](#installation) * [Usage](#usage) @@ -49,7 +48,7 @@ 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/connect" "github.com/1Password/connect-sdk-go/onepassword" ) ``` @@ -76,19 +75,19 @@ func main () { Writing a secret: ```go import ( - "github.com/1Password/connect-sdk-go/connect" + "github.com/1Password/connect-sdk-go/connect" "github.com/1Password/connect-sdk-go/onepassword" ) func main () { client := connect.NewClient("", "") item := &onepassword.Item{ + Title: "Secret String", + Category: onepassword.Login, Fields: []*onepassword.ItemField{{ Value: "mysecret", - Type: "STRING", + Type: "STRING", }}, - Category: onepassword.Login, - Title: "Secret String", } postedItem, err := client.CreateItem(item, "") @@ -156,6 +155,7 @@ The `connect.Client` supports methods for: log.Fatal(err) } ``` + #### Retrieving a vault: ```go vault, err := client.GetVault("vault-uuid") @@ -163,6 +163,7 @@ The `connect.Client` supports methods for: log.Fatal(err) } ``` + #### Retrieving all items in a vault ```go items, err := client.GetItems("vault-uuid") @@ -170,6 +171,7 @@ The `connect.Client` supports methods for: log.Fatal(err) } ``` + #### Retrieving an item by title To retrieve all items in a vault with a given title: ```go @@ -178,6 +180,7 @@ To retrieve all items in a vault with a given title: 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") @@ -185,6 +188,7 @@ In case the item title is unique for a vault, another function is available as w log.Fatal(err) } ``` + #### Retrieving items by vault UUID and item UUID ```go item, err := client.GetItem("item-uuid", "vault-uuid") @@ -192,16 +196,17 @@ In case the item title is unique for a vault, another function is available as w 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", }}, - Tags: []string{"1password-connect"}, - Category: onepassword.Login, - Title: "Secret String", } postedItem, err := client.CreateItem(item, "vault-uuid") @@ -209,26 +214,31 @@ In case the item title is unique for a vault, another function is available as w 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") @@ -236,6 +246,7 @@ In case the item title is unique for a vault, another function is available as w log.Fatal(err) } ``` + #### Retrieving a file from an item ```go file, err := client.GetFile("", "item-uuid", "vault-uuid") @@ -243,17 +254,20 @@ In case the item title is unique for a vault, another function is available as w 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") @@ -261,12 +275,14 @@ In case the item title is unique for a vault, another function is available as w 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) @@ -301,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"` }