Active Directory service account check-out

1. Execute the following command to enable the AD secrets engine at ad/ path.

   $ vault secrets enable ad Success! Enabled the ad secrets engine at: ad/

   If you want to enable the secrets engine at a different path, use the -path parameter to specify your desired path. Otherwise, the secrets engine gets enabled at a path named after its type. Since the type is ad in this example, its path becomes ad in absence of -path parameter.

2. To configure the AD secrets engine, you need to set the following parameters.

   parameter	Description
   binddn	Distinguished name of object to bind when performing user and group search
   bindpass	Password to use along with binddn when performing user search
   url	The AD sever URL
   userdn	Base DN under which to perform user search

   This is a subset of available parameters. Refer to the API documentation for the full list of configuration parameters.

3. Export the username as a USERNAME environment variable.

   $ export USERNAME=<YOUR-VAULT-USERNAME-IN-AD@YOUR-AD-ROOT-DOMAIN>

4. Export the password as a PASSWORD environment variable.

   $ export PASSWORD=<YOUR-VAULT-USER-IN-AD-PASSWORD>

5. Execute the vault write ad/config command with correct AD server configuration information.

   $ vault write ad/config binddn=$USERNAME \      bindpass=$PASSWORD \      url=ldaps://127.0.0.11 \      userdn='dc=example,dc=com' \      insecure_tls=true

   Output:

   Success! Data written to: ad/config

1. The following command example enable ad secrets engine at sys/mounts/ad path.

   $ curl --header "X-Vault-Token: <TOKEN>" \      --request POST \      --data '{"type":"ad"}' \      http://127.0.0.1:8200/v1/sys/mounts/ad

   Where the X-Vault-Token header value is set to your valid token.

   In this tutorial, the AD secrets engine is enabled at the /ad path in Vault. However, it is possible to enable your secrets engines at any location.

2. To configure the AD secrets engine, the following parameters will be set.

   parameter	Description
   binddn	Distinguished name of object to bind when performing user and group search
   bindpass	Password to use along with binddn when performing user search
   url	The AD sever URL
   userdn	Base DN under which to perform user search

   This is a subset of available parameters. Refer to the API documentation for the full list of configuration parameters.

   Execute the ad/config endpoint to configure the AD secrets engine.

   Example:

   First, create an API request payload.

   $ tee payload.json <<EOF{  "binddn": "CN=vault-ad-test,CN=Users,DC=example,DC=com",  "bindpass": "pa$$w0rd",  "url": "ldaps://127.0.0.11",  "userdn": "dc=example,dc=com",  "insecure_tls": true}EOF

   Invoke the ad/config endpoint to configure the AD secrets engine.

   $ curl --header "X-Vault-Token: <TOKEN>" --request POST \      --data @payload.json \      http://127.0.0.1:8200/v1/ad/config

1. Execute the following command to create a library named accounting-team with a ttl set to 24 hours and max_ttl set to 5 days.

   $ vault write ad/library/accounting-team \        service_account_names="testMSA@example.com,MSA4SQL@example.com" \        ttl=24h \        max_ttl=120hSuccess! Data written to: ad/library/accounting-team

2. Execute the following command to list the existing libraries.

   $ vault list ad/library Keys----accounting-team

3. Execute the following command to view the status of the accounts in the library.

   $ vault read ad/library/accounting-team/status Key                 Value---                 -----MSA4SQL@example.com    map[available:true]testMSA@example.com    map[available:true]

   Both service accounts are available for check-out.

1. Create the API request payload to define a library name to be accounting-team with ttl set to 24 hours and max_ttl is set to 5 days.

   $ tee payload.json <<EOF{  "service_account_names": ["testMSA@example.com", "MSA4SQL@example.com"],  "ttl": "24h",  "max_ttl": "120h"}EOF

2. Execute the ad/library endpoint to create a library.

   $ curl --header "X-Vault-Token: <TOKEN>" \      --request POST \      --data @payload.json \      http://127.0.0.1:8200/v1/ad/library/accounting-team

3. Execute the ad/library endpoint to list the existing libraries.

   $ curl --header "X-Vault-Token: <TOKEN>" \      --request LIST      http://127.0.0.1:8200/v1/ad/library | jq{  ...  "data": {    "keys": [      "accounting-team"    ]  },  ...}

4. Execute the ad/library/accounting-team/status endpoint to view the status of the accounts in the library.

   $ curl --header "X-Vault-Token: <TOKEN>" \      http://127.0.0.1:8200/v1/ad/library/accounting-team/status | jq{  ...  "data": {    "MSA4SQL@example.com": {      "available": true    },    "testMSA@example.com": {      "available": true    }  },  "testMSA@example.com": {    "available": true  }},...}

Execute the following command to create a policy named, acct-team.

$ vault policy write acct-team acct-team.hcl Success! Uploaded policy: acct-team

Execute the sys/policies/acl endpoint to create a policy named, acct-team.

# Create the API request payload. Use stringified policy expression.$ tee policy-payload.json <<EOF{  "policy": "# To check-out a service account which is a part of accounting-team library\npath \"ad/library/accounting-team/check-out\" {\n  capabilities = [ \"update\" ]\n}\n\n# To allow the extension of TTL\npath \"sys/leases/renew\" {\n  capabilities = [ \"update\" ]\n}\n\n# To check back in a service account\npath \"ad/library/accounting-team/check-in\" {\n  capabilities = [ \"update\" ]\n}\n\n# If you want to allow the client to see the library status\npath \"ad/library/accounting-team/status\" {\n  capabilities = [ \"read\" ]\n}"}EOF # Create admin policy$ curl --header "X-Vault-Token: <TOKEN>" \       --request PUT \       --data @policy-payload.json \       http://127.0.0.1:8200/v1/sys/policies/acl/acct-team

1. Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.

2. Click the Policies tab, and then select Create ACL policy.

3. Toggle the Upload file sliding switch, and click Choose a file to select your acct-team.hcl file you authored.

4. Click Create Policy to complete.

1. First, generate a client token with acct-team policy attached and store it in a VAULT_TOKEN environment variable.

   Example:

   $ vault token create -policy=acct-team Key                  Value---                  -----token                s.1jJFckALyEShvimC7kxizd3Ytoken_accessor       JiFqVsH7PKfGeIX8McFqwGgOtoken_duration       768htoken_renewable      truetoken_policies       ["acct-team" "default"]identity_policies    []policies             ["acct-team" "default"] # Store the generated client token as VAULT_TOKEN env var$ export VAULT_TOKEN=s.1jJFckALyEShvimC7kxizd3Y

2. Check-out a service account managed by the accounting-team library.

   $ vault write -f ad/library/accounting-team/check-out Key                     Value---                     -----lease_id                ad/library/accounting-team/check-out/SVNimFfpLKwWThHq1eGBG5mjlease_duration          768hlease_renewable         truepassword                ?@09AZFIwvunQIThl0RTMI1o3gTGZ7hinlQuUaBJMIPTURin3Ub0n9zkRSgLr0vMservice_account_name    testMSA@example.com

   Now, the testMSA@example.com account has been checked out and its password has been dynamically generated by Vault.

   Note

   If no service accounts are available for check-out, Vault will return a 400 Bad Request. This may be an indication that an organization may need to add more service accounts to the library or reduce the number of requestors trying to use them at the same time.

3. View the library status.

   $ vault read ad/library/accounting-team/status Key                 Value---                 -----MSA4SQL@example.com    map[available:true]testMSA@example.com    map[available:false borrower_client_token:49aef0b628c06d77d4237da3cedc6ec29e0e51ae]

   It is shown that testMSA@example.com is now checked out.

4. When you are done, check back in the service account by executing the following command.

   $ vault write -f ad/library/accounting-team/check-in Key          Value---          -----check_ins    [testMSA@example.com]

1. First, generate a client token with acct-team policy attached and store it in a VAULT_TOKEN environment variable.

   $ curl --request POST --header "X-Vault-Token: <TOKEN>" \      --data '{ "policies": "acct-team" }' \      http://127.0.0.1:8200/v1/auth/token/create{  ...  "auth": {    "client_token": "s.7hO8OHNg6YMi4YYAIjMzRo6Y",    "accessor": "wGqT2H3MM6CVzIF57wCIYCLg",    "policies": [      "acct-team",      "default"    ],    "token_policies": [      "acct-team",      "default"    ],    ...  }}

2. Check-out a service account managed by the accounting-team library.

   $ curl --header "X-Vault-Token: s.7hO8OHNg6YMi4YYAIjMzRo6Y \      --request POST \      http://127.0.0.1:8200/v1/ad/library/accounting-team/check-out | jq{  "request_id": "5e468a48-0316-158e-8e03-9e171a8a0f48",  "lease_id": "ad/library/accounting-team/check-out/HR2AsbSQbNVQCSzx6WTRCLqH",  "renewable": true,  "lease_duration": 86400,  "data": {    "password": "?@09AZ6Jane6QAjf54kgEpz6R/7ggOKLT93cxpbn2kaY20DfzX7bIKtUbLsl0Y6c",    "service_account_name": "testMSA@example.com"  },  ...}

   Now, the testMSA@example.com account has been checked out and its password has been dynamically generated by Vault.

   Note

   If no service accounts are available for check-out, Vault will return a 400 Bad Request. This may be an indication that an organization may need to add more service accounts to the library or reduce the number of requestors trying to use them at the same time.

3. View the library status.

   $ curl --header "X-Vault-Token: <TOKEN>" \      http://127.0.0.1:8200/v1/ad/library/accounting-team/status | jq{  ...  "data": {    "MSA4SQL@example.com": {      "available": true    },    "testMSA@example.com": {      "available": false,      "borrower_client_token": "8ee2c9a26f187d88e068f1631a1acd183484287d"    }  },  ...}

   It is shown that testMSA@example.com is now checked out.

4. When you are done, check back in the service account by invoking the ad/library/accounting-team/check-in endpoint.

   $ curl --header "X-Vault-Token: s.7hO8OHNg6YMi4YYAIjMzRo6Y" \        --request POST \        http://127.0.0.1:8200/v1/ad/library/accounting-team/check-in{  ...  "data": {    "check_ins": [      "testMSA@example.com"    ]  },  ...}

1. Log back in with your admin token.

2. Execute the following command to update the ttl and max_ttl.

   $ vault write ad/library/accounting-team \        service_account_names="testMSA@example.com,MSA4SQL@example.com" \        ttl=20 \        max_ttl=40

3. Check-out a service account, wait for 20 seconds and then try renewing the lease.

   $ vault write -f ad/library/accounting-team/check-out Key                     Value---                     -----lease_id                ad/library/accounting-team/check-out/cp4X5rcwQrp3w8f4lMj2jhTolease_duration          20slease_renewable         truepassword                ?@09AZBbCyiLZtx+DPKYducATJ3HH/kZe2BuzCIC+oDpPpoD71PQW9L5iLaLahahservice_account_name    testMSA@example.com # Wait for 20 seconds# Try renewing the TTL using the lease_id$ vault lease renew ad/library/accounting-team/check-out/cp4X5rcwQrp3w8f4lMj2jhTo

   While ad/library/accounting-team/check-out/cp4X5rcwQrp3w8f4lMj2jhTo is the lease_id.

   The lease renew command returns lease not found error.

4. Check the library status.

   $ vault read ad/library/accounting-team/status Key                 Value---                 -----MSA4SQL@example.com    map[available:true]testMSA@example.com    map[available:true]

   Both service accounts are available for check-out. This is because Vault automatically checked in testMSA@example.com after the TTL expired.

1. Execute the ad/config endpoint to update the ttl and max_ttl set on the accounting-team library to be 20 seconds and 40 seconds respectively.

   # Create the HTTP request payload$ tee payload.json <<EOF{  "service_account_names": ["testMSA@example.com", "MSA4SQL@example.com"],  "ttl": "20s",  "max_ttl": "40s"}EOF # Invoke the ad/library API endpoint$ curl --header "X-Vault-Token: <TOKEN>" \      --request POST \      --data @payload.json \      http://127.0.0.1:8200/v1/ad/library/accounting-team

2. Check-out a service account, wait for 20 seconds and then try renewing the lease.

   $ curl --header "X-Vault-Token: <TOKEN>" \      --request POST \      http://127.0.0.1:8200/v1/ad/library/accounting-team/check-out | jq{  "request_id": "b8130438-3651-e17c-bf23-da203a554768",  "lease_id": "ad/library/accounting-team/check-out/MJJfJyBSG1Wfh1FqiGxA3pWN",  "renewable": true,  "lease_duration": 20,  "data": {    "password": "?@09AZn1H2P0pUngP7hPeG3QNgo5BrA0/Dx0fI6gDaCBuadfRUw6zmQqZ5MSF9B8",    "service_account_name": "testMSA@example.com"  },  ...}

3. Wait for 20 seconds and try renewing the TTL using the lease_id.

   $ curl --header "X-Vault-Token: <TOKEN>" \      --request POST \      --data '{ "lease_id": "ad/library/accounting-team/check-out/MJJfJyBSG1Wfh1FqiGxA3pWN"}' \      http://127.0.0.1:8200/v1/sys/lease/renew | jq{  "errors": [    "lease not found"  ]}

   While ad/library/accounting-team/check-out/MJJfJyBSG1Wfh1FqiGxA3pWN is the lease_id.

4. Execute the ad/library/accounting-team/status endpoint to view the status of the accounts in the library.

   $ curl --header "X-Vault-Token: <TOKEN>" \      http://127.0.0.1:8200/v1/ad/library/accounting-team/status | jq{  ...  "data": {    "MSA4SQL@example.com": {      "available": true    },    "testMSA@example.com": {      "available": true    }  },  ...}

   Both service accounts are available for check-out. This is because Vault automatically checked in testMSA@example.com after the TTL expired.

Example:

$ vault write ad/library/accounting-team \        service_account_names="testMSA@example.com,MSA4SQL@example.com" \        ttl=24h \        max_ttl=120h \        disable_check_in_enforcement=true

Example:

# Create the HTTP request payload$ tee payload.json <<EOF{  "service_account_names": ["testMSA@example.com", "MSA4SQL@example.com"],  "ttl": "24h",  "max_ttl": "120h",  "disable_check_in_enforcement": true}EOF # Invoke the ad/library API endpoint$ curl --header "X-Vault-Token: <TOKEN>" \       --request POST \       --data @payload.json \       http://127.0.0.1:8200/v1/ad/library/accounting-team

$ vault lease revoke ad/library/accounting-team/check-out/zklrSdycrQnwuxvAqCkIJkaV

While ad/library/accounting-team/check-out/zklrSdycrQnwuxvAqCkIJkaV is the lease_id.

$ curl --header "X-Vault-Token: <TOKEN>"  \       --request POST \       --data '{ "lease_id": "ad/library/accounting-team/check-out/zklrSdycrQnwuxvAqCkIJkaV" }'  \       http://127.0.0.1:8200/v1/sys/leases/revoke

While ad/library/accounting-team/check-out/zklrSdycrQnwuxvAqCkIJkaV is the lease_id.