Skip to content

Commit

Permalink
modify docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@firingLi
firingLi committed Apr 15, 2022
1 parent 803bd43 commit 6d4e99b
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 77 deletions.
106 changes: 72 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,102 @@
# Vault Plugin: TencentCloud Auth Backend

This is a standalone backend plugin for use with [Hashicorp Vault](https://www.github.com/hashicorp/vault).
This plugin allows authentication to Vault using Cloud Access Management (CAM).
This is a standalone backend plugin for use with [Hashicorp Vault](https://www.github.com/hashicorp/vault). This plugin
allows authentication to Vault using Cloud Access Management (CAM).

**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, _please responsibly disclose_ by contacting us at [security@hashicorp.com](mailto:security@hashicorp.com).
**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security
issue in Vault, _please responsibly disclose_ by contacting us
at [security@hashicorp.com](mailto:security@hashicorp.com).

## Quick Links

- [Vault Website](https://www.vaultproject.io)
- [TencentCloud Auth Docs](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20Auth%20Method.md)
- [Main Project Github](https://www.github.com/hashicorp/vault)

## Getting Started

This is a [Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html)
and is meant to work with Vault. This guide assumes you have already installed Vault
and have a basic understanding of how Vault works.
and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of
how Vault works.

Otherwise, first read this guide on how to [get started with Vault](https://www.vaultproject.io/intro/getting-started/install.html).
Otherwise, first read this guide on how
to [get started with Vault](https://www.vaultproject.io/intro/getting-started/install.html).

To learn specifically about how plugins work, see documentation on [Vault plugins](https://www.vaultproject.io/docs/internals/plugins.html).
To learn specifically about how plugins work, see documentation
on [Vault plugins](https://www.vaultproject.io/docs/internals/plugins.html).

## Security Model

This authentication model places Vault in the middle of a call between a client and
TencentCloud's "GetCallerIdentity" method. Based on TencentCloud's response, it grants
an access token based on pre-configured roles.
This authentication model places Vault in the middle of a call between a client and TencentCloud's "GetCallerIdentity"
method. Based on TencentCloud's response, it grants an access token based on pre-configured roles.

## Usage

Please see [documentation for the plugin](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20Auth%20Method.md)
Please
see [documentation for the plugin](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20Auth%20Method.md)

### From Sources

If you prefer to build the plugin from sources, clone the GitHub repository locally.

### Build the plugin

Build the auth method into a plugin using Go.

```shell
$ go build -o vault/plugins/vault-plugin-auth-tencentcloud ./cmd/vault-plugin-auth-tencentcloud/main.go
```

### Configuration

Copy the plugin binary into a location of your choice; this directory must be specified as
the [`plugin_directory`](https://www.vaultproject.io/docs/configuration#plugin_directory) in the Vault configuration
file:

This plugin is currently built into Vault and by default is accessed at `auth/tencentcloud`.
To enable this in a running Vault server:
```hcl
plugin_directory = "vault/plugins"
```

Start a Vault server with this configuration file:

```sh
$ vault auth enable tencentcloud
Success! Enabled tencentcloud auth method at: tencentcloud/
$ vault server -config=vault/server.hcl
```

To see all the supported paths, see the [TencentCloud auth backend docs](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20Auth%20Method.md).
Once the server is started, register the plugin in the Vault
server's [plugin catalog](https://www.vaultproject.io/docs/internals/plugins#plugin-catalog):

```sh
$ SHA256=$(shasum -a 256 vault/plugins/vault-plugin-auth-tencentcloud | cut -d ' ' -f1)

$ vault plugin register -sha256=$SHA256 auth vault-plugin-auth-tencentcloud

$ vault plugin info auth vault-plugin-auth-tencentcloud

```

You can now enable the tencentCloud auth plugin:

```sh
$ vault auth enable -path=tencentcloud vault-plugin-auth-tencentcloud
Success! Enabled vault-plugin-auth-tencentcloud auth method at: tencentcloud/
```

## Developing

If you wish to work on this plugin, you'll first need [Go](https://www.golang.org) installed on
your machine (version 1.13+ is required).
If you wish to work on this plugin, you'll first need [Go](https://www.golang.org) installed on your machine.

For local dev first make sure Go is properly installed, including setting up a [GOPATH](https://golang.org/doc/code.html#GOPATH).
Next, clone this repository into `$GOPATH/src/github.com/hashicorp/vault-plugin-auth-tencentcloud`.
You can then download any required build tools by bootstrapping your environment:
For local dev first make sure Go is properly installed, including setting up
a [GOPATH](https://golang.org/doc/code.html#GOPATH). Next, clone this repository
into `$GOPATH/src/github.com/hashicorp/vault-plugin-auth-tencentcloud`. You can then download any required build tools
by bootstrapping your environment:

```sh
$ make bootstrap
```

To compile a development version of this plugin, run `make` or `make dev`. This will put the
plugin binary in the `bin` and `$GOPATH/bin` folders. `dev` mode will only generate the binary
for your platform and is faster:
To compile a development version of this plugin, run `make` or `make dev`. This will put the plugin binary in the `bin`
and `$GOPATH/bin` folders. `dev` mode will only generate the binary for your platform and is faster:

```sh
$ make
Expand All @@ -68,8 +109,8 @@ For local development, use Vault's "dev" mode for fast setup:
$ vault server -dev -dev-plugin-dir="path/to/plugin/directory"
```

The plugin will automatically be added to the catalog with the name "vault-plugin-auth-tencentcloud".
Run the following command to enable this new auth method as a plugin:
The plugin will automatically be added to the catalog with the name "vault-plugin-auth-tencentcloud". Run the following
command to enable this new auth method as a plugin:

```sh
$ vault auth enable -path=tencentcloud vault-plugin-auth-tencentcloud
Expand All @@ -81,15 +122,12 @@ Success! Enabled vault-plugin-auth-tencentcloud auth method at: tencentcloud/
This plugin has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing)
covering most of the features of this auth backend.

If you are developing this plugin and want to verify it is still
functioning (and you haven't broken anything else), we recommend
running the acceptance tests.
If you are developing this plugin and want to verify it is still functioning (and you haven't broken anything else), we
recommend running the acceptance tests.

**Warning:** The acceptance tests create/destroy/modify *real resources*,
which may incur real costs in some cases. In the presence of a bug,
it is technically possible that broken backends could leave dangling
data behind. Therefore, please run the acceptance tests at your own risk.
At the very least, we recommend running them in their own private
**Warning:** The acceptance tests create/destroy/modify *real resources*, which may incur real costs in some cases. In
the presence of a bug, it is technically possible that broken backends could leave dangling data behind. Therefore,
please run the acceptance tests at your own risk. At the very least, we recommend running them in their own private
account for whatever backend you're testing.

To run the acceptance tests, you will need a TencentCloud account.
Expand Down
113 changes: 70 additions & 43 deletions docs/Tencent Cloud Auth Method.md
View file
Original file line number Diff line number Diff line change
@@ -1,95 +1,122 @@

# Tencent Cloud Auth Method

The `tencentcloud` auth method provides an automated mechanism to retrieve
a Vault token for Tencent Cloud entities. Unlike most Vault auth methods, this
method does not require manual first-deploying, or provisioning
security-sensitive credentials (tokens, username/password, client certificates,
etc), by operators.
The `tencentcloud` auth method provides an automated mechanism to retrieve a Vault token for Tencent Cloud entities.
Unlike most Vault auth methods, this method does not require manual first-deploying, or provisioning security-sensitive
credentials (tokens, username/password, client certificates, etc), by operators.

## Authentication Workflow

The TencentCloud STS API includes a method,
[`sts:GetCallerIdentity`],
which allows you to validate the identity of a client. The client signs
a `GetCallerIdentity` query using the [Tencent Cloud Signature Algorithm v3](https://intl.cloud.tencent.com/document/api/598/32225). It then
submits 2 pieces of information to the Vault server to recreate a valid signed
request: the request URL, and the request headers. The Vault server then
reconstructs the query and forwards it on to the Tencent Cloud STS service and validates
[`sts:GetCallerIdentity`], which allows you to validate the identity of a client. The client signs a `GetCallerIdentity`
query using the [Tencent Cloud Signature Algorithm v3](https://intl.cloud.tencent.com/document/api/598/32225). It then
submits 2 pieces of information to the Vault server to recreate a valid signed request: the request URL, and the request
headers. The Vault server then reconstructs the query and forwards it on to the Tencent Cloud STS service and validates
the result back.

Each signed Tencent Cloud request includes the current timestamp and a nonce to mitigate
the risk of replay attacks.

Each signed Tencent Cloud request includes the current timestamp and a nonce to mitigate the risk of replay attacks.

## Authorization Workflow

The basic mechanism of operation is per-role.

Roles are associated with a role ARN that has been pre-created in Tencent Cloud.
Tencent Cloud's console displays each role's ARN. A role in Vault has a 1:1 relationship
with a role in Tencent Cloud, and must bear the same name.
Roles are associated with a role ARN that has been pre-created in Tencent Cloud. Tencent Cloud's console displays each
role's ARN. A role in Vault has a 1:1 relationship with a role in Tencent Cloud, and must bear the same name.

When a client assumes that role and sends its `GetCallerIdentity` request to Vault,
Vault matches the arn of its assumed role with that of a pre-created role in Vault.
It then checks what policies have been associated with the role, and grants a
token accordingly.
When a client assumes that role and sends its `GetCallerIdentity` request to Vault, Vault matches the arn of its assumed
role with that of a pre-created role in Vault. It then checks what policies have been associated with the role, and
grants a token accordingly.

## Authentication

### Via the CLI

#### Enable Tencent Cloud authentication in Vault.
### From Sources

If you prefer to build the plugin from sources, clone the GitHub repository locally.

### Build the plugin

Build the auth method into a plugin using Go.

```shell
$ go build -o vault/plugins/vault-plugin-auth-tencentcloud ./cmd/vault-plugin-auth-tencentcloud/main.go
```

### Configuration

Copy the plugin binary into a location of your choice; this directory must be specified as
the [`plugin_directory`](https://www.vaultproject.io/docs/configuration#plugin_directory) in the Vault configuration
file:

```hcl
plugin_directory = "vault/plugins"
```

Start a Vault server with this configuration file:

```sh
$ vault server -config=vault/server.hcl
```

Once the server is started, register the plugin in the Vault
server's [plugin catalog](https://www.vaultproject.io/docs/internals/plugins#plugin-catalog):

```shell-session
$ vault auth enable tencentcloud
```sh
$ SHA256=$(shasum -a 256 vault/plugins/vault-plugin-auth-tencentcloud | cut -d ' ' -f1)
$ vault plugin register -sha256=$SHA256 auth vault-plugin-auth-tencentcloud
$ vault plugin info auth vault-plugin-auth-tencentcloud
```

#### Configure the credentials required to make TENCENTCLOUD API calls
You can now enable the tencentCloud auth plugin:

```shell-session
```sh
$ vault auth enable -path=tencentcloud vault-plugin-auth-tencentcloud
Success! Enabled vault-plugin-auth-tencentcloud auth method at: tencentcloud/
```

#### Configure the credentials required to make TencentCLoud API calls

```shell
$ vault write auth/tencentcloud/config/client \
secret_id="..." \
secret_key="..."
```

#### Configure the policies on the role.

```shell-session
vault write auth/tencentcloud/role/dev-role arn='qcs::cam::uin/100021543443:roleName/dev-role'
```shell
$ vault write auth/tencentcloud/role/dev-role arn='qcs::cam::uin/100021543443:roleName/dev-role'
```

#### Perform the login operation

```shell-session
```shell
$ vault write auth/tencentcloud/login \
role=dev-role \
identity_request_url=$IDENTITY_REQUEST_URL_BASE_64 \
identity_request_headers=$IDENTITY_REQUEST_HEADERS_BASE_64
```

For the CAM auth method, generating the signed request is a non-standard
operation. The Vault CLI supports generating this for you:
For the CAM auth method, generating the signed request is a non-standard operation. The Vault CLI supports generating
this for you:

```shell-session
```shell
$ vault login -method=tencentcloud secret_id=... secret_key=... token=... region=... role=...
```

This assumes you have the Tencent Cloud credentials you would find on an CVM instance using the
following call:
This assumes you have the Tencent Cloud credentials you would find on an CVM instance using the following call:

```
```shell
curl 'http://metadata.tencentyun.com/latest/meta-data/cam/security-credentials/$ROLE_NAME'
```

Please note the `$ROLE_NAME` above is case-sensitive and must be consistent with how it's reflected
on the instance.
Please note the `$ROLE_NAME` above is case-sensitive and must be consistent with how it's reflected on the instance.

An example of how to generate the required request values for the `login` method can be found found in the Vault CLI
source code

An example of how to generate the required request values for the `login` method
can be found found in the
Vault CLI source code
## API

The Tencent Cloud auth method has a full HTTP API. Please see the
[Tencent Cloud Auth API](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20-%20Auth%20Methods%20-%20HTTP%20API.md) for more
details.
[Tencent Cloud Auth API](https://github.com/tencentcloudstack/vault-plugin-auth-tencentcloud/blob/master/docs/Tencent%20Cloud%20-%20Auth%20Methods%20-%20HTTP%20API.md)
for more details.

0 comments on commit 6d4e99b

Please sign in to comment.