1# Vault Plugin: AliCloud Auth Backend [![Build Status](https://travis-ci.org/hashicorp/vault-plugin-auth-alicloud.svg?branch=master)](https://travis-ci.org/hashicorp/vault-plugin-auth-alicloud) 2 3This is a standalone backend plugin for use with [Hashicorp Vault](https://www.github.com/hashicorp/vault). 4This plugin allows authentication to Vault using Resource Access Management (RAM). 5 6**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). 7 8## Quick Links 9 - Vault Website: https://www.vaultproject.io 10 - AliCloud Auth Docs: https://www.vaultproject.io/docs/auth/alicloud.html 11 - Main Project Github: https://www.github.com/hashicorp/vault 12 13## Getting Started 14 15This is a [Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html) 16and is meant to work with Vault. This guide assumes you have already installed Vault 17and have a basic understanding of how Vault works. 18 19Otherwise, first read this guide on how to [get started with Vault](https://www.vaultproject.io/intro/getting-started/install.html). 20 21To learn specifically about how plugins work, see documentation on [Vault plugins](https://www.vaultproject.io/docs/internals/plugins.html). 22 23## Security Model 24 25This authentication model places Vault in the middle of a call between a client and AliCloud's "GetCallerIdentity" method. Based on AliCloud's response, it grants an access token based on pre-configured roles. 26 27## Usage 28 29Please see [documentation for the plugin](https://www.vaultproject.io/docs/auth/alicloud.html) 30on the Vault website. 31 32This plugin is currently built into Vault and by default is accessed 33at `auth/alicloud`. To enable this in a running Vault server: 34 35```sh 36$ vault auth enable alicloud 37Successfully enabled 'alicloud' at 'alicloud'! 38``` 39 40To see all the supported paths, see the [AliCloud auth backend docs](https://www.vaultproject.io/docs/auth/alicloud.html). 41 42## Developing 43 44If you wish to work on this plugin, you'll first need 45[Go](https://www.golang.org) installed on your machine. 46 47For local dev first make sure Go is properly installed, including 48setting up a [GOPATH](https://golang.org/doc/code.html#GOPATH). 49Next, clone this repository into 50`$GOPATH/src/github.com/hashicorp/vault-plugin-auth-alicloud`. 51You can then download any required build tools by bootstrapping your 52environment: 53 54```sh 55$ make bootstrap 56``` 57 58To compile a development version of this plugin, run `make` or `make dev`. 59This will put the plugin binary in the `bin` and `$GOPATH/bin` folders. `dev` 60mode will only generate the binary for your platform and is faster: 61 62```sh 63$ make 64$ make dev 65``` 66 67Put the plugin binary into a location of your choice. This directory 68will be specified as the [`plugin_directory`](https://www.vaultproject.io/docs/configuration/index.html#plugin_directory) 69in the Vault config used to start the server. 70 71```json 72... 73plugin_directory = "path/to/plugin/directory" 74... 75``` 76 77Start a Vault server with this config file: 78```sh 79$ vault server -config=path/to/config.json ... 80... 81``` 82 83Once the server is started, register the plugin in the Vault server's [plugin catalog](https://www.vaultproject.io/docs/internals/plugins.html#plugin-catalog): 84 85```sh 86$ vault write sys/plugins/catalog/alicloud \ 87 sha_256=<expected SHA256 Hex value of the plugin binary> \ 88 command="vault-plugin-auth-alicloud" 89... 90Success! Data written to: sys/plugins/catalog/alicloud 91``` 92 93Note you should generate a new sha256 checksum if you have made changes 94to the plugin. Example using openssl: 95 96```sh 97openssl dgst -sha256 $GOPATH/vault-plugin-auth-alicloud 98... 99SHA256(.../go/bin/vault-plugin-auth-alicloud)= 896c13c0f5305daed381952a128322e02bc28a57d0c862a78cbc2ea66e8c6fa1 100``` 101 102Enable the auth plugin backend using the AliCloud auth plugin: 103 104```sh 105$ vault auth enable -plugin-name='alicloud' plugin 106... 107 108Successfully enabled 'plugin' at 'alicloud'! 109``` 110 111#### Tests 112 113If you are developing this plugin and want to verify it is still 114functioning (and you haven't broken anything else), we recommend 115running the tests. 116 117To run the tests, invoke `make test`: 118 119```sh 120$ make test 121``` 122 123You can also specify a `TESTARGS` variable to filter tests like so: 124 125```sh 126$ make test TESTARGS='--run=TestConfig' 127``` 128