OAuth2

Contains the access_token extracted from the most recent successful token response. It is updated after a successful authorization-code exchange or refresh-token request.

The access token is presented to the protected API, commonly in an HTTP header:

Authorization: Bearer ACCESS_TOKEN

Contains the raw response body returned by the token endpoint after a successful authorization-code exchange or refresh-token request.

Most providers return JSON similar to:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "...",
  "scope": "read write",
  "refresh_token": "..."
}

Some providers return form-encoded text instead of JSON. Use GetAccessTokenResponseSb when a StringBuilder destination is preferred.

Specifies a public HTTPS callback URL on an application-controlled web server when the provider will not redirect directly to localhost or a loopback IP address.

The intermediary endpoint receives the provider's redirect and forwards the complete callback, including code, state, error, and any provider-specific parameters, to the local listener used by Chilkat.

Reports the current state of the background authorization flow.

Specifies the authorization endpoint to which the user's browser is directed. StartAuth appends the client identifier, redirect URI, scope, state, PKCE values, and other configured authorization parameters.

Specifies the client identifier assigned when the application is registered with the authorization server. It identifies the application in authorization and token requests.

Specifies the client secret assigned to a confidential client by the authorization server. It is used when the provider requires the client to authenticate at the token endpoint.

Set to true to enable Proof Key for Code Exchange (PKCE) for the authorization-code flow. The default is false.

When enabled, Chilkat generates a high-entropy code verifier, sends its transformed challenge in the authorization request, and sends the original verifier during the token exchange.

Selects the PKCE transformation used when CodeChallenge is true.

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.

Controls automatic resolution of selected values from operating-system secure storage. The default is false.

When true, the following properties may contain a secret specification beginning with !! instead of a literal value:

• AuthorizationEndpoint
• TokenEndpoint
• ClientId
• ClientSecret

The specification has the form:

!![appName|]service[|domain]|username

Chilkat resolves the value through Windows Credential Manager on Windows or Apple Keychain on macOS.

Contains diagnostic information when AuthFlowState is 5. The value is cleared when StartAuth begins a new flow.

Use this property for failures in the listener, redirect processing, network connection, or token exchange. Provider-declared authorization denial is represented by state 4 and is normally available in AccessTokenResponse.

Set to true to include an OpenID Connect nonce parameter in the authorization request. The nonce is generated by Chilkat using the byte length specified by NonceLength. The default is false.

In OpenID Connect, the authorization server includes the nonce in the ID token so the client can associate that token with the authorization request and detect replay or token-substitution problems.

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.

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.

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.

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. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

Specifies the local TCP port on which Chilkat listens for the browser's OAuth redirect. Choose an available nonprivileged port, typically between 1024 and 65535.

The redirect URI registered with the provider must match the host, selected port, and terminating slash generated by this object. For example:

http://127.0.0.1:3017/

• Use http for a loopback redirect handled entirely on the local computer.
• Use LocalHost to select localhost or 127.0.0.1.
• Include the final / when registering the redirect URI.

Defines the inclusive end of a local-listener port range that begins with ListenPort. The default value of 0 disables range selection and uses only ListenPort.

When nonzero, Chilkat selects an available port in the inclusive range. For example, ListenPort=55110 and ListenPortRangeEnd=55117 permit ports 55110 through 55117.

Read ListenPortSelected to determine which port was used.

Returns the local port selected for the current or most recently completed authorization flow.

When a range is configured with ListenPortRangeEnd, use this value to determine the actual loopback redirect port. It is also available for the {listenPort} substitution supported by StateParam.

Selects the host name used in the loopback redirect URI:

The default is localhost. The value must match the redirect URI registered with the provider.

Specifies the number of random bytes used to generate the hexadecimal OpenID Connect nonce when IncludeNonce is true. The resulting string contains two hexadecimal characters per byte.

The default is 4 bytes, which produces an 8-character hexadecimal nonce.

Set to true to use the legacy out-of-band redirect URI urn:ietf:wg:oauth:2.0:oob. The application must obtain the displayed authorization code and pass it to ExchangeCodeForToken. The default is false.

Gets or sets the HTML response sent by Chilkat's local listener to the browser after authorization is granted and the redirect is accepted.

The default HTML immediately redirects the browser to Chilkat's confirmation page:

<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>

Replace this value to display application-specific instructions or redirect to a page operated by your organization.

Gets or sets the HTML response sent by Chilkat's local listener to the browser when the authorization server reports that access was denied.

The default HTML immediately redirects the browser to Chilkat's denial page:

<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>

Replace this value to display application-specific instructions or redirect to a page operated by your organization.

Contains the raw HTTP request received from the browser by Chilkat's local redirect listener. It is intended for troubleshooting callback and provider-parameter problems.

GET /?state=...&code=... HTTP/1.1
Host: 127.0.0.1:3017
User-Agent: ...
Accept: text/html,...

The value can include the request target, query or form parameters, and browser-supplied headers.

Gets or sets the refresh token used to obtain new access tokens. Chilkat populates this property when the token endpoint issues a refresh_token, and RefreshAccessToken reads it when creating a refresh request.

A provider may omit the refresh token unless an offline-access scope or provider-specific authorization parameter was requested. A refresh response may also return a replacement token.

Specifies an optional provider-defined resource parameter identifying the API or audience for which a token is requested.

This is used by some OAuth deployments, including older Microsoft identity endpoints and certain Dynamics configurations. Modern Microsoft v2 endpoints generally identify the target API through scope values instead.

Specifies the response mode requested from an OpenID Connect or provider-specific authorization endpoint.

Set to form_post to add response_mode=form_post, causing the authorization server to return parameters in an auto-submitted HTML form that sends an HTTP POST to the redirect URI. The default is an empty string, which omits the parameter and lets the provider choose its normal mode.

Specifies the authorization response type. The default is code, which requests an authorization code.

Set to id_token+code when a provider requires the OpenID Connect hybrid response response_type=id_token code; the plus sign is the URL-encoded representation of a SPACE in the query string.

Specifies the access scopes requested from the authorization server. A scope is a provider-defined permission or capability associated with the resulting access token.

OAuth scope values are commonly separated by a single SPACE character:

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

• openid requests OpenID Connect processing and an ID token when used with an appropriate response type.
• email and profile request standard OpenID Connect claims.
• The Google Drive URI requests read-only access to Drive files.

Allows the application to supply an explicit OAuth state value. Normally this property should remain empty so Chilkat generates a cryptographically random state value and validates the returned value automatically.

The automatically generated state is intentionally not exposed through this property.

The special token {listenPort} may appear in an explicitly supplied value. Chilkat replaces it with the actual listener port selected for the flow.

Specifies the provider's token endpoint. Chilkat sends authorization-code and refresh-token requests to this URL over TLS.

Contains the token_type value from the most recent successful token response. The common value is Bearer.

Provides a comma-separated list of specialized compatibility options. The default is an empty string and is appropriate for normal OAuth providers.

Controls how ClientId and ClientSecret are supplied during the authorization-code token exchange.

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"

Adds a name/value query parameter to the authorization URL produced by StartAuth. Call the method multiple times to add multiple provider-specific authorization parameters.

Typical examples include provider extensions such as access_type=offline, prompt=consent, or an account-selection hint.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Adds a provider-specific name/value parameter to requests sent by RefreshAccessToken. Call the method multiple times to add multiple parameters.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Adds a provider-specific name/value parameter to the authorization-code token request that Chilkat sends after receiving the browser redirect. Call the method multiple times to add multiple parameters.

This setting affects the code-for-token exchange performed by StartAuth or ExchangeCodeForToken; it does not alter the browser authorization URL or refresh-token requests.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Requests cancellation of the authorization flow currently running in the background thread.

Returns true if the cancellation request is accepted. After cancellation, inspect AuthFlowState and FailureInfo to determine the final state.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Exchanges the authorization code in code for tokens at TokenEndpoint.

This is used when the application obtains the authorization code outside Chilkat's local-listener workflow, most commonly with the legacy out-of-band mode selected by Oob. Configure the same client, endpoint, redirect, PKCE, and token-request settings that the provider requires for the original authorization request.

On success, the token properties and AccessTokenResponse are populated in the same manner as a successful background exchange.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Copies the raw token-endpoint response into sb and returns true on success.

This is the StringBuilder equivalent of reading AccessTokenResponse. The response is commonly JSON, but some providers return form-encoded or other text; this method does not guarantee JSON.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Returns the decoded value of param_name from the authorization redirect received by Chilkat's local listener.

Call this after the redirect has been received. It is useful for provider-specific parameters in addition to the standard code, state, and error values. For example, QuickBooks can return a company identifier named realmId:

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

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

Asks the operating system to open url in the user's default web browser. On Windows, macOS, and supported Linux desktop environments, an existing browser may open the URL in a new tab.

This method is typically called with the authorization URL returned by StartAuth. Returns false if the operating system cannot launch a browser or open the URL.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Sends a refresh-token grant request to TokenEndpoint to obtain a new access token without repeating interactive browser authorization.

Configure ClientId, RefreshToken, and TokenEndpoint, together with whatever client authentication the provider requires. This may include ClientSecret and UseBasicAuth.

On success, Chilkat updates AccessToken, TokenType, and AccessTokenResponse. If the provider rotates refresh tokens and returns a new refresh_token, RefreshToken is also updated.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Adds or replaces an HTTP request header used by subsequent calls to RefreshAccessToken. name is the header field name and value is its value.

Call this method once for each required header. Passing an empty value removes the named header.

Accept: application/json

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Suspends the calling thread for millisec milliseconds.

This convenience method is commonly used in a polling loop that checks AuthFlowState while the authorization flow continues on Chilkat's background thread.

Starts an OAuth 2.0 Authorization Code flow and returns the authorization URL that the application should open in the user's browser.

Before calling this method, configure ClientId, AuthorizationEndpoint, TokenEndpoint, the requested Scope, and the redirect-listener settings such as ListenPort. Configure ClientSecret only when the provider requires client authentication for this application type.

1. Chilkat constructs and returns the provider's authorization URL.
2. Chilkat starts a background thread that listens for the redirect request, validates the returned state, and exchanges the authorization code at the token endpoint.

Open the returned URL with LaunchBrowser or another browser-launch mechanism. Poll AuthFlowState until the flow reaches a terminal state.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

Associates sock with this object for HTTP connections to the token endpoint. This method is optional.

• Pass an unconnected Socket when it is configured with HTTP-proxy, SOCKS-proxy, local-bind, or other connection options that Chilkat should use when opening the token-endpoint connection.
• Pass an already connected socket when traffic must travel through an established SSH tunnel or another prebuilt connection.

Without this method, Chilkat opens a direct TLS connection to the token endpoint.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

Example

const Abort = struct {
    stop: std.atomic.Value(bool) = .init(false),
    pub fn abortCheck(self: *Abort) bool {
        return self.stop.load(.acquire); // another thread may call abort.stop.store(true, .release)
    }
};

var abort = Abort{};
o_auth2.setHeartbeatMs(250); // call abortCheck 4 times per second
o_auth2.setEventHandler(&abort);
defer o_auth2.clearEventHandler();

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

Example

const Progress = struct {
    pub fn percentDone(_: *Progress, pct: i32) bool {
        // pct ranges from 1 to 100.
        std.debug.print("Percent done: {d}\n", .{pct});
        return false; // return true to abort the method in progress
    }
};

var progress = Progress{};
o_auth2.setEventHandler(&progress);
defer o_auth2.clearEventHandler();

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

Example

const Info = struct {
    pub fn progressInfo(_: *Info, name: [:0]const u8, value: [:0]const u8) void {
        std.debug.print("{s}: {s}\n", .{ name, value });
    }
};

var info = Info{};
o_auth2.setEventHandler(&info);
defer o_auth2.clearEventHandler();