Managing access for IBM Cloudant

Service credential JSON examples for each option

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.

{
  "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
  "iam_apikey_description": "Auto generated apikey during resource-key [...]",
  "iam_apikey_id": "050d21b5-5f4a-4a5b-8a2c-0a2c0a2c0a2c",
  "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://00000000-0000-0000-0000-00000000.abc.cloudant.eu-de.dataservices.appdomain.cloud",
  "vpe_url": "https://00000000-0000-0000-0000-00000000.private.abc.eu-de.cloudant.dataservices.appdomain.cloud"
}

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_id

Unique id the 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 public service URL.

vpe_url

IBM Cloudant private service URL.

Examples

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://00000000-0000-0000-0000-00000000.abc.cloudant.eu-de.dataservices.appdomain.cloud"/_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://00000000-0000-0000-0000-00000000.abc.cloudant.eu-de.dataservices.appdomain.cloud/source",
    "auth": {
      "iam": {
        "api_key": "xju1...TxuS"
      }
    }
  },
  "target": {
    "url": "https://00000000-0000-0000-0000-00000000.abc.cloudant.eu-de.dataservices.appdomain.cloud/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://00000000-0000-0000-0000-00000000.abc.cloudant.eu-de.dataservices.appdomain.cloud/_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.

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.

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.