Authenticating with IBM Cloudant FAQ

IBM Cloud® Identity and Access Management (IAM) combines managing user identities, services, and access control into one approach. IBM® Cloudant® for IBM Cloud® integrates with IBM Cloud Identity and Access Management.

What is the difference between IBM Cloudant legacy and IAM access controls?

IBM Cloud IAM

Centrally managed access management across IBM Cloud.
Allows a user or service to access many different resources by using the same set of credentials (for example, same username and password or IAM API key).
IAM API keys can be granted access to account management functions, like creating new databases.

IBM Cloudant legacy

Unique to IBM Cloudant.
Access to each service instance requires its own set of credentials.
Uses HTTP basic authentication with credentials that aren't bound to an individual user or service.

Why is the Use only IAM mode preferred?

The Use only IAM mode means that only IAM credentials are provided through service binding and credential generation. You gain the following advantages when you use IBM Cloud IAM:

Managing access to IBM Cloudant with the standard tooling of IBM Cloud.
Using credentials that you can easily revoke and rotate when you use IBM Cloud IAM.

For more information about the advantages and disadvantages between these modes, see Advantages and disadvantages of the two access control mechanisms.

How can I create an instance by using the command line?

When you create a new IBM Cloudant instance from the command line, you must include the ibmcloud tool by using the -p parameter. This parameter enables or disables legacy credentials for an account by passing the option in JSON format. The option is called legacyCredentials.

To create an instance as Use only IAM, run the following command:

ibmcloud resource service-instance-create  "Instance Name" \
    cloudantnosqldb Standard us-south \
    -p '{"legacyCredentials": false}'

If you don't use Use only IAM mode when you use the IAM Reader and Writer roles, you might grant users legacy credentials with more access permissions than you intended.

How can I generate service credentials?

You can generate service credentials in the primary IBM Cloud IAM interface. When you select Use only IAM, service credentials include only IAM values. The service credential JSON looks like the following example:

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "host": "2922d728-27c0-4c7f-aa80-1e59fbeb04d0-bluemix.cloudant.com",
  "iam_apikey_description": "Auto generated apikey during resource-key [...]",
  "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::[...]",
  "url": "https://76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "username": "76838001-b883-444d-90d0-46f89e942a15-bluemix"
}

The values for the previous example are described in the following list:

apikey: IAM API key.
host: The DNS that resolves domain names with their corresponding IP addresses.
iam_apikey_description: Description of IAM API key.
iam_apikey_name: ID of IAM API key.
iam_role_crn: The IAM role that the IAM API key has.
iam_serviceid_crn: The CRN of service ID.
url: IBM Cloudant service URL.
username: The internal IBM Cloudant account name.

For more information, see IBM Cloud API keys and Use only IAM.

How do I rotate my credentials?

In most cases, rotating credentials is a straight-forward process:

Generate a replacement service credential. For more information, see How can I generate service credentials?.
Replace the current credential with the newly generated credential.
Delete the no-longer-used service credential.

However, when you rotate the credentials for a replication, if you are using legacy credentials in the replication document, the replication starts from the beginning. To ensure that changes arrive in a timely manner, we advise you to create a new replication once it catches up with deleting the previous replication and the associated service credential. The process is described in the following steps:

Generate a replacement service credential. For more information, see How can I generate service credentials?.
Create a replication with the same settings but new credentials.
Monitor the new replication by using Active Tasks, or you can use _scheduler/jobs.
Once the changes_pending field for the new replication is a suitably low value for your requirements, the replication that uses the previous credentials can be deleted.
Delete the no-longer-used service credential.

Replications that use IAM API keys can be updated to use a new API key directly, without delaying the changes that are replicating.