What the Class Is Used For

Use Chilkat.AuthGoogle when an application needs to authenticate HTTP requests to Google Cloud Platform APIs or Google Apps APIs using a service account. The class builds and signs the service-account JWT, sends the token request, and stores the resulting access token in AccessToken.

Service Account Authentication Obtain access tokens using a Google service account rather than an interactive browser login.

JSON or P12 Key Use JsonKey or SetP12 to provide the private key material.

Scoped Access Set Scope to the space-delimited list of requested Google API permissions.

Use with Rest Use the resulting token or credential object with Chilkat.Rest when making authenticated Google API requests.

Use with Chilkat.Rest

AuthGoogle is used as a way to specify credentials for HTTP requests to Google Cloud Platform APIs and Google Apps APIs using a service account in the Chilkat.Rest class. The AuthGoogle object obtains the access token, and Chilkat.Rest performs the actual HTTP requests to the Google API endpoints.

Responsibility	Handled By	Description
Configure service-account identity	AuthGoogle	Uses the service account email and private key information from either a JSON key or P12 key configuration.
Request Google API permissions	AuthGoogle	Uses Scope to specify the Google API permissions requested by the application.
Obtain the access token	AuthGoogle	Calls ObtainAccessToken to fetch an access token and store it in AccessToken.
Send Google API requests	Chilkat.Rest	Sends HTTP requests to Google Cloud Platform or Google Apps APIs using the service-account access token.

Practical role: Think of AuthGoogle as the service-account credential object used to obtain and supply Google API access tokens for Chilkat.Rest requests.

Service Account vs 3-Legged OAuth2

Scenario	Use This Class	Why
Server-to-server Google API access using a service account	Chilkat.AuthGoogle	This class is designed for Google service account authentication.
Interactive user consent in a browser	Chilkat.OAuth2	For 3-legged OAuth2, where the Google account owner must interactively grant permission in a browser, use the Chilkat OAuth2 class instead.

Important distinction: AuthGoogle is for service accounts. It is not the browser-based user-consent OAuth2 flow.

Typical Workflow

Create a Chilkat.AuthGoogle object.
Provide the service-account private key by setting JsonKey or by calling SetP12.
If using a P12 key, set EmailAddress to the service account client email address.
Set Scope to the space-delimited list of Google API permissions requested by the application.
Optionally set SubEmailAddress for delegated access to a user.
Optionally adjust ExpireNumSeconds, or leave it at the default maximum of 3600 seconds.
Open or provide an existing socket connection to www.googleapis.com.
Call ObtainAccessToken. On success, AccessToken contains the token.
Use the token with Chilkat.Rest or other Chilkat HTTP request classes when calling Google APIs.
Check Valid, NumSecondsRemaining, and LastErrorText as needed.

Core Concepts

Concept	Meaning	Important Members
Service Account	A Google identity used by server-side applications to access Google APIs without interactive user login.	JsonKey, EmailAddress, SetP12
Private Key	The service-account key used to sign the JWT for the access token request.	JsonKey, SetP12, GetP12
Scope	A space-delimited list of requested Google API permissions.	Scope
Delegated Access	A service account may request delegated access for a specific user.	SubEmailAddress
Access Token	The bearer token used in authenticated Google API requests.	ObtainAccessToken, AccessToken, Valid
JWT Claims	Claims used when forming the signed JWT for the token request.	AddClaims, Iat, ExpireNumSeconds

Properties

Property	Purpose	Guidance
AccessToken	The access token used in Google API requests.	Set automatically after a successful ObtainAccessToken call.
JsonKey	JSON private key for obtaining an access token.	Use when authenticating with a Google service-account JSON key. Set either JsonKey or a P12 key, but not both.
EmailAddress	Client email address of the service account.	Required when using a P12 key. If using a JSON key, the client_email is already included in the JSON key and this property is unused.
Scope	Space-delimited list of requested permissions.	Set this to the scopes required by the Google APIs being called.
SubEmailAddress	User email address for delegated access.	Set when the service account is requesting delegated access for a specific user.
ExpireNumSeconds	Requested access token expiration time in seconds.	Default is 3600. Maximum is 3600 seconds, or one hour.
Iat	Overrides the JWT iat claim.	Default is 0, which uses the current system date/time. Leave at the default unless an override is explicitly needed.
NumSecondsRemaining	Seconds remaining before the access token expires.	Returns 0 if the token is invalid or expired.
Valid	Indicates whether AccessToken contains a valid, non-expired token obtained by ObtainAccessToken.	Check before reusing a token.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Private Key Options

Key Type	How to Configure	Important Details
JSON key	Set JsonKey.	The JSON key includes the service account client_email, so EmailAddress is unused.
P12 key	Call SetP12 with a Pfx object.	EmailAddress must be set to the service account client email address.

Choose one key type: An application must set either the P12 private key or the JSON private key, but not both.

Token Lifetime and Validity

Member	Meaning	Guidance
ExpireNumSeconds	Requested token lifetime in seconds.	Maximum is 3600. The default is 3600.
Valid	True if the current access token is valid and non-expired.	Use before reusing AccessToken.
NumSecondsRemaining	Number of seconds remaining until the access token expires.	A value of 0 means the token is invalid or expired.

Methods

Method	Purpose	Important Details
ObtainAccessToken	Sends the HTTP request to fetch the access token.	Requires an existing connection to www.googleapis.com. On success, the token is stored in AccessToken.
AddClaims	Adds additional custom claims to the JWT claims set.	Use when the token request requires extra JWT claims.
SetP12	Sets the P12 private key used for obtaining an access token.	Use when authenticating with a P12 service-account key. Do not also set JsonKey.
GetP12	Returns the private key in a Pfx object.	Available only if the private key was previously set by SetP12.
LoadTaskCaller	Loads the caller of the task's async method.	Used in asynchronous workflows after a task completes.

Clock Accuracy Requirement

Service-account authentication uses JWT time claims. The computer's system date and time must be accurate when requesting a token. If the local clock is too far off, Google can reject the request.

Invalid JWT error: If the computer date/time is not accurately set, the token request may fail with a 400 response indicating that the JWT must be short-lived and within a reasonable timeframe. Check the iat and exp values and use an accurate system clock.

Method and Property Summary by Category

Category	Members	Purpose
Credentials	JsonKey, SetP12, GetP12, EmailAddress	Provide service-account identity and private key material.
Permissions and delegation	Scope, SubEmailAddress	Request Google API permissions and optional delegated user access.
JWT options	Iat, ExpireNumSeconds, AddClaims	Control JWT timing and add optional custom claims.
Token request	ObtainAccessToken	Fetch a Google API access token using the configured service-account credentials.
Token state	AccessToken, Valid, NumSecondsRemaining	Store and inspect the current access token.
Async workflow	LoadTaskCaller	Load the caller object from a completed asynchronous task.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Security Notes

Item	Security Guidance
JSON key or P12 key	Treat service-account private keys as secrets. Do not expose them in client-side code, public repositories, logs, or error messages.
AccessToken	Treat access tokens as bearer credentials. Anyone with the token may be able to call the allowed Google APIs until it expires.
Scope	Request only the permissions required by the application.
SubEmailAddress	Use delegated access only when the service account is authorized for that scenario and the application intentionally acts on behalf of a user.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Token request fails	ObtainAccessToken, LastErrorText	Confirm the connection is to www.googleapis.com, credentials are correct, the scope is valid, and diagnostics are checked.
Invalid JWT time error	Iat, ExpireNumSeconds	Make sure the computer's system clock is accurate. Leave Iat at the default unless an override is explicitly required.
Using JSON key but setting email manually	JsonKey, EmailAddress	When using a JSON key, the client email is already included in the JSON key, and EmailAddress is unused.
Using P12 key without an email address	SetP12, EmailAddress	When using a P12 key, set EmailAddress to the service account client email address.
Access token expired	Valid, NumSecondsRemaining	Check whether the current token is still valid. If not, obtain a new access token.
Google API request is unauthorized	Scope, AccessToken	Confirm the requested scope allows the API operation and that the token is being sent with the REST request.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected token-generation, credential, connection, or async behavior.

Common Pitfalls

Pitfall	Better Approach
Using AuthGoogle for browser-based OAuth2 consent.	Use Chilkat.OAuth2 for 3-legged OAuth2 flows that require interactive user permission in a browser.
Setting both JSON and P12 private keys.	Set either JsonKey or a P12 key with SetP12, but not both.
Using a P12 key without setting EmailAddress.	Set EmailAddress when authenticating with a P12 key.
Overriding Iat unnecessarily.	Leave Iat at 0 so Chilkat uses the current system date/time.
Requesting a token lifetime greater than one hour.	Keep ExpireNumSeconds at or below 3600.
Assuming an access token remains valid indefinitely.	Use Valid and NumSecondsRemaining to check token state.
Ignoring diagnostics after token request failure.	Check LastErrorText and the Google token response details.

Best Practices

Recommendation	Reason
Use AuthGoogle for service-account authentication.	It is designed for Google Cloud Platform API and Google Apps API calls using a service account.
Use Chilkat.OAuth2 for 3-legged OAuth2.	Interactive browser-based permission grants require the OAuth2 class instead.
Prefer JSON keys when the service account key is supplied in JSON format.	The JSON key already contains the client email and key metadata needed by the service account.
Protect service-account private keys and access tokens.	Both can authorize access to Google APIs.
Set Scope to the minimum permissions needed.	Narrow scopes reduce the impact of credential exposure or misuse.
Keep the system clock accurate.	JWT token requests depend on valid iat and expiration timing.
Check Valid before reusing an access token.	Expired tokens should be replaced by calling ObtainAccessToken again.
Check LastErrorText after failures.	It provides useful diagnostic detail for failed or unexpected authentication behavior.

Summary

Chilkat.AuthGoogle is the Chilkat credential class for obtaining Google API access tokens using a service account. It supports JSON and P12 private keys, scoped permissions, optional delegated access, token lifetime control, custom JWT claims, and token validity checks.

The most important practical guidance is to use this class for service-account authentication with Google Cloud Platform APIs and Google Apps APIs, use Chilkat.OAuth2 for browser-based 3-legged OAuth2, set either JsonKey or a P12 key but not both, keep the system clock accurate, protect private keys and access tokens, and use the obtained token with Chilkat.Rest for authenticated Google API requests.

Chilkat.AuthGoogle Class Overview