OAuth2 Delphi DLL Reference Documentation

OAuth2

Current Version: 10.0.0

Implements OAuth2 authorization for desktop (installed) applications, scripts, etc. These are applications that run on a computer where it is possible to popup a browser window, or embed a browser window, to allow the end-user to interactively grant or deny authentication.

In OAuth 2.0 terms, the application is considered to be a "public" client type, or a "native application". (In OAuth 2.0 terminology, a fully managed .NET desktop application is still a "native application".) This OAuth2 API helps implement the "Authorization Code Grant" flow to obtain both access tokens and refresh tokens. See Section 4.1 of RFC 6749.

In other commonly used terminology, this OAuth2 class helps to implement "Three Legged" OAuth2 Authorization. See http://oauthbible.com/#oauth-2-three-legged

Create/Dispose

var
myObject: HCkOAuth2;

begin
myObject := CkOAuth2_Create();

// ...

CkOAuth2_Dispose(myObject);
end;
function CkOAuth2_Create: HCkOAuth2; stdcall;

Creates an instance of the HCkOAuth2 object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

procedure CkOAuth2_Dispose(handle: HCkOAuth2); stdcall;

Objects created by calling CkOAuth2_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

Properties

AccessToken
procedure CkOAuth2_getAccessToken(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putAccessToken(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__accessToken(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

When the OAuth2 three-legged authorization has successfully completed in the background thread, this property contains the access_token.

For example, a successful Google API JSON response looks like this:

 {
             "access_token": "ya29.Ci9ZA-Z0Q7vtnch8xxxxxxxxxxxxxxgDVOOV97-IBvTt958xxxxxx1sasw",
             "token_type": "Bearer",

            "expires_in": 3600,

            "refresh_token": "1/fYjEVR-3Oq9xxxxxxxxxxxxxxLzPtlNOeQ"
}

See the notes about PWideChar memory ownership and validity.

top
AccessTokenResponse
procedure CkOAuth2_getAccessTokenResponse(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__accessTokenResponse(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

When the OAuth2 three-legged authorization has completed in the background thread, this property contains the response that contains the access_token, the optional refresh_token, and any other information included in the final response. If the authorization was denied, then this contains the error response.

For example, a successful JSON response for a Google API looks like this:

 {
             "access_token": "ya29.Ci9ZA-Z0Q7vtnch8xxxxxxxxxxxxxxgDVOOV97-IBvTt958xxxxxx1sasw",
             "token_type": "Bearer",

            "expires_in": 3600,

            "refresh_token": "1/fYjEVR-3Oq9xxxxxxxxxxxxxxLzPtlNOeQ"
}

Note: Not all responses are JSON. A successful Facebook response is plain text and looks like this:

access_token=EAAZALuOC1wAwBAKH6FKnxOkjfEP ... UBZBhYD5hSVBETBx6AZD&expires=5134653

See the notes about PWideChar memory ownership and validity.

top
AppCallbackUrl
procedure CkOAuth2_getAppCallbackUrl(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putAppCallbackUrl(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__appCallbackUrl(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.73

Some OAuth2 services, such as QuickBooks, do not allow for "http://localhost:port" callback URLs. When this is the case, a desktop app cannot pop up a browser and expect to get the final redirect callback. The workaround is to set this property to a URI on your web server, which sends a response to redirect back to "http://localhost:3017". Thus the callback becomes a double redirect, which ends at localhost:port, and thus completes the circuit.

If the OAuth2 service allows for "http://localhost:port" callback URLs, then leave this property empty.

As an example, one could set this property to "https://www.yourdomain.com/OAuth2.php", where the PHP source contains the following:

<?php
  header( 'Location: http://localhost:3017?' . $_SERVER['QUERY_STRING'] );
?>

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top
AuthFlowState
function CkOAuth2_getAuthFlowState(objHandle: HCkOAuth2): Integer; stdcall;
Introduced in version 9.5.0.59

Indicates the current progress of the OAuth2 three-legged authorization flow. Possible values are:

0: Idle. No OAuth2 has yet been attempted.
1: Waiting for Redirect. The OAuth2 background thread is waiting to receive the redirect HTTP request from the browser.
2: Waiting for Final Response. The OAuth2 background thread is waiting for the final access token response.
3: Completed with Success. The OAuth2 flow has completed, the background thread exited, and the successful JSON response is available in AccessTokenResponse property.
4: Completed with Access Denied. The OAuth2 flow has completed, the background thread exited, and the error JSON is available in AccessTokenResponse property.
5: Failed Prior to Completion. The OAuth2 flow failed to complete, the background thread exited, and the error information is available in the FailureInfo property.

top
AuthorizationEndpoint
procedure CkOAuth2_getAuthorizationEndpoint(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putAuthorizationEndpoint(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__authorizationEndpoint(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

The URL used to obtain an authorization grant. For example, the Google APIs authorization endpoint is "https://accounts.google.com/o/oauth2/v2/auth". (In three-legged OAuth2, this is the very first point of contact that begins the OAuth2 authentication flow.)

See the notes about PWideChar memory ownership and validity.

top
ClientId
procedure CkOAuth2_getClientId(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putClientId(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__clientId(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

The "client_id" that identifies the application.

For example, if creating an app to use a Google API, one would create a client ID by:

  1. Logging into the Google API Console (https://console.developers.google.com).
  2. Navigate to "Credentials".
  3. Click on "Create Credentials"
  4. Choose "OAuth client ID"
  5. Select the "Other" application type.
  6. Name your app and click "Create", and a client_id and client_secret will be generated.
Other API's, such as Facebook, should have something similar for generating a client ID and client secret.

See the notes about PWideChar memory ownership and validity.

top
ClientSecret
procedure CkOAuth2_getClientSecret(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putClientSecret(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__clientSecret(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

The "client_secret" for the application. Application credentials (i.e. what identifies the application) consist of a client_id and client_secret. See the ClientId property for more information.

Is the Client Secret Really a Secret?

This deserves some explanation. For a web-based application (where the code is on the web server) and the user interacts with the application in a browser, then YES, the client secret MUST be kept secret at all times. One does not want to be interacting with a site that claims to be "Application XYZ" but is actually an impersonator. But the Chilkat OAuth2 class is for desktop applications and scripts (i.e. things that run on the local computer, not in a browser).

Consider Mozilla Thunderbird. It is an application installed on your computer. Thunderbird uses OAuth2 authentication for GMail accounts in the same way as this OAuth2 API. When you add a GMail account and need to authenticate for the 1st time, you'll get a popup window (a browser) where you interactively grant authorization to Thunderbird. You implicitly know the Thunderbird application is running because you started it. There can be no impersonation unless your computer has already been hacked and when you thought you started Thunderbird, you actually started some rogue app. But if you already started some rogue app, then all has already been lost.

It is essentially impossible for desktop applications to embed a secret key (such as the client secret) and assure confidentiality (i.e. that the key cannot be obtained by some hacker. An application can hide the secret, and can make it difficult to access, but in the end the secret cannot be assumed to be safe. Therefore, the client_secret, for desktop (installed) applications is not actually secret. One should still take care to shroud the client secret to some extent, but know that whatever is done cannot be deemed secure. But this is OK. The reason it is OK is that implicitly, when a person starts an application (such as Thunderbird), the identity of the application is known. If a fake Thunderbird was started, then all has already been lost. The security of the system is in preventing the fake/rogue applications in the 1st place. If that security has already been breached, then nothing else really matters.

See the notes about PWideChar memory ownership and validity.

top
CodeChallenge
function CkOAuth2_getCodeChallenge(objHandle: HCkOAuth2): wordbool; stdcall;
procedure CkOAuth2_putCodeChallenge(objHandle: HCkOAuth2; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.59

Optional. Set this to True to send a code_challenge (as per RFC 7636) with the authorization request. The default value is False.

top
CodeChallengeMethod
procedure CkOAuth2_getCodeChallengeMethod(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putCodeChallengeMethod(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__codeChallengeMethod(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

Optional. Only applies when the CodeChallenge property is set to True. Possible values are "plain" or "S256". The default is "S256".

See the notes about PWideChar memory ownership and validity.

top
DebugLogFilePath
procedure CkOAuth2_getDebugLogFilePath(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putDebugLogFilePath(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__debugLogFilePath(objHandle: HCkOAuth2): PWideChar; stdcall;

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top
FailureInfo
procedure CkOAuth2_getFailureInfo(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__failureInfo(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

If the OAuth2 three-legged authorization failed prior to completion (the AuthFlowState = 5), then information about the failure is contained in this property. This property is automatically cleared when OAuth2 authorization starts (i.e. when StartAuth is called).

See the notes about PWideChar memory ownership and validity.

top
IncludeNonce
function CkOAuth2_getIncludeNonce(objHandle: HCkOAuth2): wordbool; stdcall;
procedure CkOAuth2_putIncludeNonce(objHandle: HCkOAuth2; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.78

Optional. Set this to True to send a nonce with the authorization request. The default value is False.

More Information and Examples
top
LastErrorHtml
procedure CkOAuth2_getLastErrorHtml(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__lastErrorHtml(objHandle: HCkOAuth2): PWideChar; stdcall;

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

top
LastErrorText
procedure CkOAuth2_getLastErrorText(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__lastErrorText(objHandle: HCkOAuth2): PWideChar; stdcall;

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

top
LastErrorXml
procedure CkOAuth2_getLastErrorXml(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__lastErrorXml(objHandle: HCkOAuth2): PWideChar; stdcall;

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

top
LastMethodSuccess
function CkOAuth2_getLastMethodSuccess(objHandle: HCkOAuth2): wordbool; stdcall;
procedure CkOAuth2_putLastMethodSuccess(objHandle: HCkOAuth2; newPropVal: wordbool); stdcall;

Indicate whether the last method call succeeded or failed. A value of True indicates success, a value of False indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = True and failure = False.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to True. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
ListenPort
function CkOAuth2_getListenPort(objHandle: HCkOAuth2): Integer; stdcall;
procedure CkOAuth2_putListenPort(objHandle: HCkOAuth2; newPropVal: Integer); stdcall;
Introduced in version 9.5.0.59

The port number to listen for the redirect URI request sent by the browser. If set to 0, then a random unused port is used. The default value of this property is 0.

In most cases, using a random unused port is the best choice. In some OAuth2 situations, such as with Facebook, a specific port number must be chosen. This is due to the fact that Facebook requires an APP to have a Site URL, which must exactly match the redirect_uri used in OAuth2 authorization. For example, the Facebook Site URL might be "http://localhost:3017/" if port 3017 is the listen port.

top
ListenPortRangeEnd
function CkOAuth2_getListenPortRangeEnd(objHandle: HCkOAuth2): Integer; stdcall;
procedure CkOAuth2_putListenPortRangeEnd(objHandle: HCkOAuth2; newPropVal: Integer); stdcall;
Introduced in version 9.5.0.69

If set, then an unused port will be chosen in the range from the ListenPort property to this property. Some OAuth2 services, such as Google, require that callback URL's, including port numbers, be selected in advance. This feature allows for a range of callback URL's to be specified to cope with the possibility that another application on the same computer might be using a particular port.

For example, a Google ClientID might be configured with a set of authorized callback URI's such as:

  • http://localhost:55110/
  • http://localhost:55112/
  • http://localhost:55113/
  • http://localhost:55114/
  • http://localhost:55115/
  • http://localhost:55116/
  • http://localhost:55117/

In which case the ListenPort property would be set to 55110, and this property would be set to 55117.

top
ListenPortSelected
function CkOAuth2_getListenPortSelected(objHandle: HCkOAuth2): Integer; stdcall;
Introduced in version 9.5.0.94

If a listen port range was specified by setting both the ListenPort and ListenPortRangeEnd properties, then the StartAuth method will select and listen at an unused port in the range. After StartAuth is called, this property will contain the chosen port number.

top
LocalHost
procedure CkOAuth2_getLocalHost(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putLocalHost(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__localHost(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

Defaults to "localhost". This should typically remain at the default value. It is the loopback domain or IP address used for the redirect_uri. For example, "http://localhost:2012/". (assuming 2012 was used or randomly chosen as the listen port number) If the desired redirect_uri is to be "http://127.0.0.1:2012/", then set this property equal to "127.0.0.1".

See the notes about PWideChar memory ownership and validity.

top
NonceLength
function CkOAuth2_getNonceLength(objHandle: HCkOAuth2): Integer; stdcall;
procedure CkOAuth2_putNonceLength(objHandle: HCkOAuth2; newPropVal: Integer); stdcall;
Introduced in version 9.5.0.80

Defines the length of the nonce in bytes. The nonce is only included if the IncludeNonce property = True. (The length of the nonce in characters will be twice the length in bytes, because the nonce is a hex string.)

The default nonce length is 4 bytes.

top
RedirectAllowHtml
procedure CkOAuth2_getRedirectAllowHtml(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putRedirectAllowHtml(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__redirectAllowHtml(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

This property contains the HTML returned to the browser when access is allowed by the end-user. The default value is HTML that contains a META refresh to https://www.chilkatsoft.com/oauth2_allowed.html. Your application should set this property to display whatever HTML is desired when access is granted.

The default value of this property is:

<html>
  <head><meta http-equiv='refresh' content='0;url=https://www.chilkatsoft.com/oauth2_allowed.html'></head>
  <body>Thank you for allowing access.</body>
</html>

You may wish to change the refresh URL to a web page on your company website. Alternatively, you can provide simple HTML that does not redirect anywhere but displays whatever information you desire.

See the notes about PWideChar memory ownership and validity.

top
RedirectDenyHtml
procedure CkOAuth2_getRedirectDenyHtml(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putRedirectDenyHtml(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__redirectDenyHtml(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

The HTML returned to the browser when access is denied by the end-user. The default value is HTMl that contains a META refresh to https://www.chilkatsoft.com/oauth2_denied.html. Your application should set this property to display whatever HTML is desired when access is denied.

The default value of this property is:

<html>
  <head><meta http-equiv='refresh' content='0;url=https://www.chilkatsoft.com/oauth2_denied.html'></head>
  <body>The app will not have access.</body>
  </html>

You may wish to change the refresh URL to a web page on your company website. Alternatively, you can provide simple HTML that does not redirect anywhere but displays whatever information you desire.

See the notes about PWideChar memory ownership and validity.

top
RedirectReqReceived
procedure CkOAuth2_getRedirectReqReceived(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__redirectReqReceived(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.92

Contains the HTTP redirect request received from the local web browser. This is used for debugging.

See the notes about PWideChar memory ownership and validity.

top
RefreshToken
procedure CkOAuth2_getRefreshToken(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putRefreshToken(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__refreshToken(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

When the OAuth2 three-legged authorization has successfully completed in the background thread, this property contains the refresh_token, if present.

For example, a successful Google API JSON response looks like this:

 {
             "access_token": "ya29.Ci9ZA-Z0Q7vtnch8xxxxxxxxxxxxxxgDVOOV97-IBvTt958xxxxxx1sasw",
             "token_type": "Bearer",

            "expires_in": 3600,

            "refresh_token": "1/fYjEVR-3Oq9xxxxxxxxxxxxxxLzPtlNOeQ"
}

See the notes about PWideChar memory ownership and validity.

top
Resource
procedure CkOAuth2_getResource(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putResource(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__resource(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.67

This is an optional setting that defines the "resource" query parameter. For example, to call the Microsoft Graph API, set this property value to "https://graph.microsoft.com/". The Microsoft Dynamics CRM OAuth authentication also requires the Resource property.

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top
ResponseMode
procedure CkOAuth2_getResponseMode(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putResponseMode(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__responseMode(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.78

Can be set to "form_post" to include a "response_mode=form_post" in the authorization request. The default value is the empty string to omit the "response_mode" query param.

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top
ResponseType
procedure CkOAuth2_getResponseType(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putResponseType(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__responseType(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.78

The default value is "code". Can be set to "id_token+code" for cases where "response_type=id_token+code" is required in the authorization request.

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top
Scope
procedure CkOAuth2_getScope(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putScope(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__scope(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

This is an optional setting that defines the scope of access. For example, Google API scopes are listed here: https://developers.google.com/identity/protocols/googlescopes

For example, if wishing to grant OAuth2 authorization for Google Drive, one would set this property to "https://www.googleapis.com/auth/drive".

See the notes about PWideChar memory ownership and validity.

top
StateParam
procedure CkOAuth2_getStateParam(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putStateParam(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__stateParam(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.94

Allows the application to explicitly set the state parameter to a value. Typically this property should remain unset, and Chilkat will automatically generate a random state. (The generated random state is not reflected in this property. In other words, you can't get the random state that was generated by reading this property.)

Note: The special string "{listenPort}" can be included in the value of this property. Chilkat will replace "{listenPort}" with the actual listen port used. This can be useful if your application is listening on range of ports and you want the state param to include the chosen port.

See the notes about PWideChar memory ownership and validity.

top
TokenEndpoint
procedure CkOAuth2_getTokenEndpoint(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putTokenEndpoint(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__tokenEndpoint(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

The URL for exchanging an authorization grant for an access token. For example, the Google APIs token endpoint is "https://www.googleapis.com/oauth2/v4/token". (In three-legged OAuth2, this is the very last point of contact that ends the OAuth2 authentication flow.)

See the notes about PWideChar memory ownership and validity.

top
TokenType
procedure CkOAuth2_getTokenType(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putTokenType(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__tokenType(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

When the OAuth2 three-legged authorization has successfully completed in the background thread, this property contains the token_type, if present.

A successful Google API JSON response looks like this:

 {
             "access_token": "ya29.Ci9ZA-Z0Q7vtnch8xxxxxxxxxxxxxxgDVOOV97-IBvTt958xxxxxx1sasw",
             "token_type": "Bearer",

            "expires_in": 3600,

            "refresh_token": "1/fYjEVR-3Oq9xxxxxxxxxxxxxxLzPtlNOeQ"
}

Note: Some responses may not included a "token_type" param. In that case, this property will remain empty.

See the notes about PWideChar memory ownership and validity.

top
UncommonOptions
procedure CkOAuth2_getUncommonOptions(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
procedure CkOAuth2_putUncommonOptions(objHandle: HCkOAuth2; newPropVal: PWideChar); stdcall;
function CkOAuth2__uncommonOptions(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.85

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

Can be set to a list of the following comma separated keywords:

  • NO_OAUTH2_SCOPE - Do not includethe "scope" parameter when exchanging the authorization code for an access token.
  • ExchangeCodeForTokenUsingJson - Introduced in v9.5.0.98. Use an HTTP POST with JSON request body for the final exchange-code-for-token HTTP request in the authorization code flow.
  • RefreshTokenUsingJson - Introduced in v9.5.0.98. Use an HTTP POST with JSON request body for the token refresh HTTP request.

See the notes about PWideChar memory ownership and validity.

top
UseBasicAuth
function CkOAuth2_getUseBasicAuth(objHandle: HCkOAuth2): wordbool; stdcall;
procedure CkOAuth2_putUseBasicAuth(objHandle: HCkOAuth2; newPropVal: wordbool); stdcall;
Introduced in version 9.5.0.73

If set to True, then the internal POST (on the background thread) that exchanges the code for an access token will send the client_id/client_secret in an "Authorization Basic ..." header where the client_id is the login and the client_secret is the password.

Some services, such as fitbit.com, require the client_id/client_secret to be passed in this way.

The default value of this property is False, which causes the client_id/client_secret to be sent as query params.

More Information and Examples
top
VerboseLogging
function CkOAuth2_getVerboseLogging(objHandle: HCkOAuth2): wordbool; stdcall;
procedure CkOAuth2_putVerboseLogging(objHandle: HCkOAuth2; newPropVal: wordbool); stdcall;

If set to True, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is False. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
procedure CkOAuth2_getVersion(objHandle: HCkOAuth2; outPropVal: HCkString); stdcall;
function CkOAuth2__version(objHandle: HCkOAuth2): PWideChar; stdcall;

Version of the component/library, such as "9.5.0.94"

See the notes about PWideChar memory ownership and validity.

More Information and Examples
top

Methods

AddAuthQueryParam
function CkOAuth2_AddAuthQueryParam(objHandle: HCkOAuth2;
    name: PWideChar;
    value: PWideChar): wordbool; stdcall;
Introduced in version 9.5.0.85

Adds an additional custom query param (name=value) to the URL that is returned by the StartAuth method. This method exists to satisfy OAuth installations that require non-standard/custom query parms. This method can be called multiple times, once per additional query parm to be added.

Returns True for success, False for failure.

top
AddRefreshQueryParam
function CkOAuth2_AddRefreshQueryParam(objHandle: HCkOAuth2;
    name: PWideChar;
    value: PWideChar): wordbool; stdcall;
Introduced in version 9.5.0.97

Adds an additional query param (name=value) to the HTTP request sent in the RefreshAccessToken method. This method can be called multiple times, once per additional query parm to be added.

Returns True for success, False for failure.

top
AddTokenQueryParam
function CkOAuth2_AddTokenQueryParam(objHandle: HCkOAuth2;
    name: PWideChar;
    value: PWideChar): wordbool; stdcall;
Introduced in version 9.5.0.85

Adds an additional custom query param (name=value) to the request that occurs (internally) to exchange the authorization code for a token. This method exists to satisfy OAuth installations that require non-standard/custom query parms. This method can be called multiple times, once per additional query parm to be added.

Returns True for success, False for failure.

top
Cancel
function CkOAuth2_Cancel(objHandle: HCkOAuth2): wordbool; stdcall;
Introduced in version 9.5.0.59

Cancels an OAuth2 authorization flow that is in progress.

Returns True for success, False for failure.

top
GetRedirectRequestParam
function CkOAuth2_GetRedirectRequestParam(objHandle: HCkOAuth2;
    paramName: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkOAuth2__getRedirectRequestParam(objHandle: HCkOAuth2;
    paramName: PWideChar): PWideChar; stdcall;
Introduced in version 9.5.0.69

Some OAuth2 providers can provide additional parameters in the redirect request sent to the local listener (i.e. the Chilkat background thread). One such case is for QuickBooks, It contains a realmId parameter such as the following:

http://localhost:55568/?state=xxxxxxxxxxxx&code=xxxxxxxxxxxx&realmId=1234567890

After the OAuth2 authentication is completed, an application can call this method to get any of the parameter values. For example, to get the realmId value, pass "realmId" in paramName.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

top
LoadTaskCaller
function CkOAuth2_LoadTaskCaller(objHandle: HCkOAuth2;
    task: HCkTask): wordbool; stdcall;
Introduced in version 9.5.0.80

Loads the caller of the task's async method.

Returns True for success, False for failure.

top
Monitor
function CkOAuth2_Monitor(objHandle: HCkOAuth2): wordbool; stdcall;
Introduced in version 9.5.0.59

Monitors an already started OAuth2 authorization flow and returns when it is finished.

Note: It rarely makes sense to call this method. If this programming language supports callbacks, then MonitorAsync is a better choice. (See the Oauth2 project repositories at https://github.com/chilkatsoft for samples.) If a programming language does not have callbacks, a better choice is to periodically check the AuthFlowState property for a value >= 3. If there is no response from the browser, the background thread (that is waiting on the browser) can be cancelled by calling the Cancel method.

Returns True for success, False for failure.

top
MonitorAsync (1)
function CkOAuth2_MonitorAsync(objHandle: HCkOAuth2): HCkTask; stdcall;
Introduced in version 9.5.0.59

Creates an asynchronous task to call the Monitor method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
RefreshAccessToken
function CkOAuth2_RefreshAccessToken(objHandle: HCkOAuth2): wordbool; stdcall;
Introduced in version 9.5.0.59

Sends a refresh request to the token endpoint to obtain a new access token. After a successful refresh request, the AccessToken and RefreshToken properties will be updated with new values.

Note: This method can only be called if the ClientId, ClientSecret, RefreshToken and TokenEndpoint properties contain valid values.

Returns True for success, False for failure.

top
RefreshAccessTokenAsync (1)
function CkOAuth2_RefreshAccessTokenAsync(objHandle: HCkOAuth2): HCkTask; stdcall;
Introduced in version 9.5.0.59

Creates an asynchronous task to call the RefreshAccessToken method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
SetRefreshHeader
function CkOAuth2_SetRefreshHeader(objHandle: HCkOAuth2;
    name: PWideChar;
    value: PWideChar): wordbool; stdcall;
Introduced in version 9.5.0.77

Provides for the ability to add HTTP request headers for the request sent by the RefreshAccesToken method. For example, if the "Accept: application/json" header needs to be sent, then add it by calling this method with name = "Accept" and value = "application/json".

Multiple headers may be added by calling this method once for each. To remove a header, call this method with name equal to the header name, and with an empty string for value.

Returns True for success, False for failure.

top
SetRefreshHeaderAsync (1)
function CkOAuth2_SetRefreshHeaderAsync(objHandle: HCkOAuth2;
    name: PWideChar;
    value: PWideChar): HCkTask; stdcall;
Introduced in version 9.5.0.77

Creates an asynchronous task to call the SetRefreshHeader method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

top
SleepMs
procedure CkOAuth2_SleepMs(objHandle: HCkOAuth2;
    millisec: Integer) stdcall;
Introduced in version 9.5.0.59

Convenience method to force the calling thread to sleep for a number of milliseconds.

top
StartAuth
function CkOAuth2_StartAuth(objHandle: HCkOAuth2;
    outStr: HCkString): wordbool; stdcall;
function CkOAuth2__startAuth(objHandle: HCkOAuth2): PWideChar; stdcall;
Introduced in version 9.5.0.59

Initiates the three-legged OAuth2 flow. The various properties, such as ClientId, ClientSecret, Scope, CodeChallenge, AuthorizationEndpoint, and TokenEndpoint, should be set prior to calling this method.

This method does two things:

  1. Forms and returns a URL that is to be loaded in a browser.
  2. Starts a background thread that listens on a randomly selected unused port to receive the redirect request from the browser. The receiving of the request from the browser, and the sending of the HTTP request to complete the three-legged OAuth2 flow is done entirely in the background thread. The application controls this behavior by setting the various properties beforehand.
The return value is the URL to be loaded (navigated to) in a popup or embedded browser.

Note: It's best not to call StartAuth if a previous call to StartAuth is in a non-completed state. However, starting in v9.5.0.76, if a background thread from a previous call to StartAuth is still running, it will be automatically canceled. However,rather than relying on this automatic behavior, your application should explicity Cancel the previous StartAuth before calling again.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

top
UseConnection
function CkOAuth2_UseConnection(objHandle: HCkOAuth2;
    sock: HCkSocket): wordbool; stdcall;
Introduced in version 9.5.0.59

Calling this method is optional, and is only required if a proxy (HTTP or SOCKS), an SSH tunnel, or if special connection related socket options need to be used. When UseConnection is not called, the connection to the token endpoint is a direct connection using TLS (or not) based on the TokenEndpoint. (If the TokenEndpoint begins with "https://", then TLS is used.)

This method sets the socket object to be used for sending the requests to the token endpoint in the background thread. The sock can be an already-connected socket, or a socket object that is not yet connected. In some cases, such as for a connection through an SSH tunnel, the sock must already be connected. In other cases, an unconnected sock can be provided because the purpose for providing the socket object is to specify settings such as for HTTP or SOCKS proxies.

Returns True for success, False for failure.

top

Events

Chilkat supports event callbacks for the Delphi DLL starting in version 9.5.0.82.

AbortCheck
function MyAbortCheck(): Integer; cdecl;
Introduced in version 9.5.0.82

Provides the opportunity for a method call to be aborted. The AbortCheck event is fired periodically based on the value of the HeartbeatMs property. If HeartbeatMs is 0, then no AbortCheck events will fire. As an example, to fire 5 AbortCheck events per second, set the HeartbeatMs property equal to 200. Return True to abort; return False to continue (not abort)

More Information and Examples
top
PercentDone
function MyPercentDone(pctDone: Integer): Integer; cdecl;
Introduced in version 9.5.0.82

Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This event is only fired when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For operations (Chilkat method calls) that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).

The PercentDone callback counts as an AbortCheck event. For method calls that complete quickly such that PercentDone events fire, it may be that AbortCheck events don't fire because the opportunity to abort is already provided in the PercentDone callback. For time consuming operations, where the amount of time between PercentDone callbacks are long, AbortCheck callbacks may be used to allow for the operation to be aborted in a more responsive manner.

Return True to abort; return False to continue (not abort)

More Information and Examples
top
ProgressInfo
procedure MyProgressInfo(name: PWideChar; value: PWideChar) cdecl;
Introduced in version 9.5.0.82

A general name/value event that provides information about what is happening during a method call. To find out what information is available, write code to handle this event and log the name/value pairs. Most are self-explanatory.

More Information and Examples
top
TaskCompleted
procedure MyTaskCompleted(task: HCkTask) cdecl;
Introduced in version 9.5.0.82

Called in the background thread when an asynchronous task completes.

top