Vault Plugin: IBM Cloud Secrets Backend

This is a standalone backend plugin for use with HashiCorp Vault. This plugin dynamically generates API keys for IBM Cloud service IDs. The service ID can either be pre-existing or the plugin can dynamically create it and assign it membership in a set of IBM Cloud access groups. This enables users to gain access to IBM Cloud resources without needing to create or manage dedicated service IDs.

Setup

1. Download a release of the plugin or build it from source. Follow the steps in Developing to build the plugin executable from source.

2. Register and enable the plugin

   Copy the executable into Vault's configured plugin folder. For example: cp bin/vault-plugin-secrets-ibmcloud $VAULT_INSTALL/plugins

   Register the plugin:

   $ export SHA256=$(shasum -a 256 "bin/vault-plugin-secrets-ibmcloud" | cut -d' ' -f1)
   $ vault plugin register -sha256=${SHA256} secret vault-plugin-secrets-ibmcloud

   Enable (mount) the plugin: vault secrets enable -plugin-name="vault-plugin-secrets-ibmcloud" -path="ibmcloud" plugin

3. Configure the secrets engine with account credentials

   These credentials will be used to manage the service IDs and access group membership. The API key provided needs to have the following permissions:

   • Editor on Access Groups Service
   • Operator on IAM Identity Service

   Configure the plugin:

   $ vault write ibmcloud/config api_key=<adminAPIKey> account_id=<accountID> 
   Success! Data written to: ibmcloud/config

4. Configure a role

   Roles determine the permissions that service ID credentials generated by Vault will have on IBM Cloud resources.

   To configure a role that uses an existing service ID:

   $ vault write ibmcloud/roles/myRole service_id=ServiceId-123456dbd-de02-4435-86ce-123456789abc
   Success! Data written to: ibmcloud/roles/myRole

   To configure a role that uses existing access groups:

   $ vault write ibmcloud/roles/myRole access_group_ids=AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47,AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21
   Success! Data written to: ibmcloud/roles/myRole

   There is a limit of 10 access groups per role.

5. (Optional) Rotate the configured API key

   The API key provided in the initial configuration can be rotated. This creates a new API key in IBM Cloud, updates the secret engine configuration, and deletes the currently configured API key from IBM Cloud.

   $ vault write -f ibmcloud/config/rotate-root
   
     Key          Value
     ---          -----
     apikey_id    ApiKey-2a3984a6-f855-4c69-893d-491d32228c17

Usage

After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.

To generate an API key, read from ibmcloud/creds/...:

$ vault read ibmcloud/creds/myRole
Key                Value
---                -----
lease_id           ibmcloud/creds/myRole/86aaorlchbzzU4108JjyV11u
lease_duration     768h
lease_renewable    true
api_key            EtOMPl18...

If the role was configured with a service ID, an API key is generated for the service ID and returned. If the role was configured with access groups, a service ID is created in the plugin's configured account, and added as a member to all of the role's access groups. An API key is generated for the service ID and returned.

When the lease expires or is revoked early the generated IBM Cloud resources are deleted. If the role used for key generation was configured with a service ID, the API key will be removed. If the role used for key generation was configured with access groups, the service ID is removed, thus removing its API key and its membership in the access groups.

Do Not Modify Vault-owned service ID or API keys

While Vault will create and manage service IDs, associated API keys, and access group membership, it is possible that an external user deletes or modifies these resources. These changes are difficult to detect, and it is best to prevent this type of modification.

Vault generated service IDs and API keys will have names in this format: vault-generated-<role name>

Communicate with your teams to not modify these resources.

API documentation

This documentation assumes the plugin method is mounted at the /ibmcloud path in Vault. Since it is possible to enable secret engines at any location, please update your API calls accordingly.

Configure

Configures the credentials and parameters required for the plugin to perform API calls to IBM Cloud IAM. These credentials will be used to manage the service IDs and the access group membership. The API key provided needs to have the following permissions:

• Editor on Access Groups Service
• Operator on IAM Identity Service

Configures the secret engine must done before API keys can be generated.

Method	Path
POST	/ibmcloud/config

Parameters

• api_key (string: <required>) - An API key for a service ID or user with the permissions noted above.
• account_id (string: <required>) - The ID of the account that contains the access groups and/or service ID used for API key generation.
• iam_endpoint (string: <optional>) - The custom or private IAM endpoint. For example https://private.iam.cloud.ibm.com. If unspecified the public endpoint, https://iam.cloud.ibm.com, is used.

Sample Payload

{
  "api_key":    "Yl5OBiNlgpx...",
  "account_id": "abd85726cbd..."
}

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/ibmcloud/config

Read Config

Returns the configuration, if any. Credentials are redacted in the output.

Method	Path
GET	/ibmcloud/config

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/ibmcloud/config

Sample Response

{
  "data": {
    "api_key": "<redacted>",
    "account_id": "abd85726cbd...",
    "iam_endpoint": "https://iam.cloud.ibm.com"
  },
  "...": "..."

}

Rotate Root Credentials

Rotates the IBM Cloud API key used by Vault for this mount. A new key will be generated for same user or service ID and account as the existing API key. The configuration is updated and then the old API key is deleted.

The ID of the new API key is returned in the response.

Method	Path
POST	/ibmcloud/config/rotate-root

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    https://127.0.0.1:8200/v1/ibmcloud/config/rotate-root

Sample Response

{
  "data": {
    "api_key_id": "ApiKey-0abbbbbb-21cc-4dcc-a9cc-b59bc15c7aa1"
  },
  "...": "..."
}

Delete Config

Deletes the previously configured configuration and clears the configured credentials in the plugin.

Method	Path
DELETE	/ibmcloud/config

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/ibmcloud/config

Create Role

Registers a role in the secret engine. Roles determine the permissions that service ID credentials generated by Vault will have on IBM Cloud resources. Roles are configured with either an existing service ID or one or more existing access groups.

• There is a limit of 10 access groups per role.
• The public access group AccessGroupId-PublicAccess is not allowed.

Method	Path
POST	/ibmcloud/roles/:name

Parameters

• name (string: <required>) - Name of the role.

One of the following must be specified:

• service_id (string: "") - A service ID that API keys will be generated for.
• access_group_ids (array: []) - The list of IBM Cloud IAM access group ids that a generated service ID will become a member of.

Optional parameters:

• ttl (integer: 0 or string: "") - Default lease for generated credentials in seconds. If not set or set to 0, will use system default.
• max_ttl (integer: 0 or string: "") - Maximum lifetime of generated credentials in seconds. If not set or set to 0, will use system default.

Sample Payloads

Specifying access groups:

{
  "access_group_ids": ["AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47", "AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21"],
  "ttl": 60,
  "max_ttl": 600
}

Specifying a service ID:

{
  "service_id": "ServiceId-068bda08-c891-4a7f-82cf-3b2111ae3c43"
}

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role

Read Role

Returns the previously registered role configuration.

Method	Path
GET	/ibmcloud/roles/:name

Parameters

• name (string: <required>) - Name of the role.

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role

Sample Response

{
  "data": {
    "access_group_ids": [
      "AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47",
      "AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21"
    ],
    "ttl": 60,
    "max_ttl": 600,
    "service_id": ""
  },
  "...": "..."

}

List Roles

Lists all the roles that are registered with the plugin.

Method	Path
LIST	/ibmcloud/roles

Sample Request

curl \
   --header "X-Vault-Token: ..." \
   --request LIST \
   https://127.0.0.1:8200/v1/ibmcloud/roles

Sample Response

{
  "data": {
    "keys": ["myRole", "anotherRole"]
  },
  "...": "..."

}

Delete Role

Deletes the previously registered role.

Method	Path
DELETE	/ibmcloud/roles/:name

Parameters

• name (string: <required>) - Name of the role.

Sample Request

 curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role

Generate Secret (API key)

Method	Path
GET	/ibmcloud/creds/:name

Generates an API key for a service ID. If the named role was configured with a list of access groups, rather than a service ID, a service ID will created, added as a member to the groups, and an API key generated for the service ID.

The API keys are renewable and have a TTL/max TLL as defined by either the role or the system default if the TTL values were not set on the role.

Parameters

• name (string: <required>) - Name of the role.

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/ibmcloud/creds/dev-role

Sample Response

{
  "request_id": "0b99eaa2-cc97-9cf9-01ce-38888efdecf5",
  "lease_id": "ibmcloud/creds/dev-role/3sS1dggbxzwsxw1CrratxtFHTF9u",
  "lease_duration": 300,
  "renewable": true,
  "data": {
    "api_key": "fB1MPLzVKWd..."
  },
  "...": "..."

}

Revoking/Renewing Secrets

See docs on how to renew and revoke leases.

Developing

For local dev first make sure Go is properly installed, including setting up a GOPATH. The version of Go that is installed should match the level required by the version of Vault that will be used. See Vault's requirements for more information.

Next, clone this repository:

$ git clone https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud
$ cd vault-plugin-secrets-ibmcloud

You can then download any required build tools by bootstrapping your environment:

$ make bootstrap

To compile a development version of this plugin, run make or make dev. This will put the plugin binary in the bin and $GOPATH/bin folders. dev mode will only generate the binary for your platform and is faster:

$ make
$ make dev

For local development, use Vault's "dev" mode for fast setup:

$ vault server -dev -config vault.hcl

Where vault.hcl configures the plugin directory like this:

plugin_directory = "./plugins"

Follow the setup instructions to copy, register, and enable the plugin.