Create HTTP integration

Now that you have identified your APIs, let’s add an HTTP integration to Microapps service.

  1. From the Microapp Integrations page, select Add Integration.
  2. Choose the Create a new integration to your HTTP web service to add configuration details.

    HTTP Tile

  3. Give your integration a Name and enter the Base URL that you collected. The Base URL is the consistent part of your web address that you will use for this integration.

    You can add only one Base URL per integration. If you require more Base URLs you must create another integration.

Note:

While HTTP and HTTPS are both permitted as Base URLs, HTTP is considered a much less secure connection method and it is unlikely that you use it for your target integration application.

For example:

Name: Asana integration

Base URL: https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}

Note:

Replace ${YOUR_WORKSPACE_ID} with your workspace ID (ex. 419224638481718) in this example.

On-premises instance

Microapps service allows you to connect your on-premises System of Record (SoR). To create an on-premises connection, first connect using the Connector Appliance then follow this procedure to collect and add the resource identifier id. For more information, see Citrix Cloud Connector Appliance.

  1. Go to Citrix Cloud and sign in with your credentials.
  2. After signing in to Citrix Cloud, select Resource Locations from the menu.
  3. Select the add icon + and find your Microapps resource from the list.
  4. Select ID and copy the resource identifier id into the On-premises instance resource location field in the Add HTTP Integration screen.

Your on-premises integration is configured.

Set up Service Authentication

When configuring your HTTP Integration service authentication, you have set up your service account with your target application and possess the necessary credentials as per the requirements of your target application. After you have gathered all the necessary information on your target application (login, passwords, security credentials and so on) you can begin the service integration process.

Select your authentication method from the following:

  • None - No security credentials needed.
  • Basic - Use your user name and password of the target application for authentication.
  • NTLM - Configure your HTTP integration to use a suite of Microsoft protocols to connect via New Technology LAN Manager (NTLM) authentication server to authenticate NTLM users via Microsoft Windows credentials.
  • Bearer - Configure the target integration’s authentication scheme to use bearer tokens generated by the server in response to a log-in request.
  • OAuth 2.0 - Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. OAuth 2.0 implementation varies from system to system but the general workflow for OAuth 2.0 works as described below.
  • API Keys - use the API Keys method to authenticate a user, developer, or calling program to an API.

Note:

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.

Follow these steps:

  1. Enter Service Authentication parameters for the integration.
  2. (Optional) For Authorization Code grant type, select Log in with your service account and wait for the login to complete.
  3. (Optional) Select the Service Action Authentication radio button, and enter authentication parameters at the service action level.

    Important:

    If you are using delegated permissions, you might not have full access. In this case, use Service Action Authentication to authenticate at the service action level. In this situation, you can use basic authentication at the service level, but you must use OAuth 2.0 at the service action level for security reasons.

  4. Select Add.

OAuth 2.0 Authentication

OAuth 2.0 enables applications to gain specific access to HTTP service user accounts on third-party applications. It works by delegating authentication to the service that contains the user account, and then authorizes third-party applications to access that user account.

OAuth Callback URLs

Callback URLs for authentication follow this pattern:

https://{customer_id}.{customer_geo}.iws.cloud.com/admin/api/gwsc/auth/serverContext,
https://{customer_id}.{customer_geo}.iws.cloud.com/app/api/auth/serviceAction/callback

The second part of this URL is used only when defining per user authenticated actions. The customer and geographic identifiers are variable and unique to each customer.

OAuth 2.0 Grant Types

HTTP integration allows you to select from three grant types. When setting up Oath 2.0, select your grant type from the menu. When configuring OAuth 2.0 we recommended that you use the Authorization Code as this is the most secure grant flow. Use Client Credential and Resource Owner Password grant types if you require them for additional service action authentication methods:

  • Authorization Code - Grant 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.
  • Client Credentials - Grant type is used to obtain an access token outside of the context of a user. This is used by clients to access their own resources rather than access a user’s resources.
  • Resource Owner Password - Provide the correct credentials to authorize resource server provision of an access token.

Grant Type Inputs

Depending on the grant type defined above you are provided with the following options to complete to enable OAuth 2.0 authentication:

  • Token URL - Define the URL of the access authorization token.
  • Scope - Define the scope of the access request, this is a string that is defined by the authorization server when setting up your target integration application.
  • Client ID - Define the string representing client registration information unique to the authorization server.
  • Client Secret - Define the unique string issued when setting up the target application integration.
  • Username - Define the user name of your target application account.
  • Password - Define the password of your target application account.
  • Authorization URL - Define the authorization server url provided when setting up the target application integration.
  • Access Token Parameters - Define the access token parameters as required by the target application authorization server if necessary.
  • Log in with your service account - Log into the service account of the authorization server of your target application.
  • Header Prefix - (optional) enter the header prefix if your bearer prefix is different from the default header.

Extra resources regarding OAuth 2.0 can be found at OAuth 2.0’s request for questions page.

Troubleshooting OAuth 2.0

If you are having problems connecting your target application to the microapp platform check the following possible solutions errors against your own configuration:

  • invalid_request - Your authorization request may miss a required parameter, contain an unsupported parameter value (or other grant type), repeat a parameter, include multiple credentials, utilize more than one mechanism to authenticate a client.
  • invalid_client - Your client authentication failed for the following reasons: unknown client, no client authentication included, or unsupported authentication method. The authorization server may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported.
  • invalid_grant - The authorization grant or refresh token may be invalid, expired, revoked, does not match the redirection URI used in the authorization request was issued to another client.
  • unauthorized_client - The authenticated client is not authorized to use this authorization grant type.
  • unsupported_grant_type - The authorization grant type is not supported by the authorization server.
  • invalid_scope - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

If you are still having problems configuring OAuth 2.0, check whether you have entered the correct URL for Token and Authorization URL, as these are both unique. Also recheck that your other inputs are correct, such as Scope and so on. If problems persist, check settings on the integrated application server side.

Request rate limiting (optional)

Select the Request rate limiting to enable rate limiting for your integration. When toggled, you can define the number of requests and the time interval (1 second or 1 minute) extracted from your target application. Configure rate limiting based on the best practices/rate limits as defined in your target application’s documentation.

Webhook listeners

Configure webhook listeners (also known as HTTP push API) to enable your microapps to provide near real-time data to your end users. Configuring a webhook allows your apps to deliver data to other applications at a much quicker rate than synchronization from the Microapp platform side. Adding webhook listeners requires you to be familiar with your target application System of Record and have the necessary tools and administration privileges set up to configure your webhooks in those locations.

Configure your webhooks after you have set up your integration via Data Loading and follow these steps:

  1. Click Webhook Listeners on the left hand bar of the HTTP Integration screen:

    Webhook listeners

  2. Enter your desired webhook name.
  3. Select Copy to copy the webhook URL for use in your target System of Record administration interface.

Authorization method

You can select either the Token authorization method or None when configuring your authorization method. To configure the token method follow these steps:

  1. Select Token in the Authorization method menu.
  2. Select Generate token and then select Copy to add the token to your clipboard for use in your target System of Record administration interface.
  3. Select read token from to choose from:
    • Custom header
    • Query parameter
    • Authorization header
  4. Define either the Name or the Prefix depending on your selected read method.

The token is now set up.

Define data structure

You can define your data structure in a similar method described when you Fetch data structure during Data Loading configuration. For more information see Configure the integration.

To define your webhook data structure follow these steps:

  1. Set your desired data retention period.
  2. Select Generate Tables.

    The Generate Tables screen opens.

    Paste your JSON sample request from your target application System of Record here.

  3. Set your base name of created tables.
  4. (Optional) set the root path if necessary.
  5. Select Generate.

With this process complete alongside the configuration measures completed in your target application System of Record administration, select Add.

Your webhook is now configured.

Where to go next

Now that you have created the HTTP integration, configure the integration: