Access Token Management
CentraSite provides a simple token-based authentication for providers to flexibly secure applications (APIs) and for consumers to easily access the data of the secured applications. The token-based authentication secures an application based on a security token that is generated for the user on authentication and then stores the token secure on the client.
CentraSite supports two types of token-based authentication:
API Keys: The type of access key authorization grant that Mediator supports is
API Keys. API keys 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.
The API Provider (and users with an instance-level Modify permission on an API at a minimum) can enforce API key authentication by configuring the API Asset Details page. Such users can configure the following characteristics about client requests for API keys:
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.
Clients that want to use the API key to call (consume) an API in CentraSite must:
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.
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.
OAuth 2.0 Tokens: The type of OAuth2 authorization grant that Mediator supports is
OAuth 2.0 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.
The API Provider (and users with an instance-level Modify permission on an API at a minimum) can enforce OAuth 2.0 authentication by configuring the API Asset Details page. Such users can configure the following characteristics about the approval process of 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:
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).
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.
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.
Note: | Instructions throughout the remainder of this section use the term access tokens when referring to API keys and OAuth 2.0 tokens in general. |
Access Token Request for an API Through API Portal Gateway
An API Provider restricts the access to an API by enforcing the appropriate access tokens. If the API that is exposed in an API Portal gateway enforces an access token, any user who requests access to the data of the exposed API gets an option to request for the access token of one of the type - API key or OAuth 2.0.
The access token request for an API through the API Portal gateway is a three step process in CentraSite.
1. Client creation process: Whenever a client requests an access token for an API in API Portal, CentraSite receives the request for the API access token, and processes the request. CentraSite checks if the client who made the access token request already exists in the CentraSite registry. If the client already exists in the registry, then CentraSite generates an access token entry in the registry. However, if the client does not exist in the registry, CentraSite performs the client creation process. During this process CentraSite registers the client as a member of the consumer organization configured for the registered API Portal in the CentraSite registry.
2. Access token generation process: After a client (API Portal user) is successfully created in the registry, CentraSite generates the access token and usage details for the API.
If an approval process is configured for access token generation, CentraSite initiates the approval process and submits the client's request to the designated group of approvers. Approvers receive the approval request in the Pending Approval Requests of 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 for their approval. CentraSite does not execute the client's requested operation until it obtains the necessary approvals. If an approver rejects the request, the requested access token is not generated.
3. Notification process: In the event of a success of the access token request, CentraSite returns a success message with details about the newly generated access token to API Portal, and notifies the client (including data that is pertinent to the access token validity and usage of the API) through email. In the event of a failure of the access token request, CentraSite notifies the client about the failed request.
Similarly, when those clients subsequently request for renewal or revocation of the access key, CentraSite verifies the client credentials, performs the requested operation, and notifies the API Portal and client.
Points to keep in mind when API Portal is used with CentraSite:
When a client requests for an access token from
API Portal,
CentraSite generates an User object entry in the registry that describes the client, and then stores the user entry in the repository. This user is not allowed to log into
CentraSite or perform any operation in
CentraSite.
CentraSite automatically associates the users with the
API Portal's
Consumer Organization. This
Consumer Organization property, which is configured during the registration of an
API Portal with
CentraSite, specifies the organization to which the new user is added.
The consumer organization owns the users from an
API Portal. You cannot delete this consumer organization, unless you belong to a
CentraSite Administrator role.
You cannot delete an
API Portal user from the registry, unless you belong to a
CentraSite Administrator role.
If you are the owner of the API asset or the access token itself, you have permission to renew and revoke access token that is available to you. If you are the
CentraSite Administrator, you have the permission to renew and revoke any access token on the
CentraSite server.
