Configuring OAuth-Based Authentication

Edit online

About this task

The type of OAuth 2.0 authorization grant that CentraSite 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.

You configure the following information to enable OAuth 2.0 authentication:

  • 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.

To use OAuth 2.0 client credentials 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 client credentials (a client_id and client_secret).

  2. Request an OAuth 2.0 access token by passing the client credentials to the Mediator-hosted REST service mediator.oauth2.getOAuth2AccessToken. This service will provide an OAuth 2.0 access token to the client.
  3. To call the API, the client must pass their OAuth access token in an HTTP request header.

    An OAuth 2.0 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 API for OAuth-based client authentication

Procedure

  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:
    1. Click the chevron next to Assets option button.
    2. In the displayed list of asset types, select Virtual Service.
    3. 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 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 OAuth 2.0 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 OAuth 2.0 tokens that were generated using the authentication mechanism that you now intend to modify.

  8. In the Refresh Token After field, specify the maximum time that an OAuth 2.0 token will be valid for use with the API. The token automatically refreshes 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 OAuth 2.0 token will expire after 1 year, 2 months, 3 weeks, 7 days, 5 hours, 30 minutes, and 15 seconds.

    The default value of Unlimited denotes that the OAuth 2.0 token never expires.

  9. 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.
  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 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 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.
    • 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.

  12. Click the Configure button.

    When a client registers as a consumer, an approval request is sent to the approvers you specified above.