secret-groups.md

copyright	lastupdated	keywords	subcollection
years 2020, 2024	2024-10-10	secret groups, assign secret access, iam roles, secrets policies, organize secrets	secrets-manager

{:codeblock: .codeblock} {:screen: .screen} {:download: .download} {:external: target="_blank" .external} {:faq: data-hd-content-type='faq'} {:gif: data-image-type='gif'} {:important: .important} {:note: .note} {:pre: .pre} {:tip: .tip} {:preview: .preview} {:deprecated: .deprecated} {:beta: .beta} {:term: .term} {:shortdesc: .shortdesc} {:script: data-hd-video='script'} {:support: data-reuse='support'} {:table: .aria-labeledby="caption"} {:troubleshoot: data-hd-content-type='troubleshoot'} {:help: data-hd-content-type='help'} {:tsCauses: .tsCauses} {:tsResolve: .tsResolve} {:tsSymptoms: .tsSymptoms} {:video: .video} {:step: data-tutorial-type='step'} {:tutorial: data-hd-content-type='tutorial'} {:api: .ph data-hd-interface='api'} {:cli: .ph data-hd-interface='cli'} {:ui: .ph data-hd-interface='ui'} {:terraform: .ph data-hd-interface="terraform"} {:curl: .ph data-hd-programlang='curl'} {:java: .ph data-hd-programlang='java'} {:ruby: .ph data-hd-programlang='ruby'} {:c#: .ph data-hd-programlang='c#'} {:objectc: .ph data-hd-programlang='Objective C'} {:python: .ph data-hd-programlang='python'} {:javascript: .ph data-hd-programlang='javascript'} {:php: .ph data-hd-programlang='PHP'} {:swift: .ph data-hd-programlang='swift'} {:curl: .ph data-hd-programlang='curl'} {:dotnet-standard: .ph data-hd-programlang='dotnet-standard'} {:go: .ph data-hd-programlang='go'} {:unity: .ph data-hd-programlang='unity'} {:release-note: data-hd-content-type='release-note'}

Organizing your secrets

{: #secret-groups}

When you work with {{site.data.keyword.secrets-manager_full}}, you can create groups to organize your secrets and control who on your team has access to them. Then, if you don't need them anymore, you can delete the groups. {: shortdesc}

Similar to the way that resource groups{: term} help to ensure correct policy enforcement at the platform level, you can create secret groups at the instance level to organize secrets.

{: caption="Assigning access to secret groups" caption-side="bottom"}

As shown in the previous image, users with Reader access to a secret group can see that the group exists and understand which secrets are assigned to it. Users with Writer access can view and edit the secret group and secrets themselves. By design, the default secret group inherits all of the same permissions that are set for the instance.

You can choose to group your secrets by phase of development, specific to the type of roles that people on your team have, or in any way that might help you. Each secret can be mapped to one group only and the mapping occurs at the time of secret creation.

To learn about the suggested guidelines for using secret groups, check out Best practices for organizing secrets and assigning access. {: tip}

Before you begin

{: #before-secret-groups}

Before you begin, be sure that you have the required level of access. To create and manage secret groups, you need the Manager service role.

Creating secret groups

{: #create-secret-groups}

You can create secret groups by using the {{site.data.keyword.secrets-manager_short}} console or the API.

Creating secret groups in the UI

{: #create-group-ui} {: ui}

You can create secret groups by using the console. You can also create a secret group during the process of adding or creating a secret.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of {{site.data.keyword.secrets-manager_short}}.
3. In the navigation, click Secret groups > Create.
4. Add a name and description to easily identify your group.
5. Click Create.
6. Optional: Assign your secret group an IAM policy.

Creating secret groups with the API

{: #create-group-api} {: api}

You can create secret groups by using the {{site.data.keyword.secrets-manager_short}} API.

The following example request creates a secret group. When you call the API, replace the ID variables and IAM token with the values that are specific to your {{site.data.keyword.secrets-manager_short}} instance. {: curl}

curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
    "name":"my-secret-group",
    "description":"Extended description for this group."
    }' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secret_groups"

{: codeblock} {: curl}

Creating secret groups with Terraform

{: #create-group-terraform} {: terraform}

You can create secret groups by using Terraform for {{site.data.keyword.secrets-manager_short}}.

The following example request creates a secret group.

resource "ibm_sm_secret_group" "sm_secret_group_test" {
  instance_id = local.instance_id
  region = local.region
  name = "secret_group_test"
  description = "example secret group"
}

{: codeblock}

Deleting secret groups

{: #delete-groups}

If you no longer need to use a group, you can delete it by using the console or the API.

To delete a secret group, it must be empty. If you need to remove a secret group that contains secrets, you must first delete the secrets that are part of the group. {: note}

Deleting secret groups in the UI

{: #delete-group-ui} {: ui}

You can delete secret groups by using the console.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of {{site.data.keyword.secrets-manager_short}}.
3. In the navigation, click Secret groups.
4. In the row for the secret group that you want to delete, click the Actions icon .
5. Click Delete group.
6. Click Delete.

Deleting secret groups with the API

{: #delete-group-api} {: api}

You can delete secret groups by using the {{site.data.keyword.secrets-manager_short}} API.

The following example request deletes a secret group. When you call the API, replace the ID variables and IAM token with the values that are specific to your {{site.data.keyword.secrets-manager_short}} instance. {: curl}

curl -X DELETE 
  --H "Authorization: Bearer {iam_token}" \ 
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secret_groups/{id}"

{: codeblock} {: curl}

Next steps

{: #secret-groups-next-steps}

Already using secret groups? To learn more about assigning access and organizing your secrets, check out the following resources.

• Assigning access to a secret group
• Best practices for organizing secrets and assigning access