C
C
Using the OAuth2 Authorization Token in REST API Calls
See more OAuth2 Examples
Demonstrates how to use an OAuth2 authorization token in REST API calls after obtaining it.Chilkat C Downloads
#include <C_CkJsonObject.h>
#include <C_CkHttp.h>
#include <C_CkHttpRequest.h>
#include <C_CkHttpResponse.h>
#include <C_CkRest.h>
#include <C_CkStringBuilder.h>
void ChilkatSample(void)
{
BOOL success;
HCkJsonObject json;
const char *accessToken;
HCkHttp http;
const char *responseStr;
HCkHttpRequest req;
HCkHttpResponse resp;
HCkRest rest;
HCkStringBuilder sbAuthHeaderVal;
success = FALSE;
// This example assumes the Chilkat API to have been previously unlocked.
// See Global Unlock Sample for sample code.
// This example demonstrates how to include the OAuth2 authorization token in HTTP requests (REST API calls).
// An OAuth2 authorization token is typically in JSON format, and looks something like this:
// {
// "token_type": "Bearer",
// "scope": "openid profile User.ReadWrite Mail.ReadWrite Mail.Send Files.ReadWrite User.Read Calendars.ReadWrite Group.ReadWrite.All",
// "expires_in": 3600,
// "ext_expires_in": 3600,
// "access_token": "EwCQA8l6...rW5az09bI0C",
// "refresh_token": "MCZhZ...6jBNRcpuQW",
// "id_token": "eyJ0eXAi...kcuQQrT03jMyA",
// "expires_on": "1569281808"
// }
// A few notes about the JSON above:
//
// 1) Different OAuth2 implementations (servers) may have different JSON members.
// The important ones for this discussion are "access_token" and "refresh_token".
// These members should always be named exactly "access_token" and "refresh_token".
// (I've never seen them named differently, although I don't think it's a formal standard.)
//
// 2) The "id_token" is present if you obtained the OAuth2 authorization token including "openid" in the scope.
// It contains information about the user. It is a JWT (per the OIDC specification) and here is the Chilkat
// example for decoding the id_token.
//
// 3) If you don't have a "refresh_token" in your JSON, some REST API's require "offline_access" to be included
// in the scope when obtaining the OAuth2 token.
//
// 4) IMPORTANT: Quite often, access_token's are only valid for a limited amount of time. (Often just 1 hour (i.e. 3600 seconds)).
// When the access token expires, your HTTP request will fail with a 401 Unauthorized status response. This is where your application
// can automatically recover by fetching a new access_token and re-sending the request. I'll explain...
// Usually getting an OAuth2 token for a user requires interactive approval from the user in a browser.
// However, refreshing the access_token does NOT require user interaction. You should design
// your application to automatically recover from an expired access token by
// (A) Automatically fetch a new access_token using the refresh_token as shown in this example.
// (B) Persist the new JSON to wherever you're storing the access token, such as in a file or database record. You'll need it for the next time you refresh.
// (C) Update the http.AuthToken or rest.Authorization property (as shown below)
// (D) Re-send the request using the updated auth token.
// The above 4 steps (A, B, C, D) can be automatic such that the user never notices, except for a small delay in performance.
// When your application obtains the OAuth2 access token, it should store the JSON in persistent manner, such as in
// a file, a database record, etc. The "access_token" is used by your application when sending REST requests. Typically, it is sent
// in the Authorization request header. For example:
//
// Authorization: Bearer <token>
//
// -----
// Chilkat has two classes for sending HTTP requests. One is named "Http" and the other is named "Rest". Either can be used.
// Once you become familiar with both, you'll find that some requests are more convenient to code in one or the other.
//
// I'll demonstrate how to get the access_token from the JSON and add the Authorization header for both cases.
//
// ----
// ---- (1) Get the access_token ----
json = CkJsonObject_Create();
success = CkJsonObject_LoadFile(json,"qa_data/tokens/myToken.json");
if (success == FALSE) {
printf("%s\n",CkJsonObject_lastErrorText(json));
CkJsonObject_Dispose(json);
return;
}
// Get the access_token member.
accessToken = CkJsonObject_stringOf(json,"access_token");
// ----
// ---- (2) Demonstrate adding the "Authorization: Bearer <token>" header using Chilkat Http ----
http = CkHttp_Create();
// Setting the AuthToken property causes the "Authorization: Bearer <token>" header to be added to each request.
CkHttp_putAuthToken(http,accessToken);
// For example:
responseStr = CkHttp_quickGetStr(http,"https://example.com/someApiCall");
// Another example:
req = CkHttpRequest_Create();
CkHttpRequest_putHttpVerb(req,"POST");
CkHttpRequest_putContentType(req,"application/x-www-form-urlencoded");
// ...
resp = CkHttpResponse_Create();
success = CkHttp_HttpReq(http,"https://example.com/someApiCall",req,resp);
if (success == FALSE) {
printf("%s\n",CkHttp_lastErrorText(http));
CkJsonObject_Dispose(json);
CkHttp_Dispose(http);
CkHttpRequest_Dispose(req);
CkHttpResponse_Dispose(resp);
return;
}
// In both of the above cases, the "Authorization: Bearer <token>" header is automatically added to each request.
// ----
// ---- (3) Add the Authorization header using Chilkat Rest ----
rest = CkRest_Create();
success = CkRest_Connect(rest,"example.com",443,TRUE,TRUE);
// ...
// Set the Authorization property to "Bearer <token>"
sbAuthHeaderVal = CkStringBuilder_Create();
CkStringBuilder_Append(sbAuthHeaderVal,"Bearer ");
CkStringBuilder_Append(sbAuthHeaderVal,accessToken);
CkRest_putAuthorization(rest,CkStringBuilder_getAsString(sbAuthHeaderVal));
// All requests sent by the rest object will now include the "Authorization: Bearer <token>" header.
// For example:
responseStr = CkRest_fullRequestNoBody(rest,"GET","/someApiCall");
CkJsonObject_Dispose(json);
CkHttp_Dispose(http);
CkHttpRequest_Dispose(req);
CkHttpResponse_Dispose(resp);
CkRest_Dispose(rest);
CkStringBuilder_Dispose(sbAuthHeaderVal);
}