Component Interactions
The following diagram illustrates the logical view of interaction between various components that participate in an OAuth protected data request:
The interactions between components of the OAuth server are explained as follows:
- Request Data from API Service
When a resource is protected by OAuth, a resource owner may allow a relying party such as an API explorer or a client application to get the resource on behalf of the resource owner. In a typical OAuth scenario, the resource owner sends the request from a user agent, such as a browser, to the relying party.
- Requesting Access Token
When the relying party, such as a client application, that is serving the request, receives the request from the resource owner, the application requests an access token from the authorization server. The client application uses one of the following authorization flows to obtain the access token:
For details of the call for various flows, refer to the RFC 6749, "The OAuth 2.0 Authorization Framework " available at the following location:
- Login and Grant Access
In the authorization code flow scenario, to authenticate the resource owner, the authorization server delegates the authentication process to an Identity Service Provider. After a successful login, the Identity Service Provider returns the owner credentials to the authorization server. The authorization server then makes another request to the authentication server to enable the logged in owner to grant access to the client. When the access is granted to the client, the authorization server generates an authorization code and returns the code to the relying party.
- Redirect
When authenticating the user credentials, the owner adapter redirects the login request and grants access request to a browser.
-
Authenticate Owner and Retrieve Attributes
TIBCO API Exchange Gateway uses the owner adapter to perform the user authentication. The adapter may authenticate the owner using LDAP, database, or an SSO provider such as PingFederate™ via custom owner adapter. The successful authentication of owner returns the attributes of the owner such as owner’s DN, email, and telephone. Refer to Owner Service Provider Interface for details.
By default, TIBCO API Exchange Gateway provides the flat file and LDAP based adapter. The OAuth server provides an interface to use the custom owner adapter.
See OAuth Service Provider Interface for details on how to implement the custom adapters.
-
Authenticate Client and Retrieve Attributes
The authorization server authenticates the client credentials. The successful authentication of the client returns the attributes such as redirect URL, scopes to the authorization server.
Note: You can use the client adapter provided by TIBCO API Exchange Manager. See Enabling OAuth for Application using TIBCO API Exchange Manager. - Sending Request with Access Token
When the relying party, such as a client application, has an access token the application forwards the request to get the resource by passing the access token in the request.
-
Assigning Scope to Resource
To perform the resource authorization at runtime, the resource server relies on resource manager to provide information required to perform the authorization.
For example, the resource manager is the TIBCO API Exchange Gateway where the resources such as a facade operation is associated with an API key (client ID).
To authorize a partner for a specific operation, a scope is assigned to a partner operation. When authorizing a request with an access token, the owner of the access token is used to lookup the partner for the request. The client ID of the access token is used as the API key of the request. A partner operation is retrieved using the partner, API key, and the URI of the request. In order to authorize the operation, the operation must have the scope that matches all of the scopes from the access token.
The scope adapter is responsible to return the scopes associated with a facade operation.
- Validate Access Token
Before the TIBCO API Exchange Gateway resource server forwards the request from the relying parting to the API provider, the resource server validates the access token from the request to ensure that the access token is valid. The request is authorized based on the information obtained from the access token.
To validate the access token, the resource server sends the access token to the authorization sever to retrieve the data associated with the access token. The access token is valid when any one of the folllowing scenarios is true:- It is issued by the authorization server.
- It is not expired.
- It is able to retrieve the scopes for the resource that are associated with the token.
- If the access token is not valid, the request is terminated, and an error is returned to the relying party.
- If the access token is valid, the owner of the access token is used to find the partner of the operation and the request is processed as follows:
- If the partner is not found using the owner, the request is returned with a partner identification error.
- The client of the operation is used to find the partner operation. If partner operation is not found, the request is returned with a partner operation not found error.
- The partner operation must have the scope associated with the access token. If the partner operation does not have a scope that matches the one with the access token, the request is returned with scope mismatch error.
-
Forward Request with Access Token
If the owner, client, and scopes of the access token are valid for the facade operation, the resource server forwards the access token or, alternatively, converts the access token to a SAML assertion and forwards the assertion in the HTTP header.