{"id":19773177,"url":"https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud","last_synced_at":"2026-03-02T07:33:35.099Z","repository":{"id":40563297,"uuid":"311402161","full_name":"ibm-cloud-security/vault-plugin-secrets-ibmcloud","owner":"ibm-cloud-security","description":null,"archived":false,"fork":false,"pushed_at":"2023-08-30T18:06:02.000Z","size":248,"stargazers_count":4,"open_issues_count":2,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-30T18:37:44.242Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibm-cloud-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-09T16:42:00.000Z","updated_at":"2022-04-04T16:44:29.000Z","dependencies_parsed_at":"2024-06-19T09:56:30.933Z","dependency_job_id":"8c985ab8-94cb-4828-857b-23910cab4696","html_url":"https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud","commit_stats":{"total_commits":23,"total_committers":3,"mean_commits":7.666666666666667,"dds":0.08695652173913049,"last_synced_commit":"12a2456c359020caefdbb327d27adde569573829"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ibm-cloud-security/vault-plugin-secrets-ibmcloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fvault-plugin-secrets-ibmcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fvault-plugin-secrets-ibmcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fvault-plugin-secrets-ibmcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fvault-plugin-secrets-ibmcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibm-cloud-security","download_url":"https://codeload.github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibm-cloud-security%2Fvault-plugin-secrets-ibmcloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:08:53.450Z","updated_at":"2026-03-02T07:33:35.085Z","avatar_url":"https://github.com/ibm-cloud-security.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vault Plugin: IBM Cloud Secrets Backend\n\nThis is a standalone backend plugin for use with [HashiCorp Vault](https://www.github.com/hashicorp/vault).\nThis plugin dynamically generates API keys for IBM Cloud service IDs. The service ID can either be pre-existing or\nthe plugin can dynamically create it and assign it membership in a set of IBM Cloud access groups. This enables\nusers to gain access to IBM Cloud resources without needing to create or manage dedicated service IDs. \n\n## Setup\n\n1. Download a release of the plugin or build it from source. Follow the steps in [Developing](#Developing) to build\nthe plugin executable from source.\n\n2. Register and enable the plugin\n\n    Copy the executable into Vault's configured plugin folder. For example: `cp bin/vault-plugin-secrets-ibmcloud $VAULT_INSTALL/plugins`\n\n    Register the plugin:\n    ```shell script\n    $ export SHA256=$(shasum -a 256 \"bin/vault-plugin-secrets-ibmcloud\" | cut -d' ' -f1)\n    $ vault plugin register -sha256=${SHA256} secret vault-plugin-secrets-ibmcloud\n    ```\n\n    Enable (mount) the plugin: `vault secrets enable -plugin-name=\"vault-plugin-secrets-ibmcloud\" -path=\"ibmcloud\" plugin`\n\n3. Configure the secrets engine with account credentials\n\n    These credentials will be used to manage the service IDs and access group membership. The API key provided\n    needs to have the following permissions:\n    \n    * `Editor` on `Access Groups Service`\n    * `Operator` on `IAM Identity Service` \n    \n    Configure the plugin:\n    ```shell script\n    $ vault write ibmcloud/config api_key=\u003cadminAPIKey\u003e account_id=\u003caccountID\u003e \n    Success! Data written to: ibmcloud/config\n    ```\n   \n4. Configure a role\n\n    Roles determine the permissions that service ID credentials generated by Vault will have on IBM Cloud resources. \n\n    To configure a role that uses an existing service ID:\n    ```shell script\n    $ vault write ibmcloud/roles/myRole service_id=ServiceId-123456dbd-de02-4435-86ce-123456789abc\n    Success! Data written to: ibmcloud/roles/myRole\n    ```\n   \n   To configure a role that uses existing access groups:\n   ```shell script\n   $ vault write ibmcloud/roles/myRole access_group_ids=AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47,AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21\n   Success! Data written to: ibmcloud/roles/myRole\n   ```\n   **There is a limit of 10 access groups per role.**\n\n5. (Optional) Rotate the configured API key\n\n    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,\n    and deletes the currently configured API key from IBM Cloud.\n\n    ```shell script\n    $ vault write -f ibmcloud/config/rotate-root\n\n      Key          Value\n      ---          -----\n      apikey_id    ApiKey-2a3984a6-f855-4c69-893d-491d32228c17\n    ```\n\n## Usage\nAfter the secrets engine is configured and a user/machine has a Vault token with the proper permission,\nit can generate credentials.\n\nTo generate an API key, read from `ibmcloud/creds/...`:\n```shell script\n$ vault read ibmcloud/creds/myRole\nKey                Value\n---                -----\nlease_id           ibmcloud/creds/myRole/86aaorlchbzzU4108JjyV11u\nlease_duration     768h\nlease_renewable    true\napi_key            EtOMPl18...\n```\n\nIf the role was configured with a service ID, an API key is generated for the service ID and returned.\nIf the role was configured with access groups, a service ID is created in the plugin's configured account, and added\nas a member to all of the role's access groups. An API key is generated for the service ID and returned.\n\nWhen the lease expires or is revoked early the generated IBM Cloud resources are deleted. If the role used for key\ngeneration was configured with a service ID, the API key will be removed. If the role used for key generation was\nconfigured with access groups, the service ID is removed, thus removing its API key and its membership in the\naccess groups. \n\n### Do Not Modify Vault-owned service ID or API keys\nWhile Vault will create and manage service IDs, associated API keys, and access group membership, it is possible that\nan external user deletes or modifies these resources. These changes are difficult to detect, and it is best\nto prevent this type of modification.\n    \nVault generated service IDs and API keys will have names in this format:\n`vault-generated-\u003crole name\u003e`\n\nCommunicate with your teams to not modify these resources.\n\n# API documentation\nThis documentation assumes the plugin method is mounted at the `/ibmcloud` path in Vault. Since it is possible to\nenable secret engines at any location, please update your API calls accordingly.\n\n## Configure\n\nConfigures the credentials and parameters required for the plugin to perform API calls to IBM Cloud IAM. These\ncredentials will be used to manage the service IDs and the access group membership. The API key provided needs\nto have the following permissions:\n\n* `Editor` on `Access Groups Service`\n* `Operator` on `IAM Identity Service` \n\nConfigures the secret engine must done before API keys can be generated.\n\n\n| Method   | Path |\n|----------|-------------------------------------------------|\n| `POST`   |  `/ibmcloud/config`                             |\n\n\n### Parameters\n* `api_key (string: \u003crequired\u003e)` - An API key for a service ID or user with the permissions noted above.\n* `account_id (string: \u003crequired\u003e)` - The ID of the account that contains the access groups and/or service ID used for\nAPI key generation.\n* `iam_endpoint (string: \u003coptional\u003e)` - The custom or private IAM endpoint. For example `https://private.iam.cloud.ibm.com`.\nIf unspecified the public endpoint, `https://iam.cloud.ibm.com`, is used.\n\n### Sample Payload\n\n```json\n{\n  \"api_key\":    \"Yl5OBiNlgpx...\",\n  \"account_id\": \"abd85726cbd...\"\n}\n```\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request POST \\\n    --data @payload.json \\\n    https://127.0.0.1:8200/v1/ibmcloud/config\n```\n\n## Read Config\nReturns the configuration, if any. Credentials are redacted in the output.\n\n| Method   | Path |\n|----------|--------------------------------------------------|\n| `GET`    |  `/ibmcloud/config`                              |\n\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    https://127.0.0.1:8200/v1/ibmcloud/config\n```\n\n### Sample Response\n```json\n{\n  \"data\": {\n    \"api_key\": \"\u003credacted\u003e\",\n    \"account_id\": \"abd85726cbd...\",\n    \"iam_endpoint\": \"https://iam.cloud.ibm.com\"\n  },\n  \"...\": \"...\"\n\n}\n```\n\n## Rotate Root Credentials\n\nRotates the IBM Cloud API key used by Vault for this mount. A new key will be generated\nfor same user or service ID and account as the existing API key. The configuration is updated\nand then the old API key is deleted.\n\nThe ID of the new API key is returned in the response.\n\n\n| Method   | Path |\n|----------|-------------------------------------------------|\n| `POST`   |  `/ibmcloud/config/rotate-root`                 |\n\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request POST \\\n    https://127.0.0.1:8200/v1/ibmcloud/config/rotate-root\n```\n\n### Sample Response\n```json\n{\n  \"data\": {\n    \"api_key_id\": \"ApiKey-0abbbbbb-21cc-4dcc-a9cc-b59bc15c7aa1\"\n  },\n  \"...\": \"...\"\n}\n```\n\n## Delete Config\nDeletes the previously configured configuration and clears the configured credentials in the plugin.\n\n| Method     | Path |\n|----------- |--------------------------------------------------|\n| `DELETE`   |  `/ibmcloud/config`                              |\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request DELETE \\\n    https://127.0.0.1:8200/v1/ibmcloud/config\n```\n\n## Create Role\nRegisters a role in the secret engine. Roles determine the permissions that service ID credentials generated\nby Vault will have on IBM Cloud resources. Roles are configured with either an existing service ID or one or more\nexisting access groups. \n\n* There is a limit of 10 access groups per role.\n* The public access group `AccessGroupId-PublicAccess` is not allowed.\n\n| Method     | Path                                             |\n|----------- |--------------------------------------------------|\n| `POST`     |  `/ibmcloud/roles/:name`                          |\n\n\n### Parameters\n\n* `name (string: \u003crequired\u003e)` - Name of the role.\n\nOne of the following must be specified:\n* `service_id (string: \"\")` - A service ID that API keys will be generated for.\n* `access_group_ids (array: [])` - The list of IBM Cloud IAM access group ids that a generated service ID will become a member of.\n\nOptional parameters:\n* `ttl (integer: 0 or string: \"\") `- Default lease for generated credentials in seconds. If not set or set to 0, will use system default.\n* `max_ttl (integer: 0 or string: \"\")` - Maximum lifetime of generated credentials in seconds. If not set or set to 0, will use system default.\n\n\n### Sample Payloads\nSpecifying access groups:\n```json\n{\n  \"access_group_ids\": [\"AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47\", \"AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21\"],\n  \"ttl\": 60,\n  \"max_ttl\": 600\n}\n```\n\nSpecifying a service ID:\n```json\n{\n  \"service_id\": \"ServiceId-068bda08-c891-4a7f-82cf-3b2111ae3c43\"\n}\n```\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request POST \\\n    --data @payload.json \\\n    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role\n```\n## Read Role\nReturns the previously registered role configuration.\n\n| Method     | Path                                             |\n|----------- |--------------------------------------------------|\n| `GET`      |  `/ibmcloud/roles/:name`                          |\n \n### Parameters\n\n* `name (string: \u003crequired\u003e)` - Name of the role.\n\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role\n```\n\n### Sample Response\n```json\n{\n  \"data\": {\n    \"access_group_ids\": [\n      \"AccessGroupId-43f12338-fc2c-41cd-b4f9-14eff0cbeb47\",\n      \"AccessGroupId-43f12111-fc2c-41cd-b4f9-14eff0cbeb21\"\n    ],\n    \"ttl\": 60,\n    \"max_ttl\": 600,\n    \"service_id\": \"\"\n  },\n  \"...\": \"...\"\n\n}\n```\n\n## List Roles\nLists all the roles that are registered with the plugin.\n\n| Method     | Path                                             |\n|----------- |--------------------------------------------------|\n| `LIST`     |  `/ibmcloud/roles`                                |\n \n### Sample Request\n ```shell script\ncurl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request LIST \\\n    https://127.0.0.1:8200/v1/ibmcloud/roles\n```\n\n### Sample Response\n\n```json\n{\n  \"data\": {\n    \"keys\": [\"myRole\", \"anotherRole\"]\n  },\n  \"...\": \"...\"\n\n}\n```\n\n## Delete Role\nDeletes the previously registered role.\n\n| Method     | Path                                             |\n|----------- |--------------------------------------------------|\n| `DELETE`   |  `/ibmcloud/roles/:name`                          |\n \n### Parameters\n* `name (string: \u003crequired\u003e)` - Name of the role.\n\n### Sample Request\n```shell script\n curl \\\n    --header \"X-Vault-Token: ...\" \\\n    --request DELETE \\\n    https://127.0.0.1:8200/v1/ibmcloud/roles/dev-role\n```\n\n## Generate Secret (API key)\n\n| Method         | Path                                             |\n|----------------|--------------------------------------------------|\n| `GET`          |  `/ibmcloud/creds/:name`                         |\n\nGenerates an API key for a service ID. If the named role was configured with a list of access groups, rather than\na service ID, a service ID will created, added as a member to the groups, and an API key generated for\nthe service ID.\n\nThe API keys are renewable and have a TTL/max TLL as defined by either the role or the system default if\nthe TTL values were not set on the role. \n\n \n### Parameters\n\n* `name (string: \u003crequired\u003e)` - Name of the role.\n\n\n### Sample Request\n```shell script\n$ curl \\\n    --header \"X-Vault-Token: ...\" \\\n    https://127.0.0.1:8200/v1/ibmcloud/creds/dev-role\n```\n\n### Sample Response\n```json\n{\n  \"request_id\": \"0b99eaa2-cc97-9cf9-01ce-38888efdecf5\",\n  \"lease_id\": \"ibmcloud/creds/dev-role/3sS1dggbxzwsxw1CrratxtFHTF9u\",\n  \"lease_duration\": 300,\n  \"renewable\": true,\n  \"data\": {\n    \"api_key\": \"fB1MPLzVKWd...\"\n  },\n  \"...\": \"...\"\n\n}\n```\n\n## Revoking/Renewing Secrets\nSee docs on how to renew and revoke leases.\n\n## Developing\n\nFor local dev first make sure Go is properly installed, including\nsetting up a [GOPATH](https://golang.org/doc/code.html#GOPATH). The version\nof Go that is installed should match the level required by the version of Vault\nthat will be used. See [Vault's requirements](https://github.com/hashicorp/vault#developing-vault)\nfor more information.\n\nNext, clone this repository:\n\n```sh\n$ git clone https://github.com/ibm-cloud-security/vault-plugin-secrets-ibmcloud\n$ cd vault-plugin-secrets-ibmcloud\n```\n\nYou can then download any required build tools by bootstrapping your\nenvironment:\n\n```sh\n$ make bootstrap\n```\n\nTo compile a development version of this plugin, run `make` or `make dev`.\nThis will put the plugin binary in the `bin` and `$GOPATH/bin` folders. `dev`\nmode will only generate the binary for your platform and is faster:\n\n```sh\n$ make\n$ make dev\n```\n\nFor local development, use Vault's \"dev\" mode for fast setup:\n\n```sh\n$ vault server -dev -config vault.hcl\n```\n\nWhere vault.hcl configures the plugin directory like this:\n```\nplugin_directory = \"./plugins\"\n```\n\nFollow the setup instructions to copy, register, and enable the plugin.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud-security%2Fvault-plugin-secrets-ibmcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm-cloud-security%2Fvault-plugin-secrets-ibmcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud-security%2Fvault-plugin-secrets-ibmcloud/lists"}