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.

   

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. For example, https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}. Replace ${YOUR_WORKSPACE_ID} with your workspace ID (ex. 419224638481718).

   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 for SaaS integrations, HTTP is considered a much less secure connection method and it is unlikely that you use it for your target integration application. On-premises integrations do not permit HTTP base URLs.

4. Select an Icon to show with your integration. Choose one from the predefined set of icons, or add a custom icon. For details about adding custom icons, see Add custom icons.
5. (Optional) To connect to an on-premises System of Record (SoR), enable the On-premises instance toggle. For more information, see On-premises instance.
6. Select your Service authentication method and Service Action Authentication as required. For more information, see Set up Service Authentication.
7. (Optional) To enable rate limiting for your integration, select the Request rate limiting toggle. For more information, see Request rate limiting.
8. Select Add at the top-right to save these integration configurations. You now continue configuring the integration. For more information, see Configure the integration.

Add custom icons

You can add custom icons to better identify your integrations. When you publish your HTTP integration to a broader audience, the icons files are uploaded to the Azure CDN storage, and are accessible publicly.

The icon file must conform to these parameters:

• The file is in the png format, with a transparent background.
• The file’s resolution must be 128x128 pixels exactly.
• Maximum file size is 80 KB.

Note

Custom icons are for your overview of integrations only. You cannot propagate them to Workspace notifications.

To add an icon, choose Add an icon, and select the file that you want to upload.

When you export an integration and then import it to another instance, the icon is added to the list of custom icons at the target instance.

To remove an icon, select an icon from the icons popup, and click Remove icon. When you remove an icon, the icon isn’t deleted. The integration contains a link to the icon, but you can’t select the icon again.

On-premises instance

Microapps service allows you to connect your on-premises System of Record (SoR). On-premises integrations do not permit HTTP base URLs. 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 top left menu.
3. Find the resource location you want to use and select the ID icon below the resource name to reveal the ID of your resource location.
4. Copy the resource location ID.
5. Paste the location ID into the On-premises instance resource location field in the Add HTTP Integration screen.
6. (Optional) disable SSL certificate validation if you require your integration to accept unsigned certificates.

Your on-premises integration is configured.

Set up Service Authentication

When configuring your HTTP Integration service authentication, you must set up your service account with your target application (System of Record). You must also possess both read and write privileges in your target application if you are using the service account to write data to your 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 four 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.
• Implicit Flow - Implicit grant type is present only for Service action authentication and only in developer mode. You can set response type either to token or id_token. Automatic access token refresh is not provided. You must provide consent again when the access token expires.

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:

• 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.
• Token URL - Define the URL of the access authorization token.
• Refresh token URL - (Optional) Define the refresh token URL of the access authorization token. If not set, the Token URL is used.
• 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.
• Relay state allows you to configure authentication that enables users to access certain microapps without needing reenter their credentials.

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

Relay state

Relay state can only be used if the following conditions are met:

• You use Okta as your identity provider.
• The target SoR supports Okta as its identity provider.
• Relay state is enabled and configured correctly with the correct Okta URL.

After a successful Okta setup, enter the SingleSignOnService URL provided by Okta into the Relay state Okta URL field for your integration. For example: https://{your Okta}.okta.com/app/{SoR ID}/{ID}/sso/saml.

Relay state works only with user actions and not with full/incremental sync and only passes end user credentials. Some SoRs require end users to confirm a consent page and configuring RelayState does not remove this requirement.

Additional information on configuring Okta can be found in Okta’s official documentation. For example you can view how to configure Okta in Salesforce in How to Configure SAML 2.0 for Salesforce.

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.

Where to go next

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

• Configure the integration