The OAuth 2.0 authentication process is described by the following diagram:
In the diagram, step
6 represents the end of authentication and the actual communication with
the API (extraction of data) may begin.
The final authorization section of the Generic Extractor configuration is generated between
6. When a component is registered, steps
6 of the process are handled by
KBC (and the end-user).
To develop and test a new component with the OAuth authorization, go through
6 manually. At step
5, you will obtain a response which needs to be put
authorization.oauth_api.credentials.data section of the configuration. The response can be
either plaintext or a JSON. Let’s say you obtain a simple plaintext string:
The following configuration needs to be supplied to Generic Extractor:
authorization field has a single property
oauth_api with a single property
has three child properties:
#data— contains the response from the service provider; the response is a plaintext string or a JSON string (not an object!).
appKey— contains the Client ID (use an empty string if not used by the service provider).
#appSecret— contains the Client Secret (use an empty string if not used by the service provider).
Note that the properties
#appSecret must exist even if not used by the API; set them
to empty strings. For more information about OAuth 2, see the official documentation
or learn more about KBC-OAuth integration.
The following configuration parameters are supported for the
oauth20 authentication type:
format(optional, string) — If the OAuth service provider response is JSON, use the only possible value –
json. Otherwise do not specify format at all (plaintext is assumed).
headers(optional, object) — Object whose properties represent the key-value pairs of the URL query.
query(optional, object) — Object whose properties represent the key-value pairs sent as HTTP headers.
At least one of the
query options should always be specified; otherwise no authentication
will be sent with the API requests. Both fields also allow and practically require using
functions to generate an OAuth signature. Specific authentication values
are available in the OAuth function context.
The following two examples demonstrate the support for OAuth 2 in Generic Extractor.
The most basic OAuth authentication method is with “Bearer Token”. If you have an API which supports this authentication method, the following configuration can be used:
The response obtained from the service provider (the API) is a plaintext string
is simply a token to be used to access other API calls. The
api.authentication.headers section creates
Authorization: Bearer SomeToken1234abcd567ef using the
See example [EX103].
If you have an API which requires an HMAC signed token, generate the correct signature using functions. The following example assumes you obtain the following response from the API upon authentication:
The user token is represented by the
access_token and the token secret (MAC secret) is contained in the
mac_secret property. The following configuration generates the MAC signed
The above configuration generates the following header:
Authorization: MAC id="testToken", ts="1492958193", nonce="605cce2a2f687253", mac="ae96f93def8f02770f30e858e074b2a7
The configuration probably looks rather complicated. Most of it is to generate the
mac value in the above header.
The first step is the
implode function generating a
Normalized request string. This is then
passed to the
hash_hmac function along with the
sha256 (specifying the hashing algorithm) and the hashing key taken from the
data.mac_secret. The last (topmost) step is the
concat function; it
concatenates all parts of the
See example [EX104].