Background
The SSO and User Provisioning features in MyBusiness allow the customer to fully control:
- Who has access to the customer's associated companies in MyBusiness
- How the customer's users access MyBusiness, using the sign-in policies in Google Workspace, e.g. enforcing 2-Step Verification
Once SSO is activated, users provisioned to MyBusiness can only sign in with their Google Workspace account. Users who already have a MyBusiness account can no longer use their current sign-in method.
About Single Sign-On (SSO)
SSO is an authentication scheme that allows a user to log in with a single ID to several independent software systems. For the purposes of this document, SSO refers to using a Google Workspace account (Sign in with Google) to sign in to MyBusiness.
About System for Cross-domain Identity Management (SCIM)
The SCIM protocol is a standard for provisioning and managing identity data on the web. With the SCIM method, the customer uses their own system, such as an identity management tool or a custom integration, as a SCIM client that sends users and groups from Google Workspace to MyBusiness.
More information: SCIM: System for Cross-domain Identity Management
Prerequisites
Before starting this guide, the following prerequisites must be met:
- Usage of SSO and User Provisioning must be agreed with Aspia and enabled on the customer's companies in MyBusiness.
- A Google Workspace account with an administrator role that can read users is required to accept the invitation, for example the prebuilt User Management Admin role, or a custom admin role with the Admin API privilege Users → Read. Super Admin is not required. MyBusiness requests read-only access to users in the Directory API
(https://www.googleapis.com/auth/admin.directory.user.readonly). - A system that sends users and groups from Google Workspace to MyBusiness using SCIM (a SCIM client). Google Workspace does not include such a system, so the customer needs to provide one, for example an identity management tool that supports SCIM provisioning to custom applications, or an integration developed by the customer that reads users and groups from the Google Workspace Directory API and sends them to MyBusiness. The customer is responsible for configuring and operating this system. MyBusiness supports the subset of SCIM 2.0 described under Supported SCIM operations in Appendices. The customer should verify that the SCIM client is compatible.
- At least one group per company in MyBusiness must exist in Google Workspace. The customer is responsible for maintaining membership in the groups. See Groups and company access.
- Existing MyBusiness users are matched on their primary Google Workspace email address. If an existing user is registered in MyBusiness with another address, update it to the primary address before provisioning; otherwise a new user is created. When Single Sign-On starts, the domain of the primary email address of each user who is a member of a group connected to a company becomes a managed email domain in MyBusiness.
Groups and company access
MyBusiness uses groups in Google Workspace to decide which companies a user can access. Each group is connected to one company in MyBusiness, and membership gives the user basic access to that company. Only users who are members of at least one group connected to a company are synchronized to MyBusiness. Other roles and permissions are managed in MyBusiness. We recommend creating dedicated groups for MyBusiness, so that membership only changes when access to MyBusiness should change.
Examples:
- One company: create one group, e.g. MyBusiness – Company A, and add all users who need access.
- Several companies: create one group per company. A user who needs access to Company A and Company B is a member of both groups.
Several groups can be connected to the same company. Nested groups are not supported; users must be direct members of the group. Once Single Sign-On has started, a group's company connection cannot be changed. New groups can still be connected.
MyBusiness User Provisioning administration
- Click the link in the invitation email.
- Sign in with a Google Workspace account that has an administrator role in the organization that is to be connected to MyBusiness. The account must have the same email domain as the address the invitation email was sent to. A consent screen for MyBusiness will be shown. Click Allow. MyBusiness reads your own user account in Google Workspace to get your organization's Customer ID, which is used to connect the companies to the correct tenant.
- If your organization restricts access to third-party apps in the Google Admin console, an administrator may need to mark MyBusiness as trusted before you can sign in.
- Ensure that the company name and Customer ID are correct, and then click Connect to tenant.
- You are signed in to MyBusiness with your Google Workspace account and taken to the Credentials tab on the MyBusiness User Provisioning administration page.
- (Optional) If desired, change the email for notifications by clicking the edit icon. Notifications about upcoming token expiration will be sent to this address.
- Keep this page open.
SCIM client configuration
The SCIM client must be able to:
- Send users from Google Workspace to MyBusiness, using the user's Google Workspace ID as both externalId and userName.
- Create users before adding them to groups, and add group members with a PATCH request after the group has been created.
- Send changes continuously, including suspended users (active = false), removed group members and deleted users.
- Update users and groups with PATCH requests that include a path, since PUT is not supported, and look up users and groups with a filter instead of listing them all.
The detailed requirements are described under Supported SCIM operations in Appendices.
The exact steps depend on the system used as SCIM client. The following settings are required regardless of system.
- On the MyBusiness User Provisioning administration page, click Generate secret token. A dialog box will open. Click the Copy button to copy the token to the clipboard.
- In the SCIM client, configure authentication with the token. The secret token is sent as a Bearer token in the Authorization header of each SCIM request: Authorization: Bearer <token>.
- Copy the SCIM base URL from the MyBusiness User Provisioning administration page and enter it as the base URL (sometimes called endpoint URL) in the SCIM client.
- Configure the SCIM client to provision both users and groups. MyBusiness uses the SCIM resources /Users and /Groups.
- If the SCIM client has a connection test, run it.
Each secret token is valid for a limited period. Two tokens can be active at the same time, so a new token can be generated and configured before the old one expires. Notifications about upcoming expiration are sent to the email for notifications.
Attribute mapping
The SCIM client must map attributes from Google Workspace to the SCIM attributes below. The source fields are named as in the Google Admin SDK Directory API; the name may differ in the customer's SCIM client.
Important: externalId for users must be the user's unique Google Workspace ID. This is the ID MyBusiness receives when the user signs in with Google. If another value is used, users will not be matched at sign-in and will not be able to access MyBusiness.
Group mapping
| Google Workspace field | SCIM attribute | Notes |
| id | externalId | The group's unique ID |
| name | displayName | Shown on the Connect user groups tab |
| members (users) | members | Users only, nested groups are not supported. Members must be referenced by the id MyBusiness returned when the user was created, not by the Google Workspace ID. Most SCIM clients handle this automatically |
User mapping
| Google Workspace field | SCIM attribute | Notes |
| id | externalId | Required. Must be the user's unique Google Workspace ID |
| id | userName | Required. Must have the same value as externalId. MyBusiness matches the filter userName eq "..." against externalId, so a SCIM client that sets userName to the email address will not find existing users |
| primaryEmail | emails[type eq "work"].value | Required |
| name.givenName | name.givenName | Required |
| name.familyName | name.familyName | Required |
| languages (the preferred language) | preferredLanguage | Optional. A language tag such as sv-SE or en-GB |
| phones (type work) | phoneNumbers[type eq "work"].value | Optional |
| phones (type mobile) | phoneNumbers[type eq "mobile"].value | Optional |
| suspended | active | Required. A suspended user is sent as active = false |
Start the provisioning
This step starts provisioning of users and groups from Google Workspace to MyBusiness. Enabling provisioning does not enable the Single Sign-On experience for the users. Users and group memberships are received and shown on the administration page, but are not applied to the companies in MyBusiness until Single Sign-On starts. Current users will be able to sign in with their current sign-in method until the step Starting the Single Sign-On transition is completed.
- In the SCIM client, limit provisioning to the groups that represent a company in MyBusiness and their members.
- Start the provisioning in the SCIM client.
- Verify that the groups appear on the Connect user groups tab and the users on the User status tab in MyBusiness.
Configure MyBusiness companies
The groups must have been provisioned before this step can be started.
- Go back to the MyBusiness User Provisioning administration page.
- Click on the Connect user groups tab.
- For each of the groups in Waiting to be connected, select which company in MyBusiness that group represents with the Sync to company dropdown menu. If there are groups that do not represent a company, select Exclude from sync. Users who are only members of excluded groups are not synchronized to MyBusiness.
- For each group connection, press Confirm. If the connection is correct, press Connect.
Starting the Single Sign-On transition
Warning: This is the last step of the configuration. Once Single Sign-On has been enabled, all existing MyBusiness users with a managed email domain lose the ability to sign in with their current sign-in method. Ensure that the users have been informed about the change. When Single Sign-On starts, the email domains of all users who are members of a group connected to a company become managed email domains, and other users with a managed email domain will be deleted from MyBusiness. Users with a managed email domain can only be connected to companies connected to your organization. Access to other companies in MyBusiness is removed.
Before enabling SSO, review the User status tab. It lists users who will lose access to companies, and users who are not provisioned but have a managed email domain. Make sure that all users who should keep access to MyBusiness have been provisioned before the start date.
Go to the Enable SSO tab. In Enable SSO for end users in MyBusiness, select a start date by clicking the Schedule SSO start date button and selecting a date. SSO will be enabled at midnight at the start of the selected date, i.e. all sign-ins on the selected date will use Single Sign-On. If the current date is selected, Single Sign-On will be activated immediately. Select Schedule start to confirm when Single Sign-On will be activated.
Appendices
These sections describe the provisioning attributes and events as handled by MyBusiness.
Group attributes
| Attribute | MyBusiness property | Required | Notes |
| externalId | Unique identifier | Yes | |
| displayName | Name | Yes | Used to identify the group in Configure MyBusiness companies |
| members | Users to be added to a specific company | No | Added and removed with PATCH after the group has been created. Members are referenced by the id MyBusiness returned when the user was created |
User attributes
| Attribute | MyBusiness property | Required | Notes |
| externalId | Unique identifier | Yes | Must be the user's unique Google Workspace ID, used to match the user at sign-in |
| userName | Not stored | Yes | Must have the same value as externalId, see Supported SCIM operations |
| emails[type eq "work"].value | Email adress | Yes | Used in initial matching with existing users in MyBusiness |
| preferredLanguage | The preferred language | No | Used to set the initial language for a new user in MyBusiness. The value is a language tag, such as sv-SE or en-GB. Supported languages are English, Swedish, Finnish, Danish and Norwegian; other languages have no effect. Existing users are not updated, since users can choose their own language in MyBusiness. |
| name.givenName | Given name | Yes | |
| name.familyName | Family name | Yes | |
| phoneNumbers[type eq "work"].value | Work phone number | No | |
| phoneNumbers[type eq "mobile"].value | Mobile phone number | No | |
| active | Whether the user is active, either true or false | Yes | Inactive users still exist in MyBusiness and remain connected to companies, but cannot sign in |
Users with invalid data, for example illegal characters in names or invalid phone numbers, are rejected and are not created in MyBusiness until the data is corrected in Google Workspace.
Supported SCIM operations
MyBusiness implements the subset of SCIM 2.0 described in this section. A SCIM client that relies on other operations may not work.
| Resource | Operation | Used for |
| /Users | GET with filter externalId eq "..." | Finding an existing user. The filter userName eq "..." is also accepted, but the value is matched against externalId |
| /Users | POST | Creating a user |
| /Users/{id} | GET | Reading a user |
| /Users/{id} | PATCH | Updating a user, including active |
| /Users/{id} | DELETE | Deleting a user |
| /Groups | GET with filter displayName eq "..." | Finding an existing group |
| /Groups | POST | Creating a group (externalId and displayName) |
| /Groups/{id} | GET | Reading a group. excludedAttributes=members is supported |
| /Groups/{id} | PATCH | Updating the name (replace displayName) and adding or removing members (add / remove members) |
| /Groups/{id} |
DELETE |
Deleting a group |
The following rules apply:
- Every PATCH operation must include a path. The supported user paths are name.givenName, name.familyName, emails[type eq "work"].value, phoneNumbers[type eq "work"].value, phoneNumbers[type eq "mobile"].value, active, preferredLanguage and externalId. Phone numbers and preferredLanguage can be added, replaced and removed. The other attributes can only be replaced.
- Members sent when a group is created are ignored. Members must be added with a PATCH operation after the group has been created.
- Members are referenced by the id MyBusiness returned when the user was created, not by externalId. Users must therefore be created before they are added to a group. If any member in a request is not an existing user, the whole request is rejected.
- When removing members, the members must be listed in value.
- userName is not stored. If the SCIM client looks up users with the filter userName eq "...", the value is matched against externalId. userName must therefore have the same value as externalId.
- GET on /Users and /Groups requires one of the filters listed above and returns at most one match.
Not supported: PUT (replacing a whole resource), PATCH operations without path, path filters on members (e.g. members[value eq "..."]), nested groups, Bulk operations, other filters than those listed, listing all users or groups without a filter, pagination (startIndex and count), sorting, and the discovery endpoints /ServiceProviderConfig, /Schemas and /ResourceTypes.
Deprovisioning users
The following describes how MyBusiness handles provisioning events that deprovision users. Whether these events occur depends on the SCIM client sending the corresponding request when the change is made in Google Workspace.
If a user is removed from a group representing a company (the SCIM client sends PATCH on /Groups/{id} with remove members): the user loses access to the company connected to that group. If the user is a member of a group connected to another company, the user can still sign in and access that company. If the user is not a member of any connected group, the user no longer has access to any company in MyBusiness.
If a group representing a company is deleted (the SCIM client sends DELETE on /Groups/{id}): the members lose access to the company connected to that group, in the same way as if they had been removed from the group.
If a user is suspended in Google Workspace (the SCIM client sends PATCH on /Users/{id} with active = false): the user is prevented from signing in but is not otherwise changed.
If a user is deleted in Google Workspace (the SCIM client sends DELETE on /Users/{id}): the user is removed from all companies and can no longer sign in.