Skip to main content

​
Prerequisites

  • A Google Workspace domain with Super Admin access to the Admin console
  • A Google Cloud project where you can create OAuth clients and service accounts
  • Vikat Enterprise deployed and accessible
  • Your Vikat callback URL: https://<your-vikat-domain>/login
  • Vikat roles created for the roles you plan to map
1

Open the OAuth consent screen

In the Google Cloud Console, go to APIs & Services → OAuth consent screen.
Google Cloud Console APIs and Services section with OAuth consent screen option highlighted

OAuth consent screen - choose Internal for Workspace-only access or External for all Google accounts.

Choose Internal if you only want Workspace users, or External otherwise.Fill in the App name, support email, and developer contact information.
2

Add the required scopes

Add the following scopes:
  • openid
  • profile
  • email
Click Save and Continue.

​
Step 2: Create an OAuth client ID

1

Create a new credential

Go to APIs & Services → Credentials and click Create credentials → OAuth client ID.
Google Cloud Console Create credentials dropdown with OAuth client ID option

Create credentials - select OAuth client ID to generate a client for Vikat.

2

Configure the OAuth client

Set the following values:Click Create.
3

Copy your credentials

Copy the Client ID and Client Secret - you will need them in Step 5.

​
Step 3: Create a service account for Directory API access (optional)

Skip this section if you only need SSO login and do not want directory-based user import or team sync.
1

Create the service account

Go to IAM & Admin → Service Accounts and click Create service account.
Google Cloud Console Service Accounts page with Create service account button

Create a service account - the account is used to call the Admin Directory API on behalf of Vikat.

Give it a name (e.g. vikat-provisioning). Skip the Grant this service account access to project step - no GCP IAM roles are required; access is granted via domain-wide delegation in Step 4.
2

Generate a JSON key

Open the service account, go to Keys → Add Key → Create new key, and select JSON.
Service account Keys tab with Add Key dropdown and Create new key option selected

Create a new JSON key - download and store the file securely. This is the only time you can download it.

Download and store the JSON key file securely.
3

Copy the Unique ID

From the service account Details tab, copy the Unique ID - a numeric value, not the email or the OAuth Client ID.

​
Step 4: Enable the Admin SDK and set up domain-wide delegation (optional)

Required only if you created a service account in Step 3.
1

Enable the Admin SDK API

Go to APIs & Services → Library, search for Admin SDK API, and click Enable.
2

Configure domain-wide delegation

In the Google Admin Console, go to Security → Access and data control → API controls → Manage Domain Wide Delegation.
Google Admin Console Domain-Wide Delegation page with Add new entry button

Domain-wide delegation - authorize the service account to call the Directory API on behalf of an admin user.

Click Add new and enter:
  • Client ID: the service account Unique ID from Step 3
  • OAuth scopes (copy all three, comma-separated):
Click Authorize.
Domain-wide delegation requires impersonating an admin user. Choose an admin email that will persist (e.g. a dedicated sso-admin@company.com) - Vikat uses this as the Admin Email in Step 5.

​
Step 5: Configure Vikat

1

Open User Provisioning and choose Google Workspace

In your Vikat dashboard, go to Governance → User Provisioning.Select Google Workspace as the identity provider and click Next.
2

Fill in the provider configuration

Vikat Provider Configuration form for Google Workspace showing Domain, Client ID, Client Secret, and service account fields

Provider Configuration - enter your Google OAuth credentials and optional service account details.

Click Verify & Next to confirm the connection.
3

Discover claims

On the Attribute Mapping screen, click Discover Claims.Vikat opens a sign-in popup - no session is created.Once you authenticate, it returns the exact claims your Google tenant is sending in the JWT.Use this to confirm which attributes (e.g. hd for hosted domain, email, groups) are present before building your mappings.
4

Set up attribute mappings

Use the sections below the claim list to map Google claim values to Vikat roles, teams, and business units.Attribute-to-Role MappingsMap a claim value to a Vikat role.
  • All matching rules are evaluated - if multiple rules match, the role with the highest permissions is assigned
  • If no rule matches, the user is not assigned a role and login is denied
Attribute-to-Team MappingsMap a claim value to a Vikat team. All matching rules apply.
  • Use a specific value (e.g. engineering) to map that exact claim value to a named Vikat team
  • Use * as the value to sync the claim value directly as the team name
  • Use ${*} to extract part of the string - e.g. Vikat Playground: ${*} Team matches Vikat Playground: Alpha Team and creates team Alpha
Attribute-to-Business Unit MappingsSame wildcard support as team mappings.
  • Use a specific value (e.g. platform) to map that exact claim value to a named Vikat business unit
  • Use ${*} to extract a substring as the business unit name - e.g. Vikat Playground: ${*} BU matches Vikat Playground: Alpha BU and creates business unit Alpha
  • When a rule matches, the resolved business unit is assigned to all of that user’s teams
  • Manually assigned teams are left unchanged
Vikat Attribute Mapping screen showing role, team, and business unit mapping rules

Attribute Mapping - configure role, team, and business unit rules based on the claims Google sends.

Vikat custom attribute mapping configuration

Custom attribute mapping - map any custom claim from Google to a Vikat role, team, or business unit.

Click Next when done.
5

Review and enable

Review your configuration on the final screen, then click Enable.
Restart your Vikat server after enabling for the changes to take effect.

​
How background sync works

Vikat uses the Directory API credentials from this setup to sync users in the background every 24 hours. During that sync, Vikat reconciles imported users, role mappings, team mappings, and business-unit mappings from Google Workspace. Every 15 minutes, Vikat also refreshes active OIDC sessions. If a session cannot be refreshed, Vikat checks with Google whether the user is still active; if Google reports the user as inactive, Vikat decommissions that user locally.

​
Optional next steps

Real-time user sync - OIDC provisions users on first login and the Directory API runs a 24-hour background sync. For closer to real-time provisioning via SCIM, see SCIM with Google Workspace.

​
Troubleshooting

admin_policy_enforced or access_denied during OAuth - the Workspace admin has blocked third-party OAuth apps. In the Admin Console, go to Security → Access and data control → API controls and allow the Vikat OAuth client. unauthorized_client: Client is unauthorized to retrieve access tokens - the service account Unique ID and scopes in Domain-Wide Delegation don’t match. Re-enter the numeric Unique ID from the service account Details tab (not the client email or OAuth client ID). Not Authorized to access this resource/api from Directory API - the impersonated adminEmail is missing the User Management Admin role. Promote them in Admin Console → Admin roles. Also confirm the Admin SDK API is enabled in the Cloud project. domain_mismatch - use the primary domain, not an alias. Users see a consent prompt every login - on the OAuth consent screen, ensure the app is Published (or Internal for Workspace-only) so it doesn’t stay in testing mode.