Move User to Organizational Unit
Automatically move Google Workspace users between organizational units
Overview
The Google Workspace Organizational Unit (OU) tool allows Risotto to automatically move users between organizational units in Google Workspace. This is useful for managing user lifecycles, such as moving new employees from an onboarding OU to their department OU, or moving departing employees to an offboarding OU.
How It Works
When configured, Risotto can move Google Workspace users to a pre-defined organizational unit by simply providing the user's email address. The tool:
- Validates the user exists in Google Workspace
- Checks their current organizational unit
- Moves them to the target OU (if not already there)
- Provides clear feedback on the operation
Prerequisites
Before setting up this tool, you need:
1. Enable Google Admin SDK API
Before creating a service account, enable the Admin SDK API:
- Go to the Google Cloud Console
- Select your project (or create a new one)
- Navigate to APIs & Services > Library
- Search for "Admin SDK API"
- Click on Admin SDK API
- Click Enable
2. Google Workspace Service Account
Create a service account with domain-wide delegation:
- In the Google Cloud Console, navigate to IAM & Admin > Service Accounts
- Click Create Service Account
- Give it a name (e.g., "Risotto User Management")
- Grant it the following role: Service Account Token Creator (optional, for debugging)
- Click Done
- Click on the service account you just created
- Go to the Keys tab
- Click Add Key > Create new key
- Choose JSON format and click Create
- Save the downloaded JSON file securely - you'll need it for configuration
3. Enable Domain-Wide Delegation
- In the service account details, note the Client ID (numeric ID)
- Go to your Google Workspace Admin Console
- In the menu, navigate to Security > Access and data control > API controls
- Click Manage Domain Wide Delegation
- Click Add new
- Enter the Client ID from your service account
- In OAuth scopes, add the following scope:
https://www.googleapis.com/auth/admin.directory.user - Click Authorize
4. Admin User Email
You need the email address of a Google Workspace user with User Management Admin or Super Admin privileges. The service account will impersonate this user to perform operations.
5. Target Organizational Unit Path
Determine the OU path where users should be moved. Examples:
/(root organization)/Engineering/Engineering/Developers/HR/Onboarding
You can find OU paths in the Google Workspace Admin Console under Directory > Organizational units.
Configuration
To set up the tool in Risotto, select Tools in the sidebar. In the Tool groups list, select Google. Find Move User to Organizational Unit and click Set up. Provide these fields:
| Field | Description | Example |
|---|---|---|
| Service Account JSON file | The complete JSON file contents from your service account | { "type": "service_account", ... } |
| Domain | Your Google Workspace domain | company.com |
| Admin User Email | Email of an admin user to impersonate | admin@company.com |
| Target Org Unit Path | The OU path to move users to | /Engineering/Developers |
Usage
Once configured, Risotto can move users by providing their email address:
Example Request:
"Move john.smith@company.com to the Engineering OU"
What Happens:
- Risotto validates that
john.smith@company.comis in thecompany.comdomain - Retrieves the user's current OU (e.g.,
/HR/Onboarding) - Moves the user to the configured target OU (e.g.,
/Engineering/Developers) - Reports back: "Successfully moved user john.smith@company.com from /HR/Onboarding to /Engineering/Developers"
Response Messages
Success Messages
Successfully moved user {email} from {old_ou} to {new_ou}- User was moved successfullyUser {email} is already in organizational unit {target_ou}- No action needed, user already in the target OU
Error Messages
Failed. User email must be in domain {domain}- The provided email doesn't match your configured domainFailed. User email is required.- No email address was providedFailed. User {email} not found in Google Workspace- The user doesn't exist in your Google WorkspaceFailed. Escalate to a human.- An unexpected error occurred (check logs for details)
Security Considerations
-
Service Account Security: The service account JSON contains sensitive credentials. Risotto encrypts these at rest.
-
Domain-Wide Delegation: This grants powerful permissions. Only authorize the specific OAuth scopes needed.
-
Admin User: The impersonated admin user should have least-privilege permissions (User Management Admin rather than Super Admin if possible).
-
Audit Logging: All moves are logged in:
- Risotto's execution logs
- Google Workspace Admin audit logs (Admin console > Reporting > Audit and investigation > Admin log events)
Troubleshooting
"Failed to create delegated credentials"
- Verify the service account JSON is complete and valid
- Ensure domain-wide delegation is properly configured
- Check that the OAuth scope is exactly:
https://www.googleapis.com/auth/admin.directory.user
"User not found in Google Workspace"
- Verify the user email is spelled correctly
- Confirm the user exists in Google Workspace Admin Console
- Check that the user is in the expected domain
"Google API error: 403"
- The admin user may not have sufficient permissions
- The service account may not have domain-wide delegation enabled
- The OAuth scope may be missing or incorrect
"Failed. Escalate to a human."
- Check the Risotto logs for detailed error information
- Verify all configuration values are correct
- Ensure the target OU path exists in Google Workspace
Common Use Cases
- Onboarding: Move new employees from
/Onboardingto their department OU - Offboarding: Move departing employees to
/Former Employeesor/Suspended - Role Changes: Move employees between departments when they change roles
- Access Control: Use OUs to apply different policies, settings, or access rules
Best Practices
- Test First: Test with a single user in a non-production environment before rolling out
- Single Purpose: Create separate tool configurations for different target OUs (e.g., one for onboarding, one for offboarding)
- Clear Naming: Name your tool instances clearly (e.g., "Move User to Engineering OU")
- Monitor Usage: Review execution logs regularly to catch any issues
- Coordinate with Google Workspace Policies: Ensure your OU structure aligns with your Google Workspace policies and settings
Related Tools
- Create Google Group: Create and manage Google Groups programmatically
- Okta Access Rules: For managing access in Okta environments
- Google Workspace Access Rules: For granting access to Google Workspace groups
Additional Resources
Something wrong or missing? Report an issue · View as Markdown