Managing Tokens for Your Vault Instance

About Managing Tokens

Vault service creates a token when you bind your application to the Vault service instance or create a service key. You use this token to access your Vault service instance. You can use Vault service REST APIs to manage these tokens. You can use the APIs to lookup the token details, renew the token, or revoke a token.

The default time to live (TTL) for a Vault service instance token is 32 days. You can generate tokens with specific TTL when you either bind your application to your Vault service instance or by creating a new service key.

You can use Vault service API to perform the following tasks:

In addition, you can also:

APIs: Managing Tokens

Lookup Token Details of your Vault Service Instance

API/auth/token/lookup-self
DescriptionLookup details of the token for your Vault service instance.
MethodGET
URL/auth/token/lookup-self

For example, you can construct your URL to perform this operation as follows:

https://predix-vault-asv.gecis.io/v1/auth/token/lookup-self
Note: You can get the path to Vault service from your VCAP_SERVICES environment variable.
ParametersNone
HeaderX-Vault-Token: <token>
Returns 
{
    "data":{
    "accessor":"REDACTED",
    "creation_time":1484093665,
    "creation_ttl":3600,
    "display_name":"github-armon",
    "explicit_max_ttl":0,
        "id":"ClientToken",
        "meta":{"user":"armon","organization":"hashicorp"},
    "num_uses":0,
    "orphan":true,
    "path":"auth/github/login",
    "policies":["web","stage"],
    "renewable":true,
    "ttl":3655
    }
}

Renew the Token of your Vault Service Instance

API/auth/token/renew-self
DescriptionRenews the lease associated with the calling token. This prevents the expiration and automatic revocation of the token. You can renew a token only if there is a lease associated with it.
MethodPOST
URL/auth/token/renew-self

For example, you can construct your URL to perform this operation as follows:

https://predix-vault-asv.gecis.io/v1/auth/token/renew-self
Note: You can get the path to Vault service from your VCAP_SERVICES environment variable.
Parameters
  • increment (optional)

    Specify the increment value for the token lease.

HeaderX-Vault-Token: <token>
Returns 
{
    "auth":{
        "client_token":"ABCD",
        "policies":["web","stage"],
        "metadata":{"user":"armon"},
        "lease_duration":3600,
        "renewable":true,
    }
}

Revoke the Token of your Vault Service Instance

API/auth/token/revoke-self
DescriptionRevokes the token that you use for your Vault service instance. When the token is revoked, all secrets generated with it are also revoked.
MethodPOST
URL/auth/token/revoke-self

For example, you can construct your URL to perform this operation as follows:

https://predix-vault-asv.gecis.io/v1/auth/token/revoke-self
Note: You can get the path to Vault service from your VCAP_SERVICES environment variable.
ParametersNone
HeaderX-Vault-Token: <token>
ReturnsA 204 response code.

Rotating the Token for your Vault Service Instance

You can rotate the token for your Vault Service Instance to get a new value for your token.

Procedure

  1. To rotate the token, you can unbind your application from your Vault service instance and bind it again.
    For more information on binding your application, see vault-service-get-started.html#task_0c97a8d8-4ca5-42c4-8a93-10e3657b283a.
  2. Optionally, you can create a new service key for your Vault service. The new service key contains a new token value.
    For more information on service key, see vault-service-get-started.html#task_3bbe9bb0-ff26-409e-99ee-b362f139e3ca.

Specifying Duration of the Token for Your Vault Service Instance

The default time to live (TTL) for a Vault service instance token is 32 days. You can specify the duration of the tokens when you either bind your application to your Vault service instance or by creating a new service key.

About This Task

You can either generate a token that lives forever (perpetual) or a token with specific time to live (TTL).

Procedure

  1. You can specify custom parameters when you bind your application to your Vault service instance.
    • For a token with unlimited duration, use the following command:
      cf bind-service <your_app_name> <vault_instance_name> -c '{"token_type" : "perpetual"}'
    • For token with specific TTL value, use the following command:
      cf bind-service <your_app_name> <vault_instance_name> -c '{"token_type" : "periodic", "token_ttl" : "<duration>"}'

    For more information on binding your application, see vault-service-get-started.html#task_0c97a8d8-4ca5-42c4-8a93-10e3657b283a.

  2. Optionally, you can create a new service key with custom parameters for your Vault service. The new service key contains a new token value.
    • For a token with unlimited duration, use the following command:
      cf create-service-key <vault_instance_name> <service-key-name> -c '{"token_type" : "perpetual"}'
    • For token with specific TTL value, use the following command:
      cf create-service-key <vault_instance_name> <service-key-name> -c '{"token_type" : "periodic", "token_ttl" : "<duration>"}'
    For more information on service key, see vault-service-get-started.html#task_3bbe9bb0-ff26-409e-99ee-b362f139e3ca.

Adding a Read-Only Policy to the Token

When you add a read-only policy to a token, a user can read the token details but cannot create, update or delete the token.

Procedure

  1. You can specify custom parameters when you bind your application to your Vault service instance. 
    cf bind-service <your_app_name> <vault_instance_name> -c '{" token_read_only: true "}'

    For more information on binding your application, see vault-service-get-started.html#task_0c97a8d8-4ca5-42c4-8a93-10e3657b283a.

  2. Optionally, you can create a new service key with custom parameters for your Vault service. The new service key contains a new token value.
    cf create-service-key <vault_instance_name> <service-key-name> -c '{" token_read_only: true "}'

    For more information on service key, see vault-service-get-started.html#task_3bbe9bb0-ff26-409e-99ee-b362f139e3ca.