Skip to content

Latest commit

 

History

History
285 lines (228 loc) · 9.78 KB

rest-api.md

File metadata and controls

285 lines (228 loc) · 9.78 KB
Raw
copyright lastupdated
years
2017, 2018
2018-03-08

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:codeblock: .codeblock} {:pre: .pre} {:tip: .tip}

Managing certificates by using API

{: #managing-certificates-by-using-api}

The {{site.data.keyword.cloudcerts_full}} service provides REST endpoints to import, get, and delete certificates. Using {{site.data.keyword.iamshort}}, you can also assign policies for a specific certificate. {: shortdesc}

Testing APIs

{: #testing}

You can test REST endpoints by using Swagger or by running cURL requests in the command line.
Swagger is available in the US-South {{site.data.keyword.Bluemix_notm}} region only. {: shortdesc}

Prerequisites

{: #prereq-api}

You must complete the following tasks before you can use {{site.data.keyword.cloudcerts_full}}. {: shortdesc}

  • Install the {{site.data.keyword.Bluemix_notm}} CLI to obtain the required data.

  • When you work with the {{site.data.keyword.cloudcerts_short}} API, you can use the following variables in your calls.

Table 1. Command components explained
Component Explanation
IAM-token You can obtain your {{site.data.keyword.iamshort}} (IAM) access token by logging in to {{site.data.keyword.Bluemix_notm}} and running the bx iam oauth-tokens command.
certificateId The [Cloud Resource Name (CRN)-based certificate ID](/docs/overview/crn.html#format) that is assigned to your certificate after it is imported. You can find your certificate ID by using one of the following choices:
  • In the Manage tab of the service, view the certificate information by selecting it in the Certificates table.
  • Via API: [list your available certificates](/docs/services/certificate-manager/rest-api.html#list-certificates).
instanceId The [Cloud Resource Name (CRN)-based instance ID](/docs/overview/crn.html#format) that is assigned to your service instance after it is created. You can retrieve the instance ID in the following ways:
  • In the Manage page of the service.
  • Run the bx resource service-instance command, replacing <Instance_Name> with the name of your service instance. 
    bx resource service-instance <Instance_Name> --id
  • Call the {{site.data.keyword.Bluemix_notm}} Resource Controller [GET /resource_instances](https://console.bluemix.net/apidocs/700-resource-controller-api?&language=node#resource-instances-1) REST endpoint, which requires the Authorization header with your account administrator's IAM token.
account-id The account ID of the user that manages the {{site.data.keyword.Bluemix_notm}} account. You can find your account ID by running the bx info command.
cluster-url The URL of the service in the {{site.data.keyword.Bluemix_notm}} region in which it was created. You can find the URL in the Swagger UI.
name (Optional) The display name for the imported certificate.
description (Optional) The description for the imported certificate.
certificate The certificate data, escaped.
privateKey The private key data, escaped.
intermediate (Optional) The intermediate certificate data, escaped.
user-id The ID of the user that you want to assign an access policy to. To find the user ID, see [Retrieving the user ID](#retrieve-user-id).

Importing a certificate

{: #import-certificate}

Import a certificate in Privacy-enhanced Electronic Mail (PEM) format with its private key. You can also import an intermediate certificate. {: shortdesc}

Run the following curl command:

curl -X POST \
https://<cluster-url>/api/v2/<instanceId>/certificates/import \
-H 'authorization: Bearer <IAM-token>' \
-H 'content-type: application/json' \
-d '{
  "name":"<name>",
  "description":"<description>",
  "data":{
  	"content": "<certificate>",
  	"priv_key": "<privateKey>",
  	"intermediate": "<intermediate>"
  }
}'

{: pre}

Replace <cluster-url>, <instanceId>, <IAM-token>, <name>, <description>, <certificate>, <privateKey>, and <intermediate> with the appropriate values. The <name>, <description>, and <intermediate> values are optional.

Updating certificate metadata

{: #update-certificate-metadata}

Update a certificate’s optional name, description, or both, properties.

Note: Update operations are limited to five actions per minute.
{: shortdesc}

Run the following curl command:

curl -X POST \
https://<cluster-url>/api/v2/certificate/<certificateId> \
-H 'authorization: Bearer <IAM-token>' \
-H 'content-type: application/json' \
-d '{
  "name":"<name>",
  "description":"<description>"
}'

{: pre}

Replace <cluster-url>, <instanceId>, <certificateId>, <IAM-token>, <name>, and <description> with the appropriate values.

Listing all of your certificates

{: #list-certificates}

Retrieve a list of all of your available certificates. {: shortdesc}

Run the following curl command:

curl -H "Authorization: Bearer <IAM-token>" https://<cluster-url>/api/v2/<instanceId>/certificates/

{: pre}

Replace <IAM-token>, <cluster-url>, and <instanceId> with the appropriate values.

Downloading a certificate

{: #get-certificate}

Use a retrieved certificate ID to download the certificate data. {: shortdesc}

Run the following curl command:

curl -H "Authorization: Bearer <IAM-token>" https://<cluster-url>/api/v2/certificate/<certificateId>

{: pre}

Replace <IAM-token>, <cluster-url>, <instanceId> and <certificateId> with the appropriate values.

Deleting a certificate

{: #delete-certificate}

Use a retrieved certificate ID to delete the certificate and its data. {: shortdesc}

Run the following curl command:

curl -H "Authorization: Bearer <IAM-token>" -X DELETE https://<cluster-url>/api/v2/certificate/<certificateId>

{: pre}

Replace <IAM-token>, <cluster-url>, <instanceId> and <certificateId> with the appropriate values.

Assigning advanced policies

{: #assigning-advanced-policies}

You can choose to allow certain users to perform certain actions on specific certificates. You might want to allow users to view only a subset of the available service instance certificates. {: shortdesc}

To assign the policy, send a request to {{site.data.keyword.iamshort}} by running the following curl command. Repeat the command for each certificate.

curl -X POST \
    https://iampap.<region>.bluemix.net/acms/v1/scopes/a%2<account-id>/users/<user-id>/policies \
    -H 'accept: application/json' \
    -H 'authorization: Bearer <Account-Admin-IAM-token>' \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/json' \
    -d '{
        "roles": [
        {
            "id": "crn:v1:bluemix:public:iam::::role:Viewer"
        }
    ],
    "resources": [
        {
            "serviceName”: "cloudcerts",
            "serviceInstance": "<instanceId>",
            "resourceType": "certificate",
            "resource": "<certificateId>"
        }
    ]
}'

{: pre}

Replace <account-id>, <user-id>, <instanceId> and <certificateId> with the appropriate values. Replace <Account-Admin-IAM-token> with the account administrator's IAM token. Replace <region> with your region, for example, ng for US-South.

Note: In the preceeding cURL request, instanceId and certificateId are not CRN-based, they are GUID-based.
For example, in the following certificateId CRN, the instanceId value is 58866f34-55ca-4477-8c32-fda435f01f97 and the certificateId value is e20cb664efcbfa2c2f57801230d246a6.

crn:v1:staging:public:cloudcerts:us-south:a/d0c8a917589e40076a61e56b23056d16:58866f34-55ca-4477-8c32-fda435f01f97:certificate:e20cb664efcbfa2c2f57801230d246a6

Retrieving the user ID

{: #retrieve-user-id}

Retrieve the user ID. {: shortdesc}

To retrieve the user ID, complete the following steps:

  1. Ask the user to provide the IAM token. The IAM token structure is in the following format: <value_1>.<value_2>.<value_3>

  2. Copy the value of <value_2> and run the following echo command:

    echo -n "<value_2>" | base64 --decode

    {: pre}

    The result is a JSON object similar to the following output:

    {
     "iam_id":"...",
     "id":"...",
     "realmid":"...",
     "identifier":"...",
     "given_name":"...",
     "family_name":"...",
     "name":"...",
     "email":"...",
     "sub":"...",
     "account":{
         "bss":"..."},
         "iat":...,
         "exp":...,
         "iss":"...",
         "grant_type":"...",
         "scope":"...",
         "client_id":"..."
     }
}

    {: screen}

  3. Copy the value of the id property.