I have never been a big fan of creating and managing users on individual systems. I much prefer some sort of centralization of credentials, preferably that somebody else manages when people come and go. That is one of the key reasons I wanted to get the GitHub auth backend up and working in Vault.
Preparing the Environment
Setting up the GitHub authentication backend is pretty straight forward. The most difficult part was digging into how the policies work so that the teams that I add from GitHub have the right permissions. To begin, you need to enable the setup your environment.
export VAULT_ADDR=vault.example.com:8200
export VAULT_TOKEN=a38dc275-86d3-48bd-57ae-237a45d6663b</code>
Once set, you can test your configuration by using the curl command to go to the health endpoint.
% curl -k -X GET ${VAULT_ADDR}/v1/sys/health
{"initialized":true,"sealed":false,"standby":false,"server_time_utc":1477441389,"version":"0.6.2","cluster_name":"vault-cluster-2fbd0333","cluster_id":"d8056c7f-acbb-ae59-4ed4-3673f2d27d48"}</code>
Initialize the GitHub Auth Backend
Once you have verified that the endpoint is working, you can create and configure the auth backend.
curl -k -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{ "type": "github", "description": "Github OAuth Backend" }' $VAULT_ADDR/v1/sys/auth/github</code>
You can verify that the backend was created successfully by doing a GET against sys/auth. If you don’t have jq, I highly recommend you download it, as it makes viewing JSON output much easier.
curl -k -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/auth|jq .</code>
You should see the github backend in the output. Once you have verified that it has been created, the next step is to configure the backend by adding the GitHub organization that you will be authenticating against.
curl -k -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{ "organization": "yourorghere" }' $VAULT_ADDR/v1/auth/github/config
Configure GitHub Team
Next you will need to create a policy that will allow you to actually do something (Deny is the default). This is my initial policy, and I’m sure it is not a great policy, but it is only a POC. Create a file called admin.hcl with the following code.
path "sys/*" {
capabilities = ["create", "update", "read", "delete", "list", "sudo"]
}
path "secret/*" {
capabilities = ["create", "update", "read", "delete", "list"]
}
path "blackbaud-pki/*" {
capabilities = ["create", "update", "read", "delete", "list"]
}
path "auth/token/lookup-self" {
capabilities = ["read", "list"]
}
Once the file has been created, it needs to be uploaded to the server. That can be done through the sys/policy endpoint.
curl -k -X PUT -H "X-Vault-Token: $VAULT_TOKEN" -d @<(jq -n --arg a "$(<./admin.hcl)" '{ "rules": $a }') $VAULT_ADDR/v1/sys/policy/admin
You can validate it by doing a GET against the same endpoint.
curl -k -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/policy/admin
Once the policy is uploaded, you can map it to a team in GitHub.
curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{ "value": "admin" }' $VAULT_ADDR/v1/auth/github/map/teams/myteam
Verify Everything Works
Now you can test to ensure that everything works properly. Head over to Github and generate a Personal access token and then try to authenticate against Vault.
curl $VAULT_ADDR/v1/auth/github/login -d '{ "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }'|jq .
This will return JSON that will give you a client_token you can use to access vault.
To make it easy, you could set your VAULT_TOKEN with the curl command.
export VAULT_TOKEN=$(curl ${VAULT_ADDR}/v1/auth/github/login -d '{ "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }'|jq -r .auth.client_token)
And then test that you are connecting properly to the system.
curl -k -X GET -H "x-Vault-Token: ${VAULT_TOKEN}" ${VAULT_ADDR}/v1/sys/mounts|jq .
Now you can set up other teams with more restricted access.
Comments