diff --git a/README.md b/README.md index 6c54494..fbbcc8e 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ # 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) @@ -13,49 +16,87 @@ This plugin allows authentication to Vault using Cloud Access Management (CAM). ## 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 @@ -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 @@ -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. diff --git a/docs/Tencent Cloud Auth Method.md b/docs/Tencent Cloud Auth Method.md index f12f06e..c1f6347 100644 --- a/docs/Tencent Cloud Auth Method.md +++ b/docs/Tencent Cloud Auth Method.md @@ -1,53 +1,82 @@ - # 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="..." @@ -55,41 +84,39 @@ $ vault write auth/tencentcloud/config/client \ #### 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.