Skip to content

authentication.md

Latest commit

 

History

History
65 lines (45 loc) · 2.88 KB

authentication.md

File metadata and controls

65 lines (45 loc) · 2.88 KB
Raw

Authentication Guide

Principle

Choose the lightest authentication flow that satisfies the task. Do not invent credentials, do not print secrets, and do not keep retrying commands blindly if auth is missing.

Local interactive setup

gws auth setup
gws auth login
gws auth status

Use this for a developer workstation where a browser flow is available.

Service account

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
gws auth status

Use this for server-to-server tasks where the target API supports service accounts and the required access model is already configured.

CI or headless environments

Preferred approaches:

  • exported credentials handled by the environment
  • service-account based execution
  • a previously approved manual OAuth bootstrap process

Avoid copying secrets into repository files, chat output, logs, or issues.

Manual OAuth fallback

If gws auth setup cannot complete interactively, use the upstream documented manual OAuth flow instead of ad hoc environment variables or guessed filenames.

Verification checklist

  1. Run gws auth status.
  2. Confirm the identity or credential source in use.
  3. Confirm that the selected auth model matches the target Google API.
  4. Only then execute the actual business command.

Auth troubleshooting

Symptom Likely cause What to do
gws auth status shows no credentials OAuth login has not been completed, or the session expired Run gws auth setup and gws auth login, then recheck status before any API call
403 Forbidden or insufficient permissions The authenticated identity lacks API scopes, resource sharing, or workspace permissions Confirm which account is active, verify sharing and API enablement, and retry only after the missing permission is fixed
Service account auth works, but the API still rejects access The target Google API does not support the service-account access model you are using Switch to an interactive OAuth flow or reconfigure delegated access according to the API's access model
CI jobs fail while local auth works Headless execution is relying on local browser auth instead of exported credentials Use environment-managed credentials or a service account in CI, then run gws auth status inside the job
OAuth setup cannot complete in the browser Redirect or client configuration is incomplete for the current machine Use the upstream manual OAuth flow instead of guessing environment variables or editing local files ad hoc
A command fails immediately after auth succeeds Authentication is valid, but the wrong project, tenant, or shared resource is in scope Inspect the target resource identifiers carefully and verify the authenticated identity before retrying

Related references