Configuring Key-Based Authentication
You configure the following information to enable API key authentication:
Specify the approval requirements for clients requesting API keys.
You can specify that requests must be approved by approver groups of your choosing, or you can specify that requests will be automatically approved.
Configure email messages to be sent to:
The approver groups when requests are submitted for approval.
The clients to inform them of their approval status.
Specify the expiration of the API key.
To use an API key to access and consume the API in CentraSite, clients must:
1. Register as a consumer for the API.
When the client registration request is approved, the client receives an API key (a base64-encoded string of the consumer-key:consumer-secret combination). It works for both SOAP and REST calls.
2. To call the API, the client must pass the API key in an HTTP request header or as a query string parameter. The use of this key establishes the client's identity and authentication.
To configure API for Key-based client authentication
1. In CentraSite Business UI, access the Advanced Search panel in one of the following ways:
Click the
Browse link in the upper-left corner of the menu bar.
Click the
Search icon next to the
Scope list. The default search scope is
Assets.
This displays a list of assets in the Search Results page.
2. In the Additional Search Criteria list, select Asset Types.
3. To search for the assets of type, Virtual Service, click Choose.
4. In the Choose Asset Types dialog box, select the Assets option button, and then follow these steps:
a. Click the chevron next to Assets option button.
b. In the displayed list of asset types, select Virtual Service.
c. Click OK.
A list of defined Virtual Service assets is displayed in the Search Results page.
5. Click the asset you want to configure the API key authentication.
This opens the Virtual Service details page. Also, the actions bar displays a set of actions that are available for working with the Virtual Service.
6. On the actions bar of the Virtual Service details page, click API Consumption Settings.
This opens the API Consumption Settings dialog box.
7. Select API Keys.
You might wish to modify the authentication type for an API at a later stage. When modifying the authentication type (say, OAuth2), if the API has one or more API keys generated using the currently configured authentication mechanism, CentraSite issues a warning message.
The message states that the modification to the configured authentication mechanism would deactivate all of the existing API keys that were generated using the authentication mechanism that you now intend to modify.
8. In the Usage Contract Expires After field, specify the maximum time that an API key will be valid for use with the API. The key expires after the set number of seconds, minutes, hours, days, weeks, months, or years.
The time is specified in the following form: #y #m #w #d #h #min #s, where:
# is a real number
y indicates the year
m indicates the month
w indicates the week
d indicates the day
h indicates the hour
min indicates the minute
s indicates the second
An example of a time: 1y 2m 3w 7d 5h 30min 15s. This value indicates that the API key will remain active until 1 year, 2 months, 3 weeks, 7 days, 5 hours, 30 minutes, and 15 seconds.
The default value of Unlimited denotes that the API key never expires.
When an API key expires, you can renew the expired API key in the following ways:
You can re-submit an API key request for consumption.
You (as an API provider) can renew the API key using the
Renew action.
9. Select the Require Approval checkbox if you want to initiate an approval workflow for generating and renewing the API key.
When a client requests for generating or renewing an API key that triggers an approval, CentraSite initiates an approval workflow and submits the client’s request to the designated group of approvers.
Approvers receive the approval request in the Pending Approval Requests in the API details page. Approvers whose user account includes a valid email address also receive an email message informing them that a request is awaiting their approval.
CentraSite does not execute the client’s requested operation until it obtains the necessary approvals. If an approver rejects the request, CentraSite notifies the requestor.
If you do not select the
Require Approval checkbox, the request is automatically approved and
CentraSite executes the client’s registration request.
10. If you select the Require Approval checkbox, complete the following fields:
Field | Description |
Approval is needed from | All | Requests must be approved by all users specified in Approver Group. (It does not matter in which order the approvals are issued.) A single rejection will cause the request to be rejected. |
Any | Default. Requests can be approved or rejected by any single user in Approver Group. Only one user from the set of authorized approvers is required to approve or reject the request. |
Approver Group | Specify the approver group. You can specify multiple approver groups. |
11. In the Key Generation Settings section, complete the following fields so that CentraSite will send emails consumers initially request API keys.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information from the centrasite.xml file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message. To specify an additional template, use the plus button to add additional rows. Important: CentraSite sends notifications about a request status to the consumer requesting for an API key; only if the client has enabled the Email notifications option in his User Preferences page. |
Action | Specify the approval action. |
Value | Description |
Approved | (Default). CentraSite sends an email message to the client when requests are approved. If you choose this option, you can use the predefined template APIKeyGenerationSuccess.html for approval notifications if you do not want to create an email template of your own. |
Approval Request | CentraSite sends an email message to the approver(s) when requests are submitted for approval. If you choose this option, you can use the predefined template PendingApprovalNotification.html for pending-approval notifications if you do not want to create an email template of your own. |
Rejected | CentraSite sends an email message to the client when requests are rejected. If you choose this option, you can use the predefined template RejectionNotification.html for rejection notifications if you do not want to create an email template of your own. |
12. In the Key Renewal Settings section, complete the following fields so that CentraSite will send emails when consumers request API key renewals.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information fetched from the centrasite.xml file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message. To specify an additional template, use the plus button to add additional rows. Important: CentraSite sends notifications to the client only if the client has enabled the Email notifications option in his User Preferences page. |
Action | Specify the approval action. |
Value | Description |
Approved | (Default). CentraSite sends an email message to the client when requests are approved. If you choose this option, you can use the predefined template APIKeyRenewalSuccess.html for approval notifications if you do not want to create an email template of your own. |
Approval Request | CentraSite sends an email message to the approver group(s) when requests are submitted for approval. If you choose this option, you can use the predefined template APIKeyRenewalPendingNotification.html for pending-approval notifications if you do not want to create an email template of your own. |
Rejected | CentraSite sends an email message to the client when requests are rejected. If you choose this option, you can use the predefined template RejectionNotification.html for rejection notifications if you do not want to create an email template of your own. |
13. In the Key Revocation Settings section, complete the following fields so that CentraSite will send emails when consumers request to have API keys revoked.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information fetched from the centrasite.xml file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message to the client. If you choose this option, you can use the predefined template APIKeyRevocationSuccess.html for success notifications if you do not want to create an email template of your own. Important: CentraSite sends notifications to the client only if the consumer has enabled the Email notifications option in his User Preferences page. |
14. Click the Configure button.
CentraSite internally creates and activates an API Key Generation Policy specific to the API. When a client registers as a consumer, this policy will start the process of approving and generating the API key.