Managing access for IBM Cloudant

IBM Cloud Identity and Access Management

• Centrally managed access management across IBM Cloud.
• Allow 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 access controls

• Unique to IBM Cloudant.
• Access to each service instance requires its own set of credentials.
• Uses HTTP basic authentication with credentials that are not bound to an individual user or service.
• IBM Cloudant API keys can be granted permissions only at a database level.

API key notes

In this document, wherever API keys are mentioned it refers to IAM API keys. IBM Cloudant legacy access controls also have a concept of API keys, and any discussion about IBM Cloudant legacy credentials or username and password combinations also includes IBM Cloudant API keys.

IBM Cloudant API keys and Use only IAM

Use of IBM Cloudant API keys alongside IAM is possible but not recommended. This recommendation is made because IBM Cloudant API keys and permissions are not visible or manageable by using the IAM policy interface, rendering holistic access management impossible.

The choice between Use only IAM or Use both legacy credentials and IAM affects the following factors:

1. Whether legacy IBM Cloudant account-level credentials are available to manage databases and other account-level actions.
2. The style of credentials that are delivered during service credential generation.

In particular, IBM Cloudant API keys can still be used to manage database access. These credentials must be generated and configured by using the HTTP API.

Provisioning by using the command line

When you provision a new IBM Cloudant instance from the command line, provide an option to the ibmcloud tool by using the -p parameter to enable or disable legacy credentials for an account. The option is passed in JSON format and is called legacyCredentials.

To provision an instance as Use only IAM (recommended), run the following command:

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

When you use IAM roles other than Manager, such as Reader, Writer, Monitor, or Checkpointer, you must use Use only IAM to avoid supplying users with legacy credentials that include greater access permissions.

To provision an instance as Use both legacy credentials and IAM, run the following command:

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

Service credential JSON examples for each option

The choice between Use only IAM and Use both legacy credentials and IAM access control affects how credentials are delivered to your application when you bind and generate service credentials. When you generate credentials within the primary IBM Cloud IAM interface, API keys are shown in that interface when generated.

You can also generate credentials from the Service Credentials section of a service instance. Generating service credentials this way creates a service credentials JSON blob that can be pasted into applications with all the details that are needed to access the service instance.

Next, you can see what the service credential JSON looks like and what each value means.

When you select Use only IAM, the service credentials that are generated contain only IAM values, and look like the following example.

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "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"
}

Each value in the previous JSON example must be interpreted by using the following definitions:

apikey

IAM API key.

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.

When you select Use both legacy credentials and IAM, the service credentials that are generated contain both IAM and legacy credentials, and look like the values in the following example.

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "host": "76838001-b883-444d-90d0-46f89e942a15-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::[...]",
  "password": "8fb6a16b48903e87b769e7f4968521e85c2394ed8f0e69b2769e56dcb27d2e76",
  "port": 443,
  "url": "https://<username>:<password>@76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "username": "apikey-v2-58B528DF5397465BB6673E1B79482A8C"
}

Each value in the previous JSON example must be interpreted by using the following definitions:

apikey

IAM API key.

host

IBM Cloudant service hostname.

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.

password

The IBM Cloudant legacy credential password.

port

IBM Cloudant service port.

url

IBM Cloudant service URL, including embedded IBM Cloudant legacy credentials.

username

The IBM Cloudant legacy credential username.

Note the included username and password are always equivalent to IAM's Manager credentials. Therefore, the use of Use both legacy credentials and IAM is insecure when used with Reader, Writer, Monitor, or Checkpointer IAM roles.

Advantages and disadvantages of the two access control mechanisms

Overall, IBM Cloud IAM is the recommended authentication model. However, the primary disadvantages to the approach are if you have an existing application or are unable to use an IBM Cloudant-supported client library.

Generating IAM API keys for Source and Target and one for IBM Cloudant API access

In this exercise, the first two API keys are created so that the two instances can talk to each other during the replication process. The third API key is for the user to access the IBM Cloudant API, create the _replicator database, and then add the replication document to it.

Follow these steps to generate IAM API keys and API access for IBM Cloudant. You must write down the credentials that are requested in the following steps to continue with the example.

Ensure that you select the specified instance, either the Source or Target.

1. Log in to cloud.ibm.com.

2. From the Resource list, select Services and your Source instance.

   1. Click Service credentials and click New credential.

   2. Name the new credential replicator-source, and select the Manager role.

   3. Click Add, and make note of its apikey, which is under View Credentials in the Actions column.

3. Repeat steps 2 through 2.c. for the Target instance.

   1. Create a credential called replicator-target with the Manager role.

   2. Make note of its IAM API key, which is under View Credentials in the Actions column.

4. Select the Source instance, and click Service credentials and New credential.

   1. Name the new credential apiaccess, and select the Manager role.

   2. Make note of the actual IAM API key under View Credentials in the Actions column.

5. Make note of Source and Target instance URLs.

Depending on your workflow, instead of creating a service-level credential (step 4), you can use a personal IAM API key, as detailed in Creating an API key.

You can also complete these steps on the command line by using the IBM Cloud CLI tool chain.

Generating a bearer token to authenticate against the IBM Cloudant API

In step 4.b., you wrote down the apiaccess key. Use that key now:

curl -k -X POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  --data-urlencode "apikey=aSCsx4...2lN97h_2Ts" \
  "https://iam.cloud.ibm.com/identity/token"

The apiaccess key returns the following information (abbreviated):

{
   "access_token": "eyJraWQiOiIyMDE5MD...tIwkCO9A",
   "refresh_token": "ReVbNrHo3UA38...mq67g",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1566313064,
   "scope": "ibm openid"
}

Create an environment variable to save some typing by using the value under the access_token key in the response data:

export TOK="Bearer eyJraWQiOiIyMDE5MD...tIwkCO9A"

Creating the _replicator database on the Source side

URL is the Source instance URL that you previously wrote down in step 4.b.

curl -k -X PUT \
     -H"Content-type: application/json" \
     -H'Authorization: '"$TOK"'' \
     'https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/_replicator'

See the results in the following example:

{"ok": "true"}

Creating the replication job

Create a file called data.json that contains the following information. The two keys are the Source and Target API keys that are created in the beginning, and the Source and Target instance URLs, with database names added.

{
  "source": {
    "url": "https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/source",
    "auth": {
      "iam": {
        "api_key": "xju1...TxuS"
      }
    }
  },
  "target": {
    "url": "https://dbc68dd8-f69f-4083-97dd-bf0a3e1a467a-bluemix.cloudant.com/target",
    "auth": {
      "iam": {
        "api_key": "UElc7...QIaL01Bjn"
      }
    }
  },
  "create_target": true,
  "continuous": true
}

Now, write a replication document called source_dest to the _replicator database on the Source instance.

curl -k -X PUT \
     -H"Content-type: application/json" \
     -H'Authorization: '"$TOK"'' \
     'https://d43caf1b-e2c8-4d3e-9b85-1d04839fa68f-bluemix.cloudant.com/_replicator/source_dest' -d@data.json

See the results in the following example:

{"ok":true,"id":"source_dest","rev":"1-89b01e42968acd5944ed657b87c49f0c"}

Required client library versions

IAM connectivity is available in the latest release of all supported client libraries. For more information, see Client libraries.

Access by using HTTP client

IBM Cloud IAM requires that an IAM API key is exchanged for a time-limited access token before you make a request to a resource or service. The access token is then included in the Authorization HTTP header to the service. When the access token expires, the client must handle getting a new one from the IAM token service.

As stated previously, if you use IBM Cloud IAM, it requires that you first exchange an IBM API key for a time-limited access token. After that, you use the token to authenticate against the IBM Cloudant API.

In Python, an example might look like:

import time

import requests

API_KEY = "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz"
ACCOUNT = "76838001-b883-444d-90d0-46f89e942a15-bluemix"

def get_access_token(api_key):
    """Retrieve an access token from the IAM token service."""
    token_response = requests.post(
        "https://iam.cloud.ibm.com/identity/token",
        data={
            "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
            "response_type": "cloud_iam",
            "apikey": api_key
        },
        headers={
            "Accept": "application/json"
        }
    )
    if token_response.status_code == 200:
        print "Got access token from IAM"
        return token_response.json()['access_token']
    else:
        print token_response.status_code, token_response.json()
        return None

def main(api_key, account):
    access_token = None
    while True:
        if not access_token:
            access_token = get_access_token(api_key)

        if access_token:
            response = requests.get(
                "https://{0}.cloudant.com/_all_dbs".format(account),
                headers={
                    "Accept": "application/json",
                    "Authorization": "Bearer {0}".format(access_token)
                }
            )
            print "Got Cloudant response, status code", response.status_code
            if response.status_code == 401:
                print "Token has expired."
                access_token = None

        time.sleep(1)

if __name__ == "__main__":
    main(API_KEY, ACCOUNT)

Creating a Network Zone

To add IBM Cloudant to your IAM access list, you must first create a Network Zone that includes the IBM Cloudant service.

To create a network zone, complete the following steps.

1. In the IBM Cloud console, click Manage > Context-based restrictions, and select Network zones.
2. Click Create.
3. Enter a unique name (e.g. cloudant-network) and, optionally, a description.
4. Under Reference a service, select service type IAM Services and service IBM Cloudant. Click Add to associate the IBM Cloudant IP addresses with your network zone.
5. Click Next to review your network zone.
6. Click Create.

Referencing the Network Zone in the IAM IP allowlist

The Network Zone created above, called cloudant-network, can now be used in your IAM IP allowlist.

1. In the IBM Cloud console, click Manage > Access (IAM), and select Settings.
2. From the Account section, enable the IP address access setting.
3. In the Allowed IP addresses field, add the name of the Network Zone you created above (e.g. cloudant-network).
4. Click Save.

IBM Cloudant roles

The following table lists the available IAM service roles for IBM Cloudant and a brief description of each.

Manager is inclusive of all actions of Reader and Writer, and Writer is inclusive of all actions of Reader.

IBM Cloudant actions

The following table describes the available IAM actions and roles. For fine-grained authorization, you can use the roles of Manager, Reader, Writer, Monitor, or Checkpointer.

When you use IAM roles other than Manager, such as Reader, Writer, Monitor, or Checkpointer, you must use Use only IAM to avoid supplying users with legacy credentials that include greater access permissions.

Ensure that your account is IAM enabled

On the Overview portion of the IBM Cloudant Dashboard, "authentication method" is listed under deployment details. Your available authentication methods are listed there.