10.77KiB; Markdown | 2019-05-01 11:37:00+02 | SLOC 159
1
2
![logo](T-Vault.png)
3
4
# T-Vault
5
T-Vault is built to simplify the process of secrets management. We wanted to build an intuitive and easy to use tool that application developers can easily adopt without sacrificing their agility while still following best practices for secrets management.
6
It uses a few open source products internally including, at its heart [Hashicorp Vault][1]. Hashicorp vault provides the core functionality of safely storing secrets at rest and access control to those secrets. T-Vault builds on that base to provide a higher-level of abstraction called Safe. Safes are logical abstractions, internally using the concept of paths within vault.␣
7
T-Vault simplifies the access management to secrets by hiding away all the complexities of managing policies.␣
8
9
A very intuitive web UI provides a nice layer of abstraction and hides all the complexities of managing paths, policies, token management, etc. T-Vault introduces two new personas, a 'Safe User' and 'Safe Administrator'. Both can create Safes and grant access to individuals or LDAP group or an application. They can also create and Manage Approles to use in their applications. Safe Administrators can manage Safes and AppRoles created by all the users. But non admin users can manage only the Safes and AppRoles created by himself. Individuals with access to a Safe can use the web UI or API to do CRUD operations on secrets within their Safe.
10
11
When a Safe is created, T-Vault automatically creates the paths and boilerplate policies for that path. It also saves metadata about the Safe internally within the vault. Granting access to an individual for Safe involves associating user to the predefined policy for the path associated with the Safe. App roles and AWS App roles creation and granting access to them works the same way.
12
13
This readme file provides instructions to download, install, configure and use T-Vault API and user portal.
14
15
Here is a quick demo video.
16
17
18
19
<a href="http://www.youtube.com/watch?feature=player_embedded&v=fv3GOiFYAt8
20
" target="_blank"><img src="http://img.youtube.com/vi/fv3GOiFYAt8/0.jpg"␣
21
alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" /></a>
22
23
24
25
# Table of Contents
26
27
1. [Installation](#installation)
28
    * [Installation Prerequisites](#installation-prerequisites)
29
    * [How to install](#installation-steps)
30
2. [Configuration](#t-vault-configuration)
31
   * [Default Installation](#default-installation)
32
   * [Configuration Options](#t-vault-configuration-options)
33
3. [Install in Production](#install-in-production)
34
   * [Setup](#setup)
35
   * [High Availability](#high-availability)
36
   * [Un-Sealing](#un-sealing)
37
4. [License](#license)
38
39
40
# Installation
41
42
## Installation on Linux
43
44
### Installation-Prerequisites
45
46
Below are the dependencies required to build T-Vault from source.
47
48
* [JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) - Required to compile/build java source code
49
* [Maven](https://maven.apache.org) - Required to build/package
50
* [Docker](https://www.docker.com/) - Required if docker based deployment is preferred
51
* [Node](https://nodejs.org/en/) and build tools (sudo yum install gcc-c++ make, sudo yum groupinstall 'Development Tools', bzip2)
52
* [Bower](https://bower.io/)
53
* [Gulp](https://gulpjs.com/)
54
55
56
### Installation Steps
57
58
You can build T-Vault from source using build_vault.sh. There are two packaging options available. The script can create a tar file or a docker image.
59
* In case you choose 'tar' option, please make sure all the development tools are installed on Linux.␣
60
* For the case of docker image, make sure docker service is running locally.
61
62
#### Tar based installation
63
64
* Download source code (https://github.com/tmobile/t-vault).
65
* Go to the parent directory of the source code tree and run the command <pre>./build_tvault.sh --build all --package tar</pre>
66
* This will build both T-Vault API and user portal and generate tar file tvault_all.tar.gz
67
* Run the command <pre>./install_tvault.sh</pre>to install and start T-Vault and all of the dependent services.
68
69
70
#### Docker container based installation
71
72
[Docker](https://www.docker.com/) needs to be installed and running before performing this.
73
74
* Download source code (https://github.com/tmobile/t-vault).
75
* Go to the parent directory of the source code tree and run the command <pre>./build_tvault.sh --build all --package docker</pre>
76
* This will build both T-Vault API and user portal and push the docker image to local docker hub
77
* Run the command <pre>docker run --privileged -it -p 443:443 -p 8200:8200  your_tvault_docker_image_id /bin/bash</pre> to start cloud vault and all of the dependent services
78
79
80
### How to access T-Vault Services
81
82
After completing the installation, you can access
83
84
* The T-Vault User Portal using the URL https://your_ip_address
85
* The T-Vault API using the URL https://your_ip_address:8080
86
* The Vault Service using the URL https://your_ip_address:8200
87
88
89
# T-Vault Configuration
90
91
## Default Installation
92
Default installation, sets up vault with␣
93
* AUTH BACKEND : Username Password
94
* STORAGE BACKEND : File System
95
96
`Default installation should be used only to test drive the tool, it should not be used in production environments. HA is not supported with the default installation.`
97
98
The default installation sets up few default users so that you can explore the tool right away.
99
100
1. safeadmin/safeadmin
101
102
   Safe Admin user. This user has all the privileges to create and manage safes. Post installation login with safeadmin to create safes and grant access to testuser1 & 2.␣␣
103
104
2. vaultadmin/vaultadmin
105
106
   This is a Vault Admin user. By default this user is attached with policies to manage all the paths excepts for secret store mounts.␣␣
107
␣␣␣
108
 3. testuser1/testuser1, testuser2/testuser2
109
␣␣␣␣
110
    These two testusers doesnt have any previleges by default. You can grant access to these users and try out the functionalities of T-Vault.␣␣
111
112
113
## T-Vault Configuration Options
114
T-Vault supports Following Auth Backends and Storage Backends.
115
116
Auth Backends
117
```
118
* Username Password
119
* LDAP
120
* AWS Authentication
121
```
122
123
Storage Backends
124
```
125
* Consul
126
* File System
127
* Dynamo DB
128
```
129
130
You can configure your installation with combination of any of the Auth Backend and Storage Backend listed above.
131
132
The installation script requires the vault configuration information. These configurations are managed from the parameters file.
133
Sample T-Vault configuration parameters file.
134
135
```
136
###########################################################################
137
#                            Auth Backend                                 #
138
###########################################################################
139
140
# Allowed values for AUTH_BACKEND are userpass, ldap
141
AUTH_BACKEND=userpass
142
ENABLE_AWS=yes
143
144
###########################################################################
145
#                      LDAP Credentials                                   #
146
###########################################################################
147
148
#LDAP_URL='ldap://hostname.com:port'
149
#LDAP_GROUP_ATTR_NAME='cn'
150
#LDAP_USR_ATTR_NAME='---'
151
#USER_DN='---'
152
#GROUP_DN='----'
153
#BIND_DN='---'
154
#BIND_DN_PASS='---'
155
#TLS_ENABLED='false'
156
#VAULT_ADMIN_GROUP='---'
157
#SAFE_ADMIN_GROUP='---'
158
159
## The value for USE_UPNDOMAIN is either 'yes' or 'no'
160
161
#USE_UPNDOMAIN='yes'
162
#UPN_DOMAIN_URL='---'
163
164
165
##########################################################################
166
#                        Storage Backend                                 #
167
##########################################################################
168
# The possible values are 'File System' or 'Consul'
169
BACKEND='File System'
170
171
##########################################################################
172
#                         Consul Parameters                              #
173
##########################################################################
174
175
CONSUL_DATACENTER='dc1'
176
#CONSUL_ENCRYPT=''
177
CONSUL_RETRY_JOIN='127.0.0.1'
178
CONSUL_STORAGE_ADDRESS='127.0.0.1:8500'
179
CONSUL_STORAGE_PATH='tvault/tvault'
180
CONSUL_STORAGE_SERVICE_NAME='tvault'
181
182
##########################################################################
183
#                       Global                                           #
184
##########################################################################
185
186
SELF_SIGNED='y'
187
188
##########################################################################
189
#                         DynamoDB Parameters                            #
190
##########################################################################
191
192
#AWS_DYNAMODB_TABLE='tvault'
193
#AWS_DEFAULT_REGION='us-west-2'
194
195
```
196
197
# Install in Production
198
## Setup
199
For production installations use
200
```
201
1. AUTH BACKEND : LDAP
202
2. STORAGE BACKEND : Consul
203
```
204
205
Consul is the only storage backend that supports HA. When using LDAP as auth backend, you need to configure additional LDAP related parameters, two group names should be configured for setting up admin users for the T-Vault.
206
207
```
208
* SAFE_ADMIN_GROUP: All the members of this group will get safe admin privileges.
209
* VAULT_ADMIN_GROUP: All the members of this group will get vault admin privileges.
210
```
211
212
## High Availability
213
T-Vault has following components
214
215
|Component| Description|
216
|-----------------|-----------------------------------------------------------------------------------------|
217
|Nginx            |Hosts the UI, acts as a proxy for T-Vault API and Vault's native http rest interface.|
218
|Springboot App   |T-Vault API layer|
219
|Hashicorp Vault  |As is Hashicorp Vault|
220
221
Hashicorp Vault supports high availability with Consul as storage backend.
222
223
224
T-Vault UI, API and Vault is all bundled together into one unit. You can horizontally scale this unit and point it towards an HA Consul Cluster. If required you could split it up into multiple tiers and have load balancing and horizontal scaling for each of the layer.
225
226
Internally we have deployed our T-Vault on a container platform. The build scripts will create a readily usable tvault docker container (assuming with correct configuration file) which is then pushed to our container platform. We maintain a Consul cluster outside of the container platform.
227
228
229
## Un-sealing
230
One of the challenges with open source version of vault is, how to unseal a new instance of vault in case of HA setup. We have built an automated unsealing process using KMS and IAM Roles. You can come up with a solution that works for you. Same way the distribution of the master keys can be added to the installation script based on your preference.
231
232
For standalone installations on VMs, where automatic un-sealing is not preferred, T-Vault has web pages to un-seal vault instances manually(https://host:port/#/unseal). Users have to enter 3 out of 5 keys in the un-seal web form (or whatever the threshold that was used). Key holders can go to the unseal page and enter the IP address of the sealed vault and enter their master key to start unsealing.
233
234
235
# License
236
237
T-Vault is released under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
238
239
240
[1]: https://github.com/hashicorp/vault