Configuring the API Consumption Settings for OAuth2 Authentication
The type of OAuth2 authorization grant that Mediator supports is “Client Credentials”. Client credentials are used as an authorization grant when the client is requesting API to protected resources based on an authorization previously arranged with the authorization server. That is, the client application gains authorization when it successfully registers with CentraSite as a consumer.
In this task, you configure the following characteristics for granting OAuth2 client credentials:
Specify the approval requirements for client requests for client credentials.
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.
Clients that want to use the OAuth2 protocol to call APIs in CentraSite must:
1. Register as a consumer for the API, as specified in Run-Time Governance with CentraSite.
When the client registration request is approved, the client receives client credentials (a client_id and client_secret).
2. Request an OAuth2 access token by passing the client credentials to the Mediator-hosted REST service mediator.oauth2.getOAuth2AccessToken. This service will provide an OAuth2 access token to the client. For more information about this service, see Run-Time Governance with CentraSite.
3. To call the API, the client must pass their OAuth access token in an HTTP request header.
An OAuth2 token is a unique token that a client uses to invoke APIs using the OAuth 2.0 protocol. The token contains an identifier that uniquely identifies the client. The use of a token establishes the client's identity and is used for both the authentication and authorization.
To configure the API Consumption Settings for OAuth 2.0 authentication
1. In CentraSite Business UI, display the details page for the API whose OAuth 2.0 token settings you want to configure. For procedures, see Viewing Details for an API. 2. In the actions bar for the API, click API Consumption Settings.
3. In the API Consumption Settings dialog, select OAuth2.
You might wish to modify the authentication type for an API at a later stage. When modifying the authentication type (say, API Keys), if the API has one or more OAuth2 tokens 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 OAuth2 tokens that were generated using the authentication mechanism that you now intend to modify.
4. In the Refresh Token After field, type the period of time after which Mediator should refresh the token after it expires.
This field is optional. The default value "Unlimited" denotes that the token never expires.
5. Select the Require Approval checkbox if you want to initiate an approval workflow for generating the client credentials.
When a client request 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.
6. 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. |
For more information on approval management, see
Working with Approval Workflows.
7. In the Key Generation Settings section, complete the following fields so that CentraSite will send emails when a client requests a token.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information from the centrasite.xml properties 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 another template, use the plus button to add additional rows. Important: | CentraSite sends notifications about a request status 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 clients 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 group(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 clients 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. |
8. Click the Configure button.
When a client registers as a consumer, an approval request is sent to the approvers you specified above.
