https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud

Last synced: 4 months ago
JSON representation
Host: GitHub
URL: https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud
Owner: ibm-cloud-security
License: mpl-2.0
Created: 2020-11-09T16:42:00.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2023-08-30T18:06:02.000Z (almost 3 years ago)
Last Synced: 2025-04-30T18:37:44.242Z (about 1 year ago)
Language: Go
Size: 242 KB
Stars: 4
Watchers: 8
Forks: 3
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # Vault Plugin: IBM Cloud Secrets Backend

This is a standalone backend plugin for use with [HashiCorp Vault](https://www.github.com/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](#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:

    ```shell script

    $ 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:

    ```shell script

    $ vault write ibmcloud/config api_key= account_id= 

    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:

    ```shell script

    $ 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:

   ```shell script

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

    ```shell script

    $ 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/...`:

```shell script

$ 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-`

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: )` - An API key for a service ID or user with the permissions noted above.

* `account_id (string: )` - The ID of the account that contains the access groups and/or service ID used for

API key generation.

* `iam_endpoint (string: )` - 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

```json

{

  "api_key":    "Yl5OBiNlgpx...",

  "account_id": "abd85726cbd..."

}

```

### Sample Request

```shell script

$ 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

```shell script

$ curl \

    --header "X-Vault-Token: ..." \

    https://127.0.0.1:8200/v1/ibmcloud/config

```

### Sample Response

```json

{

  "data": {

    "api_key": "",

    "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

```shell script

$ curl \

    --header "X-Vault-Token: ..." \

    --request POST \

    https://127.0.0.1:8200/v1/ibmcloud/config/rotate-root

```

### Sample Response

```json

{

  "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

```shell script

$ 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: )` - 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:

```json

{

  "access_group_ids": ["AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47", "AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21"],

  "ttl": 60,

  "max_ttl": 600

}

```

Specifying a service ID:

```json

{

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

}

```

### Sample Request

```shell script

$ 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: )` - Name of the role.

### Sample Request

```shell script

$ curl \

    --header "X-Vault-Token: ..." \

    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role

```

### Sample Response

```json

{

  "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

 ```shell script

curl \

    --header "X-Vault-Token: ..." \

    --request LIST \

    https://127.0.0.1:8200/v1/ibmcloud/roles

```

### Sample Response

```json

{

  "data": {

    "keys": ["myRole", "anotherRole"]

  },

  "...": "..."

}

```

## Delete Role

Deletes the previously registered role.

| Method     | Path                                             |

|----------- |--------------------------------------------------|

| `DELETE`   |  `/ibmcloud/roles/:name`                          |

 

### Parameters

* `name (string: )` - Name of the role.

### Sample Request

```shell script

 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: )` - Name of the role.

### Sample Request

```shell script

$ curl \

    --header "X-Vault-Token: ..." \

    https://127.0.0.1:8200/v1/ibmcloud/creds/dev-role

```

### Sample Response

```json

{

  "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](https://golang.org/doc/code.html#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](https://github.com/hashicorp/vault#developing-vault)

for more information.

Next, clone this repository:

```sh

$ 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:

```sh

$ 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:

```sh

$ make

$ make dev

```

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

```sh

$ 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.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud

Awesome Lists containing this project

README
