Microapps

Integrate Google Directory

Integrate with Google Directory to share employee contact information with your entire organization on any device, intranet, or messenger. 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 Google Directory integration templates for your use. We recommend using the newer HTTP integration for most use-cases, specifically Google Directory workflows. The HTTP integration provides more power to configure the cached data structure. At the end of this article you can find documentation for the Legacy Google Directory integration template. For details of the Google Calendar integration, see Integrate Google Calendar.

Review prerequisites

These prerequisites assume you administer the Google Directory 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 Google Directory 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 Google Directory Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

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

  • Client ID
  • Client Secret
  • Domain
  • Valid Google 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 Google delegation and create Service Account Key

To enable Google 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 Google 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 Google Directory integration 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 Google Directory integration templates for your use. We recommend using the newer HTTP integration for most use-cases.

Follow these steps to set up the Google 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 Google 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 Google Directory icon.

    Google Directory HTTP parameters

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

    Google Directory 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.

      Google 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.

      Google 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.

      Google 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

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 Google Directory connector specifications.

Use Google Directory microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs. Our Google Directory HTTP integration comes with the following preconfigured out-of-the-box microapps.

Google Directory connector specifications

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 Google Directory integration

You must have these details to add the Google Directory integration in Citrix Workspace Microapps and review the prerequisites above:

  • Client ID
  • Client Secret
  • Domain
  • Valid Google Directory account and password

Add the Legacy Google Directory 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 Google Directory tile.

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

    Google 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 Google 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 Google Directory connector specifications.

Legacy Google Directory microapps

Our Google 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.