vania-janet/multiturn-rag-retrieval-data huggingface dataset:
To view the credential, the user must have the IAM level access action resource-controller.credential.retrieve_all. This action is given with the Administrator role, and overrides any credential level access enabling the user to view the credential.







 Viewing a credential by using the API 

After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential including the API key value. The access of the user must be equal to or greater than that of the service credential. For example, if the credential has the IAM service role Writer, then the user trying to view the credential must have the IAM service role Writer or Manager for that particular service assigned.

To get a list of all of the resource keys, call the [Resource Controller API](https://cloud.ibm.com/apidocs/resource-controller/resource-controllerlist-resource-keys) as shown in the following example:



* Curl
* Java
* Python
* Go
* Node



curl -X GET https://resource-controller.cloud.ibm.com/v2/resource_keys -H 'Authorization: Bearer <IAM_TOKEN>'

ListResourceKeysOptions listResourceKeysOptions = new ListResourceKeysOptions.Builder()
.name(keyName)
.build();

Response<ResourceKeysList> response = service.listResourceKeys(listResourceKeysOptions).execute();
ResourceKeysList resourceKeysList = response.getResult();

System.out.printf("listResourceKeys() response:n%sn", resourceKeysList.toString());

resource_keys_list = resource_controller_service.list_resource_keys(
name=key_name
).get_result()

print('nlist_resource_keys() response:n',
"description": "My test IAM credential that is assigned to a secret group.",
"id": "091ca93f-5c99-4078-9d7e-4801143030fd",
"labels": [
"test",
"us-south"
],
"last_update_date": "2020-10-09T17:13:47Z",
"name": "test-iam-credential-in-group",
"secret_group_id": "9ab2250f-a369-4e07-ade7-d417d63ad587",
"secret_type": "IAM_CREDENTIALS",
"state": 1,
"state_description": "Active",
"ttl": 3600
},
"warnings": null
}







 Update the metadata of a role 

Use the following commands to view details about a registered role or secret, such as its name and history.

Update the details of a role in the default secret group.

vault write [-format=FORMAT] ibmcloud/SECRET_TYPE/roles/ROLE_ID/metadata [name="ROLE_NAME"] [access_groups=ACCESS_GROUP_ID,ACCESS_GROUP_ID] [ttl=LEASE_DURATION] [description="DESCRIPTION"] [labels=LABEL,LABEL]

Update the details of a role that is assigned to a secret group.

vault write [-format=FORMAT] ibmcloud/SECRET_TYPE/roles/groups/SECRET_GROUP_ID/ROLE_ID/metadata [name="ROLE_NAME"] [access_groups=ACCESS_GROUP_ID,ACCESS_GROUP_ID] [ttl=LEASE_DURATION] [description="DESCRIPTION"] [labels=LABEL,LABEL]



 Prerequisites 

You need the [Writer service role](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam) to update the metadata of a secret.





 Command options 

SECRET_TYPE
You can configure a secrets engine programmatically by using Terraform for Secrets Manager.

The following example shows a configuration that you can use to configure the IAM credentials engine.

resource "ibm_sm_iam_credentials_configuration" "iam_credentials_configuration" {
instance_id = local.instance_id
region = local.region
name = "iam_credentials_config"
api_key = var.ibmcloud_api_key
}





 Next steps 

Now you can use Secrets Manager to dynamically generate IAM credentials for your apps. In the Secrets Manager UI, click Secrets > Add > IAM credentials to start creating secrets.



* [Creating IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials)



The metadata update operation uses a secret ID as part of the path.
By default, the service ID and API key are single-use, ephemeral values that are generated and deleted each time that an IAM credentials secret is read or accessed.

If you'd like to continue to use those credentials through the end of the lease of your secret, you can set Reuse IAM credentials until lease expires to On. When you enable this option, your secret retains its current service ID, and API key values and reuses them on each read while the secret remains valid. After the secret reaches the end of its lease, the credentials are revoked automatically.

If the reuse IAM credentials option is set to Off, manual rotation for the secret isn't supported. For more information, see [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation).





 Using an existing service ID in your account 

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID. Or, if you prefer to generate both a service ID and an API key, you can assign access by choosing an access group.

In the Assign access step of the Create IAM credentials wizard, choose a scope of access for your credentials.



1. To use an existing service ID, select an ID from the list.

Choose this option when you need Secrets Manager to generate and manage only an API key for your IAM credentials secret, and not the service ID itself. The API key inherits the access policy of the service ID that you select from your account. Only the service IDs that you have access to are displayed.
2. To generate both a new service ID and API key for the secret, select an access group.

By selecting an access group from your IBM Cloud account, you determine the scope of access to assign to the service ID and the API key. The API key is dynamically generated and associated with your new IAM credential. This step ensures that your IAM credentials are scoped with the preferred level of permissions in your IBM Cloud account. You can assign up to 10 access groups.
* YOUR_CLIENT_SECRET The client secret that is used for registering Infrastructure management as an OIDC client with IAM.
Note: The YOUR_CLIENT_ID and YOUR_CLIENT_SECRET values are generated when you register Infrastructure Management as an OIDC client. The IM_ADMIN_LDAP_USER must be a member of the LDAP group with the role EvmRole-super_administrator in Infrastructure management.





1. Browse to Workloads > Secrets
2. Click Create and select From YAML from the drop-down.
3. Update the YAML (You can use this example imconnectionsecret.yaml).

apiVersion: v1
kind: Secret
metadata:
  name: imconnectionsecret
  namespace: management-infrastructure-management
type: Opaque
stringData:
  oauth_username: <IM_ADMIN_LDAP_USER>
  oauth_password: <IM_ADMIN_LDAP_PASS>
  cpconsole: <YOUR_CP4MCM_HOST>
  clientid: <YOUR_CLIENT_ID>
  clientsecret: <YOUR_CLIENT_SECRET>
4. Click Create.
5. Browse to Operators > Installed Operators.
6. Click IBM Management Infrastructure for virtual machines.
7. Click Create instance for the Connection kind under Provided APIs.
8. Update the YAML (You can use this example imconnection.yaml)

apiVersion: infra.management.ibm.com/v1alpha1
kind: Connection
metadata:
  labels:
    app.kubernetes.io/instance: connection-1
    app.kubernetes.io/managed-by: connections.infra.management.ibm.com
    app.kubernetes.io/name: example-connection
  name: imconnection
  namespace: management-infrastructure-management
spec:
  cfHost: <YOUR_IM_APPLIANCE_HOSTNAME>
  secrets:
    accessToken:
      secretKeyRef:
Configure secrets engines for your instance so that you can work with specific types of secrets.



 ibmcloud secrets-manager config-update 

Set the configuration for the specified secret type.

Use this method to configure the IAM credentials (iam_credentials) engine for your service instance. Looking to order or generate certificates? To configure the public certificates (public_cert) or private certificates (private_cert) engines, use the Add a configuration method.

ibmcloud secrets-manager config-update --secret-type SECRET-TYPE --engine-config ENGINE-CONFIG



 Command options 

--secret-type (string)
: The secret type. Required.

Allowable values are: iam_credentials.

--engine-config ([EngineConfig](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secrets-manager-cli-v1cli-engine-config-example-schema-v1))
: Properties to update for a secrets engine. Required.





 Examples 

ibmcloud secrets-manager config-update --secret-type=iam_credentials --engine-config='{"api_key": "API_KEY"}'







 ibmcloud secrets-manager config 

Get the configuration that is associated with the specified secret type.

ibmcloud secrets-manager config --secret-type SECRET-TYPE



 Command options 

--secret-type (string)
: The secret type. Required.

Allowable values are: iam_credentials, public_cert, private_cert.





 Examples 

ibmcloud secrets-manager config --secret-type=iam_credentials







 ibmcloud secrets-manager config-element-create 

Add a configuration element to the specified secret type.

Use this method to define the configurations that are required to enable the public certificates (public_cert) and private certificates (private_cert) engines.

You can add multiple configurations for your instance as follows:
{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/creds/groups/{group_id}/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get key-value secrets. [Learn more](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-vault-manage-kv&interface=apioverview-kv).

curl -L -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/secrets/{secret_id}' -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get key-value secrets in an existing secret group.

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/secrets/groups/{group_id}/{secret_id}' -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get user credentials.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/username_password/secrets/{secret_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get user credentials in an existing secret group.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/username_password/secrets/{secret_id}/groups/{group_id}" -H 'Accept: application/json' -H 'X-Vault-Token: {Vault-Token}'

Get an imported certificate.

curl -X GET "https://{instance_id}.
If you'd like to continue to use those credentials through the end of the lease of your secret, you can set Reuse IAM credentials until lease expires to On. When you enable this option, your secret retains its current service ID, and API key values and reuses them on each read while the secret remains valid. After the secret reaches the end of its lease, the credentials are revoked automatically.

If the reuse IAM credentials option is set to Off, manual rotation for the secret isn't supported. For more information, see [Manually rotating secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-manual-rotation).





 Using an existing service ID in your account 

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID. Or, if you prefer to generate both a service ID and an API key, you can assign access by choosing an access group.

In the Assign access step of the Create IAM credentials wizard, choose a scope of access for your credentials.



1. To use an existing service ID, select an ID from the list.

Choose this option when you need Secrets Manager to generate and manage only an API key for your IAM credentials secret, and not the service ID itself. The API key inherits the access policy of the service ID that you select from your account. Only the service IDs that you have access to are displayed.
2. To generate both a new service ID and API key for the secret, select an access group.

By selecting an access group from your IBM Cloud account, you determine the scope of access to assign to the service ID and the API key. The API key is dynamically generated and associated with your new IAM credential. This step ensures that your IAM credentials are scoped with the preferred level of permissions in your IBM Cloud account. You can assign up to 10 access groups.



If you used an existing service ID, the API key that was generated by Secrets Manager is automatically locked.
"iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]",
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
"iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]",
"password": "8fb6a16b48903e87b769e7f4968521e85c2394ed8f0e69b2769e56dcb27d2e76",
"port": 443,
"url": "https://<username>:<password>@76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
"username": "apikey-v2-58B528DF5397465BB6673E1B79482A8C"
}

The service credentials include the following fields:



Table 1. Service credential fields

 Field Purpose 

 username The username that is required for applications to access the service instance. 
 password The legacy credentials password that is required for applications to access the service instance. This field displays only if the Use both legacy credentials and IAM option is chosen. 
 host The hostname that is used by applications to locate the service instance. This field displays only if the Use both legacy credentials and IAM option is chosen. 
 port The HTTPS port number for accessing the service instance on the host. It's 443 as only HTTPS access is allowed by IBM Cloudant. This field displays only if the Use both legacy credentials and IAM option is chosen. 
 url The HTTPS URL to access the IBM Cloudant instance. If the Use both legacy credentials and IAM option is chosen, it also includes the embedded legacy username and password. 
 apikey The IAM API key.
* [Service ID creator service role](https://cloud.ibm.com/docs/account?topic=account-account-servicesidentity-service-account-management) on the IAM Identity Service.



The service ID creator service role is only required when you disable the creation of service IDs in your IAM settings. If the account in which you want to generate IAM credentials allows access to only specific IP addresses, you must also update the IP address settings in the account to allow incoming requests from Secrets Manager. For more information, see [Managing access with context-based restrictions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-control-cbr).





 Setting up the IAM credentials engine in the UI 

You can add an IAM credentials engine configuration by using the Secrets Manager UI. To configure your instance to start creating IAM credentials, complete the following steps.



1. In the console, click the Menu icon ![Menu icon](https://cloud.ibm.com/docs-content/v1/content/991f60ddbe3ab0a9aa69481a07a0a73b359fa329/icons/icon_hamburger.svg)> Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets engines page, click the IAM credentials tab.
4. Click Configure.
5. Enter an API key that has access to create and manage other API keys in your account.

The service ID that is associated with your API key must have Editor platform access on the IAM Access Groups Service, Service ID creator access, and Operator platform access on the IAM Identity Service.
6. Click Configure.

Now, your Secrets Manager instance is enabled for IAM credential secrets.







 Setting up the IAM credentials engine from the CLI 

Before you can create dynamic IAM credentials, you must configure the IAM secrets engine for your service instance.
The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

curl -X POST
-H "Authorization: Bearer {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
{
"name": "example-iam-credentials-secret",
"description": "Description of my IAM Credentials secret",
"secret_type": "iam_credentials",
"secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
"labels": [
"dev",
"us-south"
],
"ttl": "30m",
"access_groups": [
"AccessGroupId-45884031-54be-4dd7-86ff-112511e92699",
"AccessGroupId-8c0ed733-dfee-4a94-992b-e2247b86e2a2"
],
"reuse_api_key": false,
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful response returns the ID value of the secret, along with other metadata. For more information about the required and optional request parameters, check out the [API reference](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret).



 Reusing the same API key until the lease expires 

IAM credentials consist of a service ID and an API key.
Why can't I configure the IAM credentials engine? 

You try to configure the IAM credentials engine in an IBM Cloud® Secrets Manager instance, but you're unable to do so.

 What’s happening 

In the Secrets Manager UI, you go to the Secrets engines page to configure the IAM credentials engine. You receive the following error message when you try to create an API key:

Access required
You're not authorized to complete this action. To verify your permissions, contact your administrator.

You verify with an account owner that you already have [Manager service access](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iamiam-roles-actions) to Secrets Manager, but you're still unable to configure the IAM credentials engine for the instance.

 Why it’s happening 

You need extra permissions to [create service ID API keys](https://cloud.ibm.com/docs/account?topic=account-account-servicesidentity-service-account-management) in the account. In some cases, API key and service ID creation might also be restricted on the account.

 How to fix it 

First, verify with the account owner that you're assigned the following IAM permissions:



* Administrator platform access on the IAM Access Groups Service.
* Administrator platform access on the IAM Identity Service.
* Manager service access on the Secrets Manager instance.



If the updated access permissions do not resolve the issue, verify with the account owner that the [Restrict API key creation](https://cloud.ibm.com/docs/account?topic=account-allow-api-create) and [Restrict service ID creation](https://cloud.ibm.com/docs/account?topic=account-restrict-service-id-create) options are disabled on the account.

Zoom

![The figure shows a simplified IAM dashboard with numbered steps for disabling account restrictions.]
"foo": "bar"
},
"annotations": {
"baz": "qux"
}
}
}'







 Viewing a credential 

After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential that includes the API key value.

To view an existing service credential for a service, complete the following steps:



1. From the Resource list page, select the name of the service to open the service details page.
2. Click Service credentials
3. Expand View credentials on the row for an existing credential.





 Credential level access 

The access of the user must be equal to or greater than the access of the service credential. For example, if the credential has the IAM service role Writer, then the user trying to view the credential must have the IAM service role Writer or Manager for that particular service assigned. When a user doesn't have the correct access, details such as the API key value are redacted:

"credentials": {
"REDACTED": "REDACTED"
},





 IAM level access 

When the credential level access can't be determined by comparing the access of the user and the credential, the credential is redacted:

"credentials": {
"REDACTED": "REDACTED_EXPLICIT"
},

To view the credential, the user must have the IAM level access action resource-controller.credential.retrieve_all. This action is given with the Administrator role, and overrides any credential level access enabling the user to view the credential.







 Viewing a credential by using the API 

After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential including the API key value.
},
"warnings": null
}

If the role is created in a secret group, the data.secret_group_id value is included in the response to identify the secret group assignment.







 Generate IAM credentials 

Use the following commands to generate an API key for a role. This command creates a service ID, adds the service ID to the access group that you configured for the role, and then generates an API key for the service ID.

Generate an API key for a role in the default secret group.

vault read [-format=FORMAT] ibmcloud/iam_credentials/creds/ROLE_ID

Generate an API key for a role in a specified secret group.

vault read [-format=FORMAT] ibmcloud/iam_credentials/creds/groups/SECRET_GROUP_ID/ROLE_ID

The generated API keys are renewable and have a time-to-live (TTL) as defined by the role or the system default.



 Prerequisites 

You need the [Writer service role](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam) to create secrets.





 Command options 

SECRET_GROUP_ID
: The ID of the secret group that you want to assign to this secret.

ROLE_ID
: The ID or name that is assigned to the role for this secret.

-format
: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.





 Examples 

Generate an IAM credential for a secret that is assigned to the default secret group.

vault read -format=json ibmcloud/iam_credentials/creds/test-iam-credentials

Generate an IAM credential for a secret that is assigned to a specified secret group.
Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



10. Click Next.
11. Set a lease duration or time-to-live (TTL) for the secret.

By setting a lease duration for your IAM credential, you determine how long its associated API key remains valid. After the IAM credential reaches the end of its lease, it is revoked automatically.

Minimum duration is 1 minute. Maximum is 90 days.
12. Optional: [Determine whether IAM credentials can be reused](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentialsiam-credentials-reuse-ui) for your secret.
13. Optional: Enable automatic rotation of your secret. Secrets can be automatically rotated only if the reuse IAM credentials option is selected.
14. Click Next.
15. [Determine the scope of access](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentialsiam-credentials-service-id-ui) to assign for your IAM credential.
16. Click Next.
17. Review the details of your secret.
18. Click Add.





 Reusing the same API key until the lease expires 

IAM credentials consist of a service ID and an API key. By default, the service ID and API key are single-use, ephemeral values that are generated and deleted each time that an IAM credentials secret is read or accessed.

If you'd like to continue to use those credentials through the end of the lease of your secret, you can set Reuse IAM credentials until lease expires to On. When you enable this option, your secret retains its current service ID, and API key values and reuses them on each read while the secret remains valid. After the secret reaches the end of its lease, the credentials are revoked automatically.

If the reuse IAM credentials option is set to Off, manual rotation for the secret isn't supported.