mirror of https://github.com/hashicorp/boundary
docs: move SDK to developing section and add authenticate example (#485)
Jeff Malnick
6 years ago
committed by
GitHub
parent
cd2bf86a0d
commit
98b230773d
@ -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)
|
||||
```
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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.
|
||||
Loading…
Reference in new issue