Using dual authorization

After you set up your IBM® Key Protect service instance, you can manage dual authorization by using the service API.

Managing dual authorization settings

Dual authorization for Key Protect service instances is an extra policy that helps to prevent accidental or malicious deletion of keys. When you enable this policy at the instance level, Key Protect requires an authorization from two users to delete any keys that are created after the policy is enabled.

The dual authorization capability is available only through the Key Protect API. To find out more about accessing the Key Protect APIs, check out Setting up the API.

Before you enable dual authorization for your Key Protect instance, keep in mind the following considerations:

When you enable dual authorization for your Key Protect instance, the policy is applicable only for new keys. By enabling dual authorization at the instance level, any new keys that you add to the instance will automatically inherit a dual authorization policy. Your existing keys are not affected by the policy change and will still require a single authorization for deletion.
You can always disable a dual authorization policy for your Key Protect instance. If you want to disable an existing dual authorization policy to allow for single authorization, keep in mind that the change is applicable only for future keys that you add to the instance. Any existing keys that were created under a dual authorization policy will continue to require actions from two users before the keys can be deleted. After a key inherits a dual authorization policy, the policy cannot be reverted.

Enabling dual authorization for your Key Protect instance with the console

If you prefer to disable a dual authorization policy on your instance by using a graphical interface, you can use the IBM Cloud console.

After creating a Key Protect instance, complete the following steps to create a dual authorization policy:

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
Click the Instance policies link on the left side of the page.
- Find the Dual authorization delete panel (on the top-left side of the page).
- Toggle Dual authorization deletion to enable or disable the policy.
- Click Save or Cancel (whichever is appropriate).

Enabling dual authorization for your Key Protect instance with the API

As an instance manager, enable a dual authorization policy for a Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete

Retrieve your authentication credentials to work with the API.

To enable and disable dual authorization policies, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Enable a dual authorization policy for your Key Protect instance by running the following curl command.

$ curl -X PUT \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "x-kms-key-ring: <key_ring_ID>" \
    -H "content-type: application/vnd.ibm.kms.policy+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.policy+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "policy_type": "dualAuthDelete",
                    "policy_data": {
                        "enabled": true
                    }
                }
            ]
        }'

Replace the variables in the example request according to the following table.

Table 1. Describes the variables that are needed to enable dual authorization at the instance level.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see Grouping keys.

A successful request returns an HTTP 204 No Content response, which indicates that your Key Protect instance is now enabled for dual authorization. Keys that you create or import to the service now require two authorizations before they can be deleted. For more information, see Deleting keys.

This new policy does not affect existing keys in your instance. If you need to enable dual authorization for an existing key, see Creating a dual authorization policy for a key.

Optional: Verify dual auth policy enablement

You can verify that a dual auth policy key has been enabled by issuing a list policies request:

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Where the <instance_ID> is the name of your instance and your <IAM_token> is your IAM token.

Disabling dual authorization for your Key Protect instance with the console

If you prefer to disable a dual authorization policy on your instance by using a graphical interface, you can use the IBM Cloud console.

After creating a Key Protect instance, complete the following steps to create a dual authorization policy:

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
On the Instance policies page, use the Policies table to browse the policies in your Key Protect instance.
Click the ⋯ icon to open a list of options for the policy that you want to disable.
From the options menu, click Disable policy and confirm the policy was disabled in the updated Policies table.

Disabling dual authorization for your Key Protect instance with the API

As an instance manager, disable an existing dual authorization policy for a Key Protect instance by making a PUT call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete

Retrieve your authentication credentials to work with the API.

To enable and disable dual authorization policies, you must be assigned a Manager access policy for your Key Protect instance. To learn how IAM roles map to Key Protect service actions, check out Service access roles.

Disable an existing dual authorization policy for your Key Protect instance by running the following curl command.

$ curl -X PUT \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "x-kms-key-ring: <key_ring_ID>" \
    -H "content-type: application/vnd.ibm.kms.policy+json" \
    -d '{
            "metadata": {
                "collectionType": "application/vnd.ibm.kms.policy+json",
                "collectionTotal": 1
            },
            "resources": [
                {
                    "type": "application/vnd.ibm.kms.policy+json",
                    "dualAuthDelete": {
                        "enabled": false
                    }
                }
            ]
        }'

Replace the variables in the example request according to the following table.

Table 1. Describes the variables that are needed to enable dual authorization at the instance level.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the key ring that the key is a part of. If unspecified, Key Protect will search for the key in every key ring associated with the specified instance. It is recommended to specify the key ring ID for a more optimized request. Note: The key ring ID of keys that are created without an `x-kms-key-ring` header is: default. For more information, see Grouping keys.

A successful request returns an HTTP 204 No Content response, which indicates that the dual authorization policy was updated for your service instance. Keys that you create or import to the service now require only one authorization before they can be deleted. For more information, see Deleting keys.

Optional: Verify dual auth policy disablement

You can verify that a dual auth policy key has been disabled by issuing a list policies request:

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete" \
    -H "accept: application/vnd.ibm.kms.policy+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Where the <instance_ID> is the name of your instance and your <IAM_token> is your IAM token.