Integrate G-Suite

Integrate with G-Suite Directory to share employee contact information with your entire organization on any device, intranet, or messenger. Integrate with G-Suite Calendar to manage calendar events. Ensure you meet the prerequisites, enable the APIs, and create the service account. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps.

Note:

We provide two G-Suite integration templates for your use. We recommend using the newer HTTP integration for most use-cases, specifically G-Suite Directory workflows. The HTTP integration provides more power to configure the cached data structure. For full details of the microapps available in each integration, see Use G-Suite microapps.

Review prerequisites

These prerequisites assume you administer the G Suite instance of your organization to set up the integration.

  • This integration requires a dedicated Google account which is used to synchronize calendar data with Workspace. This account must have Admin API privilege Users/Read or a standard Admin role which includes this privilege.
  • If your internal server hosting Workspace is behind a firewall, you must allow access to host name www.google.com with port 443, so Workspace can connect.
  • Obtain a new oauth2 client_id and client_secret and define the scope of client’s application.
  • Configure Citrix Gateway to support single sign-on for G Suite so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in G Suite Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

You must have these details to add the G Suite Calendar integration in Citrix Workspace Microapps:

  • OAUTH Private Key JSON
  • Impersonated Admin User account

For User Consent (3LO) Authentication for Google Calendar:

  • Client ID
  • Client Secret

You must have these details to add the G Suite Directory integration in Citrix Workspace Microapps:

  • Client ID
  • Client Secret
  • Domain
  • Valid G-Suite Directory account and password

Enable APIs

Enable the APIs for the services you require.

Follow these steps:

  1. Log in to https://console.developers.google.com with an administrator account and select Create to create a new project. You can also update an existing project.
  2. Select Enable APIs and Services and search for Admin SDK. Select it and select Enable.
  3. Search for the Google Calendar API. Select it and select Enable.

Create service account

  1. Select the Settings icon at the top left, mouseover IAM & admin, and select Service accounts.
  2. Select CREATE SERVICE ACCOUNT.
  3. Enter your Service account name, a Service account ID (by default, automatically generated), a Service account description, and click CREATE.
  4. Select the Select a role menu, and choose an Owner Role.
  5. Select Continue and then select Done.

Enable G Suite delegation and create Service Account Key

To enable G Suite domain-wide delegation and create a service account key follow these steps:

  1. In your service account list, find the account you created. Select Actions > Edit.
  2. Select Show domain-wide delegation. Select the Enable G Suite Domain-wide Delegation check box.
  3. To create your private key, select +Create key, select JSON, and select CREATE.

    A private key is saved to your computer.

  4. Store the JSON file in a secure location. It is required when you configure the Calendar integration.
  5. Select CLOSE and select SAVE.

Enable and manage API access

  1. Navigate to https://admin.google.com, select Security > API reference. Ensure Enable API access is selected.
  2. Select Advanced settings > Manage API client access. Add the Service account name into the list of Authorized API clients.
  3. Under Client Name, enter the client_id from the private key JSON file that you downloaded.
  4. Enter the following comma delimited list of scopes into the One or More API Scopes field:

    <https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly>,<https://www.googleapis.com/auth/admin.directory.user.readonly> <https://www.googleapis.com/auth/calendar>

  5. Select Authorize.

Add callback URLs to Google API Console

Grant access to private data and provide a link to terms of service and privacy policy. The callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com.

  1. Go to https://console.developers.google.com and log in using your credentials.
  2. Select OAuth consent screen from the left navigation.
  3. Under Authorized domains, add this domain: cloud.com, press return, and select Save.
  4. To create an OAuth client ID, select Credentials from the left navigation. Select Create credentials and Oauth Client ID.
  5. Select Web application and add the following URIs following the style of those previously added to allow access to private data and enable OAuth authenticated user actions:

    Authorized redirect URLs:

    https://{yourmicroappserverurl}/admin/api/external-services/com.sapho.services.googlecalendar.GoogleCalendarService/auth/serverContext,https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

    For Google Directory, use:

    https://{yourmicroappserverurl}/admin/api/external-services/com.sapho.services.googleforwork.GoogleForWorkService/auth/serverContext,https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

  6. After adding each URL, press Enter. After adding all desired URIs, scroll down, and select Create.

    Note:

    If you do not have access, give yourself permissions to accept OAuth permissions. Go to Admin console > Security > API Permissions. Under Internal App Settings, select the Trust domain owned apps check box.

Add the integration to Citrix Workspace Microapps

Add the G-Suite integrations to Citrix Workspace Microapps to connect to your application. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace. We provide two G-Suite Directory integration templates for your use. We recommend using the newer HTTP integration for most use-cases.

Add the G-Suite Directory HTTP integration

Follow these steps to set up the G-Suite Directory HTTP integration. The authentication options are preselected. Ensure that these options are selected as you complete the process. We recommend using this newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the G-Suite Directory tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.
    • Enter the instance Base URL or simply replace {customer-id} in the example with your customer ID.
    • Select an Icon for the integration from the Icon Library, or leave this as the default G-Suite Directory icon.

    GSuiteDirectory HTTP parameters

    • Enable the On-premises instance toggle if you are creating an on-premises connection. For more information, see On-premises instance.

    GSuiteDirectory HTTP On-premises

  5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This will display the Callback URL, which you use when registering your application
    2. Select Authorization header from the Token authorization menu.
    3. Enter your Authorization URL or simply replace {customer-id} in the example with your customer ID. This is the authorization server URL provided when setting up the target application integration.
    4. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    5. Ensure the following is entered for Scope. To synchronize additional entities, you must add scopes here. Use the following, separated by a space: https://www.googleapis.com/auth/admin.directory.user https://www.googleapis.com/auth/admin.directory.orgunit https://www.googleapis.com/auth/admin.directory.group.
    6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Google account. You need to add the Callback URL you see on the integration configuration page.
    7. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    8. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.

      GSuite Directory HTTP service authentication

    9. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

      GSuite Directory HTTP token

  6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This will display the Callback URL, which you use when registering your application
    3. Select Authorization header from the Token authorization menu.
    4. Enter your Authorization URL or simply replace {customer-id} in the example with your customer ID. This is the authorization server URL provided when setting up the target application integration.
    5. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    6. Ensure the following is entered for Scope. To synchronize additional entities, you must add scopes here. Use the following: https://www.googleapis.com/auth/admin.directory.user.
    7. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Google account. You need to add the Callback URL you see on the integration configuration page.
    8. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    9. (Optional) Enter your Header prefix if your bearer prefix is different from the default header.
    10. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

      GSuite Directory Service Action Authentication

  7. (Optional) If you want to activate rate limiting for this integration, enable the Request rate limiting toggle and set the Number of requests per Time interval.
  8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.

    Rate limiting and logging toggles

  9. Select Save to proceed.
  10. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Webex login screen.
    1. Enter your Service Account user name and password and select Log in.
    2. Select Accept. Service Authentication

Add the G-Suite Legacy integrations

To set up G Suite Calendar integration, follow these steps:

  1. From the overview page, select Get Started.

    The Manage Integrations page opens.

  2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
  3. Choose the G Suite Calendar tile.
  4. Enter a name for the integration.

    G Suite Calendar connector parameters, OAuth Private Key JSON, Impersonated Admin User

  5. Enter the Service Authentication parameters that you collected in the previous procedures.
    • Copy and paste the entire OAUTH Private Key JSON. Copy the whole key, including the {} brackets.
    • Enter the Impersonated Admin User.
  6. Select a User Authentication method.
    • Admin
    • User
    • User Consent (3LO) The resource owner allows access.
  7. For User Consent (3LO), enter the Client ID and Client Secret that you collected in the prerequisites procedure.
  8. Enter Connector Parameters.
    • Number of Days of Upcoming Events to Load - Defines the length of time to cache upcoming calendar events to send notifications.
    • Number of Days of Past Events to Load - Defines the length of time to cache past events.
    • Select the Load User Calendar Events radio button if necessary.
    • Thread Count - Enter a value.
  9. Select Add.

To set up G Suite Calendar integration, follow these steps:

  1. From the overview page, select Get Started.

    The Manage Integrations page opens.

  2. Select Add New Integration, and Add a new integration from Citrix-provided templates.
  3. Choose the G Suite Directory tile.

  4. Enter a name for the integration that you collected as prerequisites.

    G Suite Directory connector parameters, CLient ID, Client Secret, Domain

  5. Enter Connector Parameters.
    • Enter Client Secret.
    • Enter Domain.
    • Select the Download Users’ Photos radio button if you want to cache users photos.
  6. Select Log in with your G Suite Directory account to enable OAuth Authorization. A Google sign-in page opens in a new tab. You are prompted to enter an account name, confirm access, and enter a password.
  7. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see G Suite connector specifications.

Use G Suite microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

HTTP G Suite Directory

Our HTTP G Suite Calendar integration comes with the following preconfigured out-of-the-box microapps.

HTTP G Suite microapps

Create User: Add a new user.

Notification or Page Use-case workflows
Create User page Provides a form for adding a new user with details.

Directory Admin: Manage users and details.

Notification or Page Use-case workflows
Delete User page Provides a form for removing a user.
Update User page Provides a form for editing the details of a user.
User Detail page Provides a detailed view of an employee with buttons to update or delete the user.
Users page Provides a searchable list of all employees with a link to individual user details.

Groups: View groups and details.

Notification or Page Use-case workflows
Group Detail page Provides a detailed view of a group.
Groups page Provides a searchable list of all groups with a link to individual group details.

My Details: View your own details.

Notification or Page Use-case workflows
My Details page Provides a detailed, read-only view of a user’s own employee details.

Users: View user details.

Notification or Page Use-case workflows
New Employee notification When a new teammate joins, all subscribers receive a notification.
User Detail page Provides a detailed view of an employee with buttons to update or delete the user.
Users page Provides a searchable list of all employees with a link to individual user details.

Legacy G Suite Calendar

G Suite calendar microapps

Our G Suite Calendar integration comes with the following preconfigured out-of-the-box microapps.

Calendar Events: Create and preview events.

Notification or Page Use-case workflows
Event Reminder notification When an event is upcoming, all subscribers receive a reminder notification.
All Events page Provides a personalized list of upcoming events.
Create Event page Provides a form for adding a new event with details.
Event Detail page Provides a detailed view of an event including a list of guests.

Legacy G Suite Directory

G Suite directory microapps

Our G Suite Directory integration comes with the following preconfigured out-of-the-box microapps.

Directory Admin: Add a new user.

Notification or Page Use-case workflows
Create User page Provides a form for adding a new user with details.

Directory Details: View details of teammates, including new employees and position changes.

Notification or Page Use-case workflows
New Employee notification When a new teammate joins, all subscribers receive a notification.
Position Change notification When the title of an employee changes, all subscribers receive a notification.
All Users page Provides a list of all employees with a link to details.
User Detail page Provides a detailed view of an employee.

Integrate G-Suite