From 98b230773dce081dfb90abe2823968a1ff598321 Mon Sep 17 00:00:00 2001 From: Jeff Malnick Date: Mon, 28 Sep 2020 17:57:46 -0700 Subject: [PATCH] docs: move SDK to developing section and add authenticate example (#485) --- .../docs/developing/sdk/authenticate.mdx | 168 ++++++++++++++++++ website/content/docs/developing/sdk/index.mdx | 19 ++ website/content/docs/sdk/index.mdx | 13 -- website/content/docs/sdk/login.mdx | 11 -- website/data/docs-navigation.js | 15 +- 5 files changed, 197 insertions(+), 29 deletions(-) create mode 100644 website/content/docs/developing/sdk/authenticate.mdx create mode 100644 website/content/docs/developing/sdk/index.mdx delete mode 100644 website/content/docs/sdk/index.mdx delete mode 100644 website/content/docs/sdk/login.mdx diff --git a/website/content/docs/developing/sdk/authenticate.mdx b/website/content/docs/developing/sdk/authenticate.mdx new file mode 100644 index 0000000000..7905c3baef --- /dev/null +++ b/website/content/docs/developing/sdk/authenticate.mdx @@ -0,0 +1,168 @@ +--- +layout: docs +page_title: SDK - Authenticate +sidebar_title: Authenticate +description: |- + Boundary SDK authenticate +--- + +# Authenticate + +Authenticating to Boundary starts with an [Auth Method](/docs/concepts/domain-model/auth-methods). An auth method provides +the basic identity delegation needed for Boundary to generate a token for a client. There are two primary methods for +authenticating to Boundary: + +1. Via an authentication method +1. Via the recovery KMS workflow + +We'll cover how to authenticate to Boundary via both of these workflows. + +## Authentication Method + +This is the most common way for a client to authenticate to Boundary. To demonstrate this, we'll +use the [authmethods](https://github.com/hashicorp/boundary/tree/main/api/authmethods) library to generate +a valid token for a client in go. + +For this example, we're going to use the password auth method. This example assumes there's already +a valid user and an associated account in Boundary for the client to authenticate as. To simplify this +example, we're assuming you're running a Boundary instance in dev mode, where the default auth method, login name, +and password are pre-configured. + +First, we need to create a net/http client from the Boundary API and set the address to reach Boundary: + +```golang +import github.com/boundary/api + +// assumes Boundary in dev mode +const boundaryAddr := "http://localhost:9200" + +client, err := api.NewClient(nil) +if err != nil { + return err +} + +client.SetAddr(boundaryAddr) +``` + +The [auth method client](https://github.com/hashicorp/boundary/blob/main/api/authmethods/authenticate.go) uses a basic `map[string]interface{}` to pass credential information. For this example, +we assume you're using the password auth method and so we're going to tailor a credentials object +to pass this data as: + +```golang +credentials := map[string]interface{}{ + "login_name": "admin", + "password": "password", +} +``` + +Now lets create an auth method client using the base client from above: + +```golang +import github.com/boundary/api/authmethods + +am := authmethods.NewClient(client) +``` + +The last thing you'll need is the ID of the auth method in Boundary. You can get this on the CLI +with: + +```bash +$ boundary auth-methods list + +Auth Method information: + ID: ampw_1234567890 + Description: Provides initial administrative authentication into Boundary + Name: Generated global scope initial auth method + Type: password + Version: 1 +``` + +Note the ID in the output above, we're going to use that in the next step. + +We can use the credentials object we created to execute `Authenticate()` on this client: + +```golang +at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials) +if err != nil { + return err +} +``` + +Lastly, let's update the original client with the token we got from the `Authenticate()` call: + +```golang +client.SetToken(at.Item.Token) +``` + +Putting this all together: + +```golang +import ( + github.com/boundary/api + github.com/boundary/api/authmethods +) + +// assumes Boundary in dev mode +const boundaryAddr := "http://localhost:9200" + +credentials := map[string]interface{}{ + "login_name": "admin", + "password": "password", +} + +client, err := api.NewClient(nil) +if err != nil { + return err +} + +client.SetAddr(boundaryAddr) + +am := authmethods.NewClient(client) +at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials) +if err != nil { + return err +} + +// pass this client to any other resource specific API resources +client.SetToken(at.Item.Token) +``` + +## Recovery KMS Workflow + +The recovery KMS workflow allows you to use a valid [KMS configuration](/docs/configuration/kms) to generate a token for a Boundary +client. For this example, we're going to assume you've read the above and know how to get a base Boundary API +client. + +Lets start with a valid KMS configuration for recovery that uses a hard coded AEAD key as the basis. To authenticate with Boundary using this config we're assuming you have a instance of Boundary that declares this as the recovery KMS in the Boundary controller config as well. + +```golang +const kmsConfig := ` +kms "aead" { + purpose = "recovery" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "recovery_kms" +} +` +``` + +Now lets use this config to configure our Boundary API client: + +```golang +client.SetRecoveryKmsWrapper(kmsConfig) +``` + +And finally, execute `Authenticate()`: + +```golang +am := authmethods.NewClient(client) +at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials) +if err != nil { + return err +} + +// pass this client to any other resource specific API resources +client.SetToken(at.Item.Token) +``` + + diff --git a/website/content/docs/developing/sdk/index.mdx b/website/content/docs/developing/sdk/index.mdx new file mode 100644 index 0000000000..e4f7cb0721 --- /dev/null +++ b/website/content/docs/developing/sdk/index.mdx @@ -0,0 +1,19 @@ +--- +layout: docs +page_title: SDK +sidebar_title: SDK +description: |- + Reference documentation for the Boundary SDK +--- + +# Overview + +The Boundary SDK is written in golang and the reference documentation here assume basic golang experience including a local +environment for developing golang code bases. + +## Getting Started + +Download the latest `main` branch revision of our [project on GitHub](https://github.com/hashicorp/boundary). + +As a developer, the most common package within this project that you'll interact is our [API package](https://github.com/hashicorp/boundary/tree/main/api). +This package contains all the common client libraries that you'll need to interact with the Boundary platform. diff --git a/website/content/docs/sdk/index.mdx b/website/content/docs/sdk/index.mdx deleted file mode 100644 index ff8b69c28f..0000000000 --- a/website/content/docs/sdk/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: docs -page_title: SDK Index -sidebar_title: SDK -description: |- - Reference documentation for the Boundary SDK ---- - -# Overview - -~> **Coming soon.** This page is not yet available. - -Detailed SDK documentation will be found on the godoc site. This documentation will cover basic examples for common SDK use cases. diff --git a/website/content/docs/sdk/login.mdx b/website/content/docs/sdk/login.mdx deleted file mode 100644 index 1e96eb50b9..0000000000 --- a/website/content/docs/sdk/login.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: docs -page_title: SDK -sidebar_title: Login/Logout -description: |- - Boundary SDK login and logout ---- - -# How to Login and Logout - -~> **Coming soon.** This page is not yet available. diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 13dd78ea4a..f8454f33e8 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -17,7 +17,16 @@ export default [ }, { category: 'developing', - content: ['building', 'ui'], + content: [ + 'building', + 'ui', + { + category: 'sdk', + content: [ + 'authenticate', + ], + }, + ], }, { category: 'concepts', @@ -77,10 +86,6 @@ export default [ category: 'command-line', content: ['login'], }, - { - category: 'sdk', - content: ['login'], - }, { category: 'releases', content: [