Workforce Identity

Google Workspace Single Sign-On (OAuth 2.0)

Configure Google Workspace as an OpenID Connect (OIDC) identity provider for your Amazon Cognito User Pool. Operators log in with corporate Google credentials via the CLI or web console, inheriting Google 2-Step Verification and organizational lifecycle controls.

Critical Configuration

Exact Google Cloud Console Endpoints

When creating your OAuth 2.0 Client ID in the Google Cloud Console, you must provide the exact Authorized JavaScript origins and Authorized redirect URIs below. Replacing <cognito-domain-prefix> and <region> with your stack values (e.g. auritus-auth in us-east-1).

Authorized JavaScript origins
https://<cognito-domain-prefix>.auth.<region>.amazoncognito.com
http://localhost:3000
http://localhost:3001
https://console.aurit.us
Authorized redirect URIs (Required by AWS Cognito IdP)
https://<cognito-domain-prefix>.auth.<region>.amazoncognito.com/oauth2/idpresponse
Notice the /oauth2/idpresponse path: AWS Cognito User Pools require Google to redirect directly to this endpoint. If you omit /oauth2/idpresponse or add a trailing slash, Google will abort the authentication flow with Error 400: redirect_uri_mismatch.

Step 1

Configure OAuth in Google Cloud Console

Set up an OAuth 2.0 client credential in your organization's Google Cloud project.

  1. Open the Google Cloud Console → APIs & Services → Credentials.
  2. Configure OAuth consent screen (if not already completed):
    • User Type: Select Internal if you want to restrict operator access exclusively to members of your Google Workspace domain (recommended for production organizations). Select External for development or multi-domain environments.
    • App Information: Set App name to Auritus Operator Auth and provide your support email.
    • Scopes: Add openid, .../auth/userinfo.email, and .../auth/userinfo.profile.
  3. Create OAuth client ID:
    • Click + CREATE CREDENTIALS → OAuth client ID.
    • Select Web application as the Application type.
    • Name: Auritus Cognito Federation.
    • Authorized JavaScript origins: Add your Cognito Hosted UI domain and console URLs:
      https://<cognito-domain-prefix>.auth.<region>.amazoncognito.com
http://localhost:3000
    • Authorized redirect URIs: Enter the exact Cognito IdP response endpoint:
      https://<cognito-domain-prefix>.auth.<region>.amazoncognito.com/oauth2/idpresponse
    • Click CREATE. Note your Client ID and Client Secret.

Step 2

Store Credentials in AWS Secrets Manager

To avoid hardcoding secrets in CDK templates or source code, Auritus retrieves the Google OAuth credentials from AWS Secrets Manager at synth/deploy time.

Store the credentials as a JSON object with keys client_id and client_secret:

AWS CLI: Store Google OAuth Credentials
aws secretsmanager create-secret \
  --name "auritus/google-oauth" \
  --description "Google OAuth Client ID and Secret for Auritus Cognito IdP" \
  --secret-string '{"client_id":"YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com","client_secret":"GOCSPX-YOUR_GOOGLE_CLIENT_SECRET"}'

If the secret already exists, update it with aws secretsmanager put-secret-value:

AWS CLI: Update Existing Secret
aws secretsmanager put-secret-value \
  --secret-id "auritus/google-oauth" \
  --secret-string '{"client_id":"YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com","client_secret":"GOCSPX-YOUR_GOOGLE_CLIENT_SECRET"}'

Step 3

Deploy or Update the CDK Backend

Pass the Secrets Manager ARN and your chosen Cognito domain prefix into CDK context:

CDK Deploy with Google OAuth Context
cd cdk
cdk deploy \
  -c google_oauth_secret_arn="arn:aws:secretsmanager:us-east-1:123456789012:secret:auritus/google-oauth" \
  -c cognito_domain_prefix="auritus-auth"

The CDK construct creates the UserPoolIdentityProviderGoogle resource, maps Google profile attributes (email → email, name → fullname), and attaches Google as an authorized identity provider on both the CLI app client and the web console app client.

Step 4

Operator Authentication Workflows

CLI Browser Single Sign-On

Operators run the login command. The CLI launches a temporary local loopback web server and opens the default browser directly to Google Sign-In:

Terminal
auritus login --sso google

The browser redirects through Cognito to http://localhost:8080/callback. The CLI captures the authorization code, exchanges it for Cognito JWT tokens, and caches them in ~/.auritus/tokens.json with automated 30-day rotation.

Operator Web Console

On the Auritus Web Console sign-in screen, operators click the Google Single Sign-On button:

Sign in with Google Workspace

Upon successful Google authorization, Cognito redirects to https://console.aurit.us/callback or http://localhost:3000/callback, initializing an authenticated session for job exploration and worker telemetry.

Diagnostics

Troubleshooting & Common Errors

Error 400: redirect_uri_mismatch

Cause: The redirect URI sent by AWS Cognito does not exactly match any Authorized redirect URI configured in Google Cloud Console Credentials.

Fix: In Google Cloud Console under Authorized redirect URIs, verify:

  • The URI ends with /oauth2/idpresponse.
  • There is NO trailing slash after /oauth2/idpresponse.
  • The domain prefix and AWS region match your Cognito User Pool Domain exactly.
Cognito Error: redirect_mismatch

Cause: The callback URL requested by the Auritus CLI or Web Console is not in the list of allowed Callback URLs on the Cognito App Client.

Fix: Ensure http://localhost:8080/callback and http://127.0.0.1:8080/callback are present in your CDK AuritusCliClient configuration, or http://localhost:3000/callback for the web console.

Cognito Error: invalid_client

Cause: Cognito was unable to exchange credentials with Google because the Client ID or Client Secret in AWS Secrets Manager is incorrect or retains placeholder values.

Fix: Inspect and update your Secrets Manager secret:

aws secretsmanager get-secret-value --secret-id auritus/google-oauth
Access blocked: Authorization Error (Google 403)

Cause: The OAuth consent screen is configured as Internal, but the user attempting to sign in does not belong to your Google Workspace organization. Alternatively, if configured as External in Testing status, the user email has not been added to the Test Users list.

Fix: Sign in with an authorized organizational account, or add the email address under OAuth consent screen → Test users in Google Cloud Console.

← Return to Getting Started WizardSecurity & Token Architecture