OAuth2

Once the OAuth2 authorization code flow successfully completes in the background thread, this property holds the access_token from the access token response. For example, a Google API access token looks like this:

ya29.a0AfH6SMC2z8Q1Z2X3Y ... 8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2

See the notes about PWideChar memory ownership and validity.

Once the OAuth2 authorization code flow successfully completes in the background thread, this property holds the access_token JSON. For instance, a successful X.com access token appears as follows:

{
  "token_type": "bearer",
  "expires_in": 7200,
  "access_token": "AAAAAAAAAAAAAAAAAAAAA...",
  "scope": "tweet.read tweet.write users.read offline.access",
  "refresh_token": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
}

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.

This property should only be set if the OAuth2 provider does not allow localhost or loopback (127.0.0.1) redirect URLs, or requires "https://" redirect URLs.

The AppCallbackUrl is a URL that is an endpoint on your own web server that will act as an Intermediary to redirect back to localhost. For more information, see Using Your Web Server as an Intermediary for OAuth2 Redirect to localhost.

See the notes about PWideChar memory ownership and validity.

Indicates the current stage of the OAuth2 authorization flow. Possible values:

• 0: Idle. No OAuth2 flow has been initiated.
• 1: Awaiting Redirect. The OAuth2 background thread is waiting for the browser's redirect HTTP request.
• 2: Awaiting Final Response. The OAuth2 background thread is waiting for the final access token response.
• 3: Success. The OAuth2 flow completed successfully. The background thread has exited, and the JSON response is available in the AccessTokenResponse property.
• 4: Access Denied. The OAuth2 flow completed, but access was denied. The background thread has exited, and the error JSON is available in the AccessTokenResponse property.
• 5: Failed. The OAuth2 flow failed before completion. The background thread has exited, and error details are available in the FailureInfo property.

You'll need to know the authorization and token endpoints for your OAuth2 provider. Set this property to the authorization endpoint. Some providers have both sandbox and production endpoints. Here are some sample endpoints:

See the notes about PWideChar memory ownership and validity.

Should be set to the Client ID assigned to your application when it is registered with an OAuth2 authorization server. It is used to identify the application making the authorization request.

See the notes about PWideChar memory ownership and validity.

Set this to the client secret assigned to an application when it is registered with an OAuth2 authorization server.

See the notes about PWideChar memory ownership and validity.

Set this to True to enable PKCE (Proof Key for Code Exchange). The default value is False.

This selects the code challenge method for PKCE, and applies only when the CodeChallenge property is set to True. The available options are "plain" and "S256", with "S256" as the default.

See the notes about PWideChar memory ownership and validity.

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

• A timeout property set to 0, indicating an infinite timeout.
• A hang occurring within an event callback in the application code.
• An internal bug in the Chilkat code causing the hang.

See the notes about PWideChar memory ownership and validity.

If the OAuth2 authorization fails before completion (AuthFlowState = 5), this property will contain failure details. It is automatically cleared when OAuth2 authorization begins (when StartAuth is called).

See the notes about PWideChar memory ownership and validity.

Optional. Set this to True to send a nonce with the authorization request. The length of the nonce is determined by the NonceLength property. The default value is False.

In OAuth, the nonce is a unique, random value included in the authorization request to prevent Replay Attacks:

• The nonce ensures that an authorization request cannot be reused by an attacker.
• It binds the authorization request to a specific instance, preventing malicious reuse.

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

See the notes about PWideChar memory ownership and validity.

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

See the notes about PWideChar memory ownership and validity.

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

See the notes about PWideChar memory ownership and validity.

Indicates the success or failure of the most recent method call: True means success, False means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages.

Set this to the port number to be used for receiving the redirect request from the local browser. Use a port in the range 1024 to 65535 to avoid conflicts with reserved system ports. Avoid well-known ports like 80, 443, 22, etc., as they are used by system services.

Note: The chosen port number determines the redirect URL defined for your app in the OAuth2 provider's developer portal. For example, if port 3017 is chosen, then your redirect URL should be http://localhost:3017/.

Note:

• You must use http:, not https:. Because the browser and your application are running on the same machine, the redirect request is handled entirely within the operating system. It never leaves the machine, so it cannot be intercepted on the network.
• The / terminating the redirect URL is critical and must be included. Do not omit it, otherwise the OAuth2 authorization will fail.
• If the LocalHost property (see below) is set to 127.0.0.1, then the redirect URL defined for your App in the OAuth2 provider's developer portal should use 127.0.0.1 instead of localhost. For example: http://127.0.0.1:3017/

This property allows for a range of listen port numbers to be used. If set to a non-zero value, then Chilkat will use an unused port in the range from ListenPort to ListenPortRangeEnd.

For example, if ListenPort=55110 and ListenPortRangeEnd=55117, then define the following redirect URL's for your app in the OAuth2 provider's developer portal:

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

This is a read-only property that gets set when the OAuth2 authorization flow completes. It contains the port number that was used when receiving the redirect callback.

Chooses between http://localhost:{portNumber}/ or http://127.0.0.1:{portNumber}/ to be used for the redirect (callback) URL. The default value is localhost. An application can change this property to 127.0.0.1 if desired. See the X.com example linked below, which uses http://127.0.0.1:3017/.

See the notes about PWideChar memory ownership and validity.

The nonce length, measured in bytes, is defined here. A nonce is included only when the IncludeNonce property is set to True. Since the nonce is a hexadecimal string, its character length is double its byte length. By default, the nonce is 4 bytes long.

Set to True if the redirect URI is to be set to urn:ietf:wg:oauth:2.0:oob and the authorization code will be supplied manually and passed to ExchangeCodeForToken. The default value is False.

This is for the Out-of-Band) flow, which is a legacy flow where the authorization code is delivered to the client application through an out-of-band mechanism, such as manually copying and pasting the code, rather than being automatically redirected via a "redirect_uri". This flow was historically used for applications that couldn't securely handle redirects, such as native or mobile apps, but it has largely been deprecated in favor of more secure flows like PKCE (Proof Key for Code Exchange).

This property holds the HTML displayed in the browser when the end-user grants access. By default, it includes a META refresh directing to https://www.chilkatsoft.com/oauth2_allowed.html. Your application can modify this HTML to show any content when access is granted. You might want to change the refresh URL to a page on your company’s website or use simple HTML to display custom information without redirection.

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>

See the notes about PWideChar memory ownership and validity.

This property holds the HTML displayed in the browser when the end-user denies access. By default, it includes a META refresh directing to https://www.chilkatsoft.com/oauth2_denied.html. Your application can modify this HTML to show any content when access is granted. You might want to change the refresh URL to a page on your company’s website or use simple HTML to display custom information without redirection.

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>

See the notes about PWideChar memory ownership and validity.

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

Here is a sample:

GET /?state=lW6hdb-jSR2ntNCZ9NMzVozWaxuSpkaSLs8SZCDZsjI&code=NU1nbUN ...... FjOjE HTTP/1.1
Host: 127.0.0.1:3017
Connection: keep-alive
sec-ch-ua: "Not(A:Brand";v="99", "Microsoft Edge";v="133", "Chromium";v="133"
sec-ch-ua-mobile: ?0
sec-ch-ua-platform: "Windows"
DNT: 1
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36 Edg/133.0.0.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
Sec-Fetch-Site: cross-site
Sec-Fetch-Mode: navigate
Sec-Fetch-User: ?1
Sec-Fetch-Dest: document
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.9

See the notes about PWideChar memory ownership and validity.

Once the OAuth2 authorization code flow successfully completes in the background thread, this property holds the refresh_token from the access token response. For example, an X.com refresh token looks like this:

NmJjUC1aX2VDZnFzaE5ObFp ..... OjE3NDAxNzM0MTcyNjI6MTowOnJ0OjE

See the notes about PWideChar memory ownership and validity.

This optional setting specifies the resource query parameter. For instance, set it to https://graph.microsoft.com/ for Microsoft Graph API calls. It is also needed for Microsoft Dynamics CRM OAuth authentication.

See the notes about PWideChar memory ownership and validity.

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.

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.

In OAuth2, scopes are permissions that specify what access level the client application is requesting for a user's resources. Scopes are included in the authorization request to ask for specific permissions. The user reviews and consents to these scopes before authorization.

Scopes are typically formatted with a SPACE char separating each requested scope. Here's an example for Google Drive:

openid email profile https://www.googleapis.com/auth/drive.readonly

• "openid": Access to basic profile information.
• "email": Access to the user’s email address.
• "profile": Access to the user's profile information.
• "drive.readonly": Read-only access to Google Drive files.

See the notes about PWideChar memory ownership and validity.

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.

You'll need to know the authorization and token endpoints for your OAuth2 provider. Set this property to the token endpoint. Some providers have both sandbox and production endpoints. Here are some sample endpoints:

See the notes about PWideChar memory ownership and validity.

Once the OAuth2 authorization code flow successfully completes in the background thread, this property holds the token_type from the AccessTokenResponse.

See the notes about PWideChar memory ownership and validity.

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.

When set to True, the internal POST request that exchanges the code for an access token will include the client_id/client_secret in an Authorization Basic ... header, using the client_id as the login and the client_secret as the password. By default, this setting is False, meaning the client_id/client_secret are sent as query parameters.

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.

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

See the notes about PWideChar memory ownership and validity.

Adds a custom query parameter (name=value) to the URL returned by the StartAuth method. This accommodates OAuth installations requiring custom query parameters. You can call this method multiple times, adding one query parameter per call.

Returns True for success, False for failure.

Adds a query parameter (name=value) to the HTTP request sent by the RefreshAccessToken method. You can call this method multiple times to add more query parameters.

Returns True for success, False for failure.

Adds a custom query parameter (name=value) to the internal request used to exchange the authorization code for a token, accommodating OAuth setups that require non-standard parameters. This method can be called multiple times to add multiple query parameters.

Returns True for success, False for failure.

Stops an ongoing OAuth2 authorization flow.

Returns True for success, False for failure.

This method is specifically for the OOB (Out-of-Band) authorization flow, where you manually obtain and pass the authorization code to complete the OAuth2 process.

Returns True for success, False for failure.

Creates an asynchronous task to call the ExchangeCodeForToken method with the arguments provided.

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

Same as the AccessTokenResponse property, but returns the JSON in the sb.

Returns True for success, False for failure.

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.

See the code snippet at the very bottom of the example linked below.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

Launches the default browser and navigated to url. If a browser window is already open, the page will be displayed in a new tab. This works on Windows, MacOS, and Linux.

Returns True for success, False for failure.

Loads the caller of the task's async method.

Returns True for success, False for failure.

This deprecated method observes an ongoing OAuth2 authorization flow and returns when it completes. It will be removed in a future major release. Instead of using this method, regularly check if the AuthFlowState property is greater than or equal to 3. If there's no browser response, cancel the waiting background thread by calling the Cancel method.

Returns True for success, False for failure.

Creates an asynchronous task to call the Monitor method with the arguments provided.

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

To obtain a new access token, this method sends a refresh token request to the token endpoint. Upon success, it updates the AccessToken and RefreshToken properties with new values. Note: This method requires valid values for the ClientId, ClientSecret, RefreshToken, and TokenEndpoint properties.

For a deeper understanding, see OAuth2 Refresh Token Request Explained

Returns True for success, False for failure.

Creates an asynchronous task to call the RefreshAccessToken method with the arguments provided.

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

Allows you to add HTTP request headers to the HTTP request sent by the RefreshAccessToken method. For instance, to include the "Accept: application/json" header, use this method with name as "Accept" and value as "application/json". To add multiple headers, call this method separately for each header. To remove a header, set name to the header name and value to an empty string.

Returns True for success, False for failure.

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

This method initiates the OAuth2 authorization code flow. Set the following properties before calling this method: ClientId, ClientSecret, ListenPort, Scope, AuthorizationEndpoint, and TokenEndpoint. Note that ClientSecret may not be required if the OAuth2 provider supports Proof Key for Code Exchange (PKCE). This method performs two actions:

1. It generates and returns a URL to be opened in a browser.
2. It launches a background thread that listens on the specified ListenPort for the browser's redirect request. The entire process of handling this request and completing the OAuth2 authorization flow is managed in the background thread within Chilkat.

The method's return value is the URL to open in a browser.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

Calling this method is optional and only necessary if you need to use a proxy (HTTP or SOCKS), an SSH tunnel, or specific socket options for the connection. If you do not use this method, the connection to the token endpoint will be a direct one using TLS. The method assigns the socket object for sending requests to the token endpoint in the background thread. You can pass either a connected or unconnected socket as sock. For SSH tunnels, sock must already be connected, whereas for setting options like HTTP or SOCKS proxies, an unconnected sock is sufficient.

Returns True for success, False for failure.

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)

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)

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.

Called in the background thread when an asynchronous task completes.