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

Download a release of the plugin or build it from source. Follow the steps in Developing to build the plugin executable from source.
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
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
```

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.

(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.

Files

README.md

Latest commit

History

README.md

File metadata and controls

Vault Plugin: IBM Cloud Secrets Backend

Setup

Usage

Do Not Modify Vault-owned service ID or API keys

API documentation

Configure

Parameters

Sample Payload

Sample Request

Read Config

Sample Request

Sample Response

Rotate Root Credentials

Sample Request

Sample Response

Delete Config

Sample Request

Create Role

Parameters

Sample Payloads

Sample Request

Read Role

Parameters

Sample Request

Sample Response

List Roles

Sample Request

Sample Response

Delete Role

Parameters

Sample Request

Generate Secret (API key)

Parameters

Sample Request

Sample Response

Revoking/Renewing Secrets

Developing