open-vault/website/source/docs/secrets/databases/mssql.html.md
Jeff Escalante a3dfde5cec New Docs Website (#5535)
* conversion stage 1

* correct image paths

* add sidebar title to frontmatter

* docs/concepts and docs/internals

* configuration docs and multi-level nav corrections

* commands docs, index file corrections, small item nav correction

* secrets converted

* auth

* add enterprise and agent docs

* add extra dividers

* secret section, wip

* correct sidebar nav title in front matter for apu section, start working on api items

* auth and backend, a couple directory structure fixes

* remove old docs

* intro side nav converted

* reset sidebar styles, add hashi-global-styles

* basic styling for nav sidebar

* folder collapse functionality

* patch up border length on last list item

* wip restructure for content component

* taking middleman hacking to the extreme, but its working

* small css fix

* add new mega nav

* fix a small mistake from the rebase

* fix a content resolution issue with middleman

* title a couple missing docs pages

* update deps, remove temporary markup

* community page

* footer to layout, community page css adjustments

* wip downloads page

* deps updated, downloads page ready

* fix community page

* homepage progress

* add components, adjust spacing

* docs and api landing pages

* a bunch of fixes, add docs and api landing pages

* update deps, add deploy scripts

* add readme note

* update deploy command

* overview page, index title

* Update doc fields

Note this still requires the link fields to be populated -- this is solely related to copy on the description fields

* Update api_basic_categories.yml

Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.

* Add bottom hero, adjust CSS, responsive friendly

* Add mega nav title

* homepage adjustments, asset boosts

* small fixes

* docs page styling fixes

* meganav title

* some category link corrections

* Update API categories page

updated to reflect the second level headings for api categories

* Update docs_detailed_categories.yml

Updated to represent the existing docs structure

* Update docs_detailed_categories.yml

* docs page data fix, extra operator page remove

* api data fix

* fix makefile

* update deps, add product subnav to docs and api landing pages

* Rearrange non-hands-on guides to _docs_

Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.

* WIP Redirects for guides to docs

* content and component updates

* font weight hotfix, redirects

* fix guides and intro sidenavs

* fix some redirects

* small style tweaks

* Redirects to learn and internally to docs

* Remove redirect to `/vault`

* Remove `.html` from destination on redirects

* fix incorrect index redirect

* final touchups

* address feedback from michell for makefile and product downloads
2018-10-19 08:40:11 -07:00

162 lines
6.2 KiB
Markdown

---
layout: "docs"
page_title: "MSSQL - Database - Secrets Engines"
sidebar_title: "MSSQL"
sidebar_current: "docs-secrets-databases-mssql"
description: |-
MSSQL is one of the supported plugins for the database secrets engine. This
plugin generates database credentials dynamically based on configured roles
for the MSSQL database.
---
# MSSQL Database Secrets Engine
MSSQL is one of the supported plugins for the database secrets engine. This
plugin generates database credentials dynamically based on configured roles for
the MSSQL database.
See the [database secrets engine](/docs/secrets/databases/index.html) docs for
more information about setting up the database secrets engine.
## Setup
1. Enable the database secrets engine if it is not already enabled:
```text
$ vault secrets enable database
Success! Enabled the database secrets engine at: database/
```
By default, the secrets engine will enable at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument.
1. Configure Vault with the proper plugin and connection information:
```text
$ vault write database/config/my-mssql-database \
plugin_name=mssql-database-plugin \
connection_url='sqlserver://{{username}}:{{password}}@localhost:1433' \
allowed_roles="my-role" \
username="sa" \
password="yourStrong(!)Password"
```
In this case, we've configured Vault with the user "sa" and password
"yourStrong(!)Password", connecting to an instance at "localhost" on port 1433. It is
not necessary that Vault has the sa login, but the user must have privileges
to create logins and manage processes. The fixed server roles
`securityadmin` and `processadmin` are examples of built-in roles that grant
these permissions. The user also must have privileges to create database
users and grant permissions in the databases that Vault manages. The fixed
database roles `db_accessadmin` and `db_securityadmin` are examples or
built-in roles that grant these permissions.
1. Configure a role that maps a name in Vault to an SQL statement to execute to
create the database credential:
```text
$ vault write database/roles/my-role \
db_name=my-mssql-database \
creation_statements="CREATE LOGIN [{{name}}] WITH PASSWORD = '{{password}}';\
CREATE USER [{{name}}] FOR LOGIN [{{name}}];\
GRANT SELECT ON SCHEMA::dbo TO [{{name}}];" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/my-role
```
## Usage
After the secrets engine is configured and a user/machine has a Vault token with
the proper permission, it can generate credentials.
1. Generate a new credential by reading from the `/creds` endpoint with the name
of the role:
```text
$ vault read database/creds/my-role
Key Value
--- -----
lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
lease_duration 1h
lease_renewable true
password 8cab931c-d62e-a73d-60d3-5ee85139cd66
username v-root-e2978cd0-
```
## Example for Azure SQL Database
Here is a complete example using Azure SQL Database. Note that databases in Azure SQL Database are [contained databases](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases) and that we do not create a login for the user; instead, we associate the password directly with the user itself. Also note that you will need a separate connection and role for each Azure SQL database for which you want to generate dynamic credentials. You can use a single database backend mount for all these databases or use a separate mount for of them. In this example, we use a custom path for the database backend.
First, we mount a database backend at the azuresql path with `vault secrets enable -path=azuresql database`. Then we configure a connection called "testvault" to connect to a database called "test-vault", using "azuresql" at the beginning of our path:
```
$ vault write azuresql/config/testvault \
plugin_name=mssql-database-plugin \
connection_url='server=hashisqlserver.database.windows.net;port=1433; \
user id=admin;password=pAssw0rd;database=test-vault;app name=vault;' \
allowed_roles="test"
```
Now we add a role called "test" for use with the "testvault" connection:
```
$ vault write azuresql/roles/test \
db_name=testvault \
creation_statements="CREATE USER [{{name}}] WITH PASSWORD = '{{password}}';" \
revocation_statements="DROP USER IF EXISTS [{{name}}]" \
default_ttl="1h" \
max_ttl="24h"
```
We can now use this role to dynamically generate credentials for the Azure SQL database, test-vault:
```
$ vault read azuresql/creds/test
Key Value
--- -----
lease_id azuresql/creds/test/2e5b1e0b-a081-c7e1-5622-39f58e79a719
lease_duration 1h0m0s
lease_renewable true
password A1a-48w04t1xzw1s33z3
username v-token-test-tr2t4x9pxvq1z8878s9s-1513446795
```
When we no longer need the backend, we can unmount it with `vault unmount azuresql`. Now, you can use the MSSQL Database Plugin with your Azure SQL databases.
## Amazon RDS
The MSSQL plugin supports databases running on [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_SQLServer.html),
but there are differences that need to be accomodated. A key limitation is that Amazon RDS doesn't support
the "sysadmin" role, which is used by default during Vault's revocation process for MSSQL. The workaround
is to add custom revocation statements to roles, for example:
```
vault write database/roles/my-role revocation_statements="\
USE my_database; \
IF EXISTS \
(SELECT name \
FROM sys.database_principals \
WHERE name = N'{{name}}') \
BEGIN \
DROP USER [{{name}}] \
END \
IF EXISTS \
(SELECT name \
FROM master.sys.server_principals \
WHERE name = N'{{name}}') \
BEGIN \
DROP LOGIN [{{name}}] \
END"
```
## API
The full list of configurable options can be seen in the [MSSQL database
plugin API](/api/secret/databases/mssql.html) page.
For more information on the database secrets engine's HTTP API please see the
[Database secrets engine API](/api/secret/databases/index.html) page.