Google Workspace provides comprehensive organizational identity and collaboration data that serves as a foundational element for sophisticated access control decisions. By integrating Google Workspace with SGNL, you bring essential user information, organizational structure, group memberships, and administrative context into your access control framework, enabling policies that reflect how your organization actually operates and collaborates.
To successfully configure the Google Workspace integration, you need administrative access to create service accounts and assign appropriate API permissions. The integration requires read access to users, groups, and organizational data throughout your Google Workspace domain.
Google Workspace Admin Permissions: You need Super Admin access or a custom admin role with permissions to manage API access, view user information, manage groups, and access organizational unit data. The integration specifically requires the ability to read user profiles, group memberships, and organizational structures.
Google Cloud Project Access: The integration uses service account authentication, which requires the ability to create and manage service accounts in a Google Cloud project associated with your Google Workspace domain. You’ll need permissions to create service accounts, generate keys, and enable the necessary APIs.
Admin SDK API Access: The integration uses the Google Admin SDK Directory API to access user and group information. This API must be enabled for your Google Cloud project, and the service account must have appropriate scopes for directory access.
Domain-Wide Delegation: To access Google Workspace data on behalf of users, the service account requires domain-wide delegation authority. This allows the service account to impersonate domain administrators and access the necessary directory information.
Google Workspace integration uses OAuth 2.0 with Authorization Code Flow, which is the recommended authentication method for secure, long-term API access with automatic token refresh capabilities.
https://{clientname}.sgnl.cloud/auth/oidcCallback (replace with your client-specific console URL)https://www.googleapis.com/auth/admin.directory.userhttps://www.googleapis.com/auth/admin.directory.groupBefore configuring SGNL, review your Google Workspace domain structure to understand how users and groups are organized. Consider whether you have multiple domains, how organizational units are structured, and whether you want to include deleted users or specific user subsets in your synchronization. The integration supports filtering options that allow you to customize which data is synchronized based on your organization’s needs.
Google Workspace uses OAuth 2.0 with Authorization Code Flow for secure authentication with automatic token refresh:
https://www.googleapis.com/auth/admin.directory.user https://www.googleapis.com/auth/admin.directory.grouphttps://oauth2.googleapis.com/tokenhttps://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consentNote: The access_type=offline parameter in the Auth URL is required for Google Cloud Platform to issue refresh tokens, enabling long-term access without manual re-authentication.
This authentication method provides secure, long-term access with automatic token refresh, eliminating the need for manual token management.
Complete the required configuration parameters for your Google Workspace integration:
Domain Configuration: Replace the {{Input Required}} placeholder in the adapter configuration with your Google Workspace domain name (such as “company.com”). This tells SGNL which domain’s data to synchronize. Note that you can alternatively use a customer ID for multi-domain environments, but exactly one of either domain or customer must be specified.
API Version: The adapter configuration specifies API version “v1”, which is currently the supported version of the Google Admin SDK Directory API.
The Google Workspace integration includes a comprehensive adapter configuration that must be properly set up for your specific environment. The adapter configuration is provided as a base64-encoded JSON object that includes the following required and optional parameters:
API Version: Set to “v1” to use the current version of the Google Admin SDK Directory API.
Domain or Customer Selection: You must configure exactly one of the following:
Note: The choice between domain and customer depends on your Google Workspace setup. For single-domain organizations, use domain. For multi-domain organizations where you want to synchronize data across all domains, use customer.
The adapter configuration supports sophisticated filtering options to customize which data is synchronized:
User Filtering Options (filters.user):
true to include deleted users in synchronization, or false to exclude them (default: false)"isAdmin=false" to exclude administrative users"isSuspended=false" to exclude suspended usersGroup Filtering Options (filters.group):
"adminCreated=true" to include only administratively created groups"name:Engineering*" to include only groups with names starting with “Engineering”Member Filtering Options (filters.member):
true to include indirect memberships through nested groups, or false for direct memberships only (default: false)"MEMBER" for standard group members"MANAGER" for group managers"OWNER" for group owners"MEMBER,MANAGER,OWNER"Here’s an example of a complete adapter configuration:
{
"apiVersion": "v1",
"domain": "yourcompany.com",
"filters": {
"user": {
"showDeleted": false,
"query": "isAdmin=false"
},
"group": {
"query": "adminCreated=true"
},
"member": {
"includeDerivedMembership": false,
"roles": "MEMBER,MANAGER,OWNER"
}
}
}
This configuration would:
When setting up your Google Workspace integration in SGNL:
"domain": "{{Input Required}}" with your actual domain nameFor detailed information on query syntax and filtering options, refer to the Google Admin SDK documentation for user searches and group searches.
The Google Workspace integration provides sophisticated filtering capabilities that allow you to customize which data is synchronized based on your organization’s needs and access policy requirements.
User Filtering Options: You can configure queries to filter which users are synchronized. For example, you might exclude admin users from general access policies by setting a query like “isAdmin=false”, or include only active users by filtering out suspended accounts. The integration also supports including deleted users if you need to maintain historical access context.
Group Filtering Capabilities: Group synchronization can be filtered to include only administratively created groups or groups matching specific criteria. This is particularly useful for organizations with many informal or automatically generated groups that may not be relevant for access control decisions.
Membership Role Filtering: The integration allows you to specify which membership roles to include when synchronizing group memberships. You can choose to include only standard members, or also include managers and owners, depending on how your organization uses Google Workspace group roles in access decisions.
Derived Membership Options: For complex organizational structures, you can choose whether to include derived (indirect) memberships that result from nested group structures. This affects how SGNL understands the complete scope of user access through group hierarchies.
The Google Workspace template defines several interconnected entities that capture the complete organizational and collaborative structure within your domain.
User Entity: Represents individual users within your Google Workspace domain with comprehensive profile information including names, administrative status, login patterns, security settings like two-factor authentication enrollment, suspension status, organizational unit placement, and various account settings. This rich user context enables policies that consider not just identity, but user behavior, security posture, and organizational role.
User Email Entity: Represents the multiple email addresses associated with each user, including primary email, aliases, and alternate addresses. This parent-child relationship structure allows policies to reason about user identity across different email addresses while maintaining the connection to the primary user entity.
Group Entity: Represents Google Workspace groups with information about group purpose, membership counts, administrative creation status, and group characteristics. Groups in Google Workspace often represent both organizational structure (departments, teams) and functional roles (project access, application permissions), making them crucial for access control decisions.
Member Entity: Represents the relationship between users and groups, including membership types (user members vs. nested group members), roles within groups (member, manager, owner), and membership status. This entity captures the complex membership structures that Google Workspace supports, including nested groups and role-based group participation.
The template’s structure reflects Google Workspace’s flexible organizational model where users can have multiple email addresses, belong to numerous groups with different roles, and where groups themselves can be members of other groups, creating rich hierarchical structures for access control.
The Google Workspace template establishes sophisticated relationships that enable SGNL to understand both direct and indirect organizational connections within your domain.
Direct User-Group Relationships: The template creates direct relationships connecting users to their group memberships through the Member entity. These relationships capture not just membership, but also roles within groups and membership types, enabling policies that consider leadership roles and group responsibilities.
Nested Group Structures: Google Workspace supports groups containing other groups, and the template maps these nested relationships through SubGroupMember path relationships. This enables policies that understand inherited permissions and hierarchical organizational structures.
User Email Relationships: The parent-child relationship between User and UserEmail entities allows policies to reason about user identity across multiple email addresses while maintaining organizational context. This is particularly important for access decisions that might be based on specific email addresses or domains.
Complex Membership Paths: The template defines path relationships like UserGroupMember that trace complete membership chains from users through the member relationship to their groups. This enables sophisticated policies that can reason about multi-level organizational structures and complex permission inheritance patterns.
After configuring the Google Workspace integration, systematic testing ensures that your organizational data is being correctly imported and that the complex group and membership relationships are properly established.
The Google Workspace integration includes multiple related entities that should be enabled systematically to ensure complete organizational mapping:
Once synchronization is complete, use DataLens to explore your Google Workspace organizational data:
OAuth Authorization Failures: If SGNL cannot authenticate with Google Workspace, verify that your Client ID and Client Secret are correctly entered and that the OAuth 2.0 credentials are properly configured in Google Cloud Console. Ensure that the redirect URI in SGNL matches exactly what you configured in Google Cloud.
Scope and Permission Issues: If you receive authorization errors, verify that the required scopes (https://www.googleapis.com/auth/admin.directory.user and https://www.googleapis.com/auth/admin.directory.group) are correctly configured and that the authenticating user has Super Admin privileges or appropriate delegated admin permissions in Google Workspace.
API Access and Consent Problems: If synchronization fails with permission errors, ensure that the Admin SDK Directory API is enabled in your Google Cloud project and that the OAuth consent screen is properly configured. The authenticating admin user must consent to the requested scopes during the authorization flow.
Refresh Token Issues: If authentication works initially but fails during subsequent synchronizations, this may indicate refresh token problems. Ensure that the access_type=offline parameter is included in your Auth URL configuration to enable refresh token generation.
Large Domain Performance: Google Workspace domains with thousands of users and complex group structures may experience slow synchronization times. The default API call frequency settings respect Google’s rate limits, but you may need to adjust timing parameters for very large domains or consider implementing more selective filtering.
Complex Group Hierarchy Issues: If nested group relationships are not being properly mapped, ensure that all core entities (User, Group) have completed their initial synchronization before Member entities begin processing. Complex nested structures may require multiple synchronization cycles to fully establish all relationships.
User Filtering Complications: If user filtering isn’t producing expected results, review your query syntax against Google’s directory API documentation. User queries support complex expressions, but syntax errors can cause unexpected filtering behavior or synchronization failures.
Email Address Mapping Problems: If UserEmail entities are not properly connecting to their parent User entities, verify that the parent-child relationship configuration is correct and that users with multiple email addresses are being processed completely before the relationship mapping occurs.
Multi-Domain Configuration: If your organization uses multiple Google Workspace domains, ensure that you’ve configured either the correct primary domain or used the customer ID approach for multi-domain access. Mixing domain and customer configurations can cause synchronization failures.
Organizational Unit Complexity: While the template doesn’t explicitly map organizational units as separate entities, organizational unit paths are captured in user profiles. If organizational unit information isn’t appearing as expected, verify that your domain structure includes the organizational units you expect and that users are correctly assigned to them.
Group Type Confusion: Google Workspace supports various group types (distribution lists, security groups, etc.), and different group types may have different characteristics. If certain groups aren’t synchronizing as expected, review the group types in your domain and consider whether filtering adjustments are needed.
API Rate Limiting: Google Workspace APIs have rate limits that can affect synchronization of large domains. The default configuration respects these limits, but if you encounter throttling errors, you may need to reduce the API call frequency or implement more selective synchronization strategies.
Token Management: OAuth 2.0 access tokens expire and need to be refreshed periodically. For ongoing synchronization, consider implementing automated token refresh mechanisms or monitoring token expiration to prevent synchronization interruptions.
Memory and Processing Requirements: Large Google Workspace domains with complex group structures and extensive user profiles require significant processing power to map all relationships and attributes. Monitor SGNL’s resource usage during initial synchronization and consider optimizing filtering criteria if performance becomes an issue.
Once your Google Workspace integration is successfully configured and synchronized, you can leverage the rich organizational data in sophisticated SGNL policies that reflect how your organization actually operates and collaborates.
Organizational Hierarchy Policies: Use Google Workspace group memberships and roles to create policies that reflect your organizational structure. For example, group managers might automatically receive access to resources related to their group’s function, or department-based groups might determine access to department-specific applications.
Administrative Role-Based Access: Leverage Google Workspace administrative roles to inform access decisions in other systems. Users with Google Workspace admin privileges might receive corresponding elevated access in integrated applications, or conversely, might be subject to additional security requirements.
Security Posture-Based Policies: Use Google Workspace security attributes like two-factor authentication enrollment, account suspension status, and login patterns to create dynamic access policies. Users who haven’t enabled 2FA might be restricted from accessing sensitive resources, or recently inactive users might trigger additional verification requirements.
Collaborative Context Policies: Leverage Google Workspace group structures to understand collaborative relationships and project affiliations. Users who are members of specific project groups might automatically receive access to related development tools, documentation systems, or project management applications.
Email-Based Identity Policies: Use the comprehensive email address mapping to create policies that work across different identity representations. This is particularly valuable for integrating with systems that identify users by different email addresses or for handling identity federation scenarios.
Nested Group Permission Inheritance: Take advantage of Google Workspace’s nested group capabilities to create policies that understand complex organizational hierarchies. Users might inherit permissions through multiple levels of group membership, reflecting real organizational structures and delegation patterns.
For comprehensive guidance on creating policies with Google Workspace organizational data, refer to the SGNL Policy Management documentation. For understanding how Google Workspace entities relate to other identity and business systems in your environment, review the Entities and Relationships guide.