Adding and viewing credentials

Adding a credential when binding an IAM-enabled service

Services that are managed by IBM Cloud Identity and Access Management (IAM) can generate a resource key, also known as a credential. Credentials are service-specific and vary based on how each service defines the credentials they need to generate. A credential might contain a user name, password, host name, port, and a URL, however the contents of each credential is unique to the service that generates it.

Some services might generate more data that requires parameters to be passed in. For example, a service might require you to input a language parameter to set the default language that is returned in the resource key that is generated.

Complete the following steps to add a credential to a service that is managed by IAM:

1. From the Resource list page, select the name of the service to open the service details page. Then, click Service credentials > New Credential+.

2. Provide a Name.

3. Specify the role. This value sets the IAM service access role. If no additional access is required, specify None. For more information, see IAM Access.

4. Optionally, you can provide a Service ID by either allowing IAM to generate a unique value for you, or by providing an existing Service ID. For more information, see Creating and working with service IDs.

5. Optionally, you can provide more parameters as a valid JSON object that contains service-specific configuration parameters, provided either inline or in a file.

   Most services don't require extra parameters, and for services that do, each service defines its own unique list of parameters. For a list of supported configuration parameters, see the documentation for the particular service.

6. Click Add to generate the new service credential.

Adding a credential when binding an IAM-enabled service by using the API

Services that are managed by IBM Cloud Identity and Access Management (IAM) can generate a resource key, also known as a credential. Credentials are service-specific and vary based on how each service defines the credentials they need to generate. A credential might contain a user name, password, host name, port, and a URL, however the contents of each credential is unique to the service that generates it.

Some services might generate more data that requires parameters to be passed in. For example, a service might require you to input a language parameter to set the default language that is returned in the resource key that is generated.

Services managed by IAM that generate new credentials can assign an IAM Service access role. This role grants access to the entire service instance. For services that have finer grain resource access, you might want to grant access only to a sub-resource, such as a Cloud Object Storage bucket. In this case, select None as the role so that the new credential is created without an IAM Service role. This way, you can manage fine grain access by creating an IAM policy that you scope to a specific resource, like a bucket. To do so, go to Manage > Access (IAM) > Service IDs. Select the service ID with the same name as the service credential key, and click Assign access.

To create a resource key, call the Resource Controller API as shown in the following example:

curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_keys -H 'Authorization: Bearer <IAM_TOKEN>' -H 'Content-Type: application/json' -d '{
  "name": "my-instance-key-1",
  "source": "267bf377-7fa2-43f6-94ec-09103a8e89d4",
  "role": "Writer"
}'

ResourceKeyPostParameters parameters = new ResourceKeyPostParameters.Builder()
  .add("exampleParameter", "exampleValue")
  .build();
CreateResourceKeyOptions createResourceKeyOptions = new CreateResourceKeyOptions.Builder()
  .name(keyName)
  .source(instanceGuid)
  .parameters(parameters)
  .build();

Response<ResourceKey> response = service.createResourceKey(createResourceKeyOptions).execute();
ResourceKey resourceKey = response.getResult();

System.out.printf("createResourceKey() response:\n%s\n", resourceKey.toString());

const parameters = {
  'exampleParameter': 'exampleValue'
};

const params = {
  name: keyName,
  source: instanceGuid,
  parameters: parameters,
};

resourceControllerService.createResourceKey(params)
  .then(res => {
    instanceKeyGuid = res.result.guid;
    console.log('createResourceKey() response:\n' + JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

parameters = {
    'exampleParameter': 'exampleValue'
}
resource_key = resource_controller_service.create_resource_key(
    name=key_name,
    source=instance_guid,
    parameters=parameters
).get_result()

print('\ncreate_resource_key() response:\n',
      json.dumps(resource_key, indent=2))

createResourceKeyOptions := resourceControllerService.NewCreateResourceKeyOptions(
  keyName,
  instanceGUID,
)

parameters := &resourcecontrollerv2.ResourceKeyPostParameters{}
parameters.SetProperty("exampleParameter", "exampleValue")
createResourceKeyOptions.SetParameters(parameters)

resourceKey, response, err := resourceControllerService.CreateResourceKey(createResourceKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceKey, "", "  ")
fmt.Printf("\nCreateResourceKey() response:\n%s\n", string(b))

Adding a credential when binding an IAM-enabled service by using Terraform

Before you can add a credential when binding an IAM-enabled service by using Terraform, make sure that you have completed the following:

• Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform. For more information, see the tutorial for Getting started with Terraform on IBM Cloud®. The plug-in abstracts the IBM Cloud APIs that are used to complete this task.
• Create a Terraform configuration file that is named main.tf. In this file, you define resources by using HashiCorp Configuration Language. For more information, see the Terraform documentation.

Use the following steps to add a credential when binding an IAM-enabled service:

1. Create an argument in your main.tf file. The following example creates credentials for a resource without a service ID by using the ibm_resource_instance resource, where name is a unique name to identify the credential.

   data "ibm_resource_instance" "resource_instance" {
    name = "myobjectsotrage"
   }
   
   resource "ibm_resource_key" "resourceKey" {
    name                 = "myobjectkey"
    role                 = "Viewer"
    resource_instance_id = data.ibm_resource_instance.resource_instance.id
   
    //User can increase timeouts
    timeouts {
      create = "15m"
     delete = "15m"
    }
   }
   

   By default, the ibm_resource_key resource creates service credentials that use the public service endpoint of a service

   You can specify tags associated with the resource group instance. For more information, see the argument reference details on the Terraform Resource Management page.

2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.

   terraform init
   

3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.

   1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan
      

   2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply
      

curl "https://api.example.org/v3/service_credential_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "app",
    "name": "some-binding-name",
    "relationships": {
      "service_instance": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      },
      "app": {
        "data": {
          "guid": "e0e4417c-74ee-11ea-a604-48bf6bec2d78"
        }
      }
    },
    "parameters": {
      "key1": "value1",
      "key2": "value2"
    },
    "metadata": {
      "labels": {
        "foo": "bar"
      },
      "annotations": {
        "baz": "qux"
      }
    }
  }'

curl "https://api.example.org/v3/service_credential_bindings" \
  -X POST \
  -H "Authorization: bearer [token]" \
  -H "Content-type: application/json" \
  -d '{
    "type": "key",
    "name": "some-binding-name",
    "relationships": {
      "service_instance": {
        "data": {
          "guid": "7304bc3c-7010-11ea-8840-48bf6bec2d78"
        }
      }
    },
    "parameters": {
      "key1": "value1",
      "key2": "value2"
    },
    "metadata": {
      "labels": {
        "foo": "bar"
      },
      "annotations": {
        "baz": "qux"
      }
    }
  }'

Viewing a credential

After a credential is created for a service that has onetime_credentials configured to false, it can be viewed at any time for users that need the credential values. 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.

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

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

Viewing a credential by using the API

After a credential is created for a service that has onetime_credentials configured to false, it can be viewed at any time for users that need the credential values. However, all users must have the correct level of access to see the details of a credential that includes 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 that is 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 as shown in the following example:

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%s\n", resourceKeysList.toString());

const params = {
  name: keyName,
};

resourceControllerService.listResourceKeys(params)
  .then(res => {
    console.log('listResourceKeys() response:\n' + JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

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

print('\nlist_resource_keys() response:\n',
      json.dumps(resource_keys_list, indent=2))

listResourceKeysOptions := resourceControllerService.NewListResourceKeysOptions()
listResourceKeysOptions = listResourceKeysOptions.SetName(keyName)

resourceKeysList, response, err := resourceControllerService.ListResourceKeys(listResourceKeysOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceKeysList, "", "  ")
fmt.Printf("\nListResourceKeys() response:\n%s\n", string(b))

Example response:

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "onetime_credentials": false,
      "credentials": {
        "apikey": "XXXX-YYYY-ZZZZ\"",
        "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
        "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
      "resource_alias_url": null
    }
  ]
}

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

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