In this blog post you will learn how to setup custom domains for SAP Integration Suite integration runtime based on Cloud Foundry when the subaccount is on the main landscape of the same region (e.g. eu20) and your Integration Suite service is created for the extension landscape (e.g. eu20-001).

The setup is a bit different compared to the documentation available in help.sap.com as of the writing of this blog and most of the blogs published are pointing to the Cloud Foundry CLI which will not work for this specific configuration.

To keep this blog to the point the focus is to provide detailed steps and information for this case. Information about obtaining a certificate or updating DNS records are only briefly touched.

Prerequisites

To follow the steps explained please make sure you have or gathered:

• Administrator access to the subaccount in which Integration Suite is running. To be able to
  • Setup Custom Domain Manager
  • Setup authorization
• SAP Integration Suite is setup and running. Launchpad is accessible.
• DNS administrator authorization.
• Certificate administrator authorization.

Knowing the difference between extension and main landscape. Below an example but it applies to all regions supported:

• Main landscape = eu20
• Extension landscape = eu20-001

Integration Suite extension landscape validation

Before going to the next paragraphs in this blog validate you have your subaccount in another landscape compared to the Integration Suite. This is an easy validation:

1. Login to the BTP cockpit and navigate to the subaccount containing the Integration Suite service overview tab and look for the API endpoint in the Cloud Foundry Environment section:
2. Open the SAP Integration Suite application/launchpad from the BTP cockpit:
3. In the URL you will see the landscape used:
4. If you see something like -000 behind the main region this means the SAP Integration Suite is using the extension landscape of the region. Be aware this is the case for API proxies, integration flow runtimes but doesn’t have to be the case for API business hub enterprise (formerly known as API developer portal).

If your subaccount matches the region including possible -000 for integration suite the custom domain can be setup via the normal procedure. Otherwise please follow the rest of this blog.

Configuration steps – Custom Domain manager setup

As mentioned the Cloud Foundry CLI with the custom domain plugin cannot be used for the extension landscape setup as described above. The Custom Domain Manager is a UI-based web application available within the service marketplace of the subaccount. To setup custom domains for integration suites at the extension landscape when the subaccount is at the main landscape follow the below steps and in my setup Custom Domain Manager is configured in one of the subaccounts containing an SAP Integration Suite:

1. Login to the BTP cockpit and navigate to the subaccount containing the Integration Suite service.
2. In the entitlement menu within the subaccount assign the custom domain service and only the standard (Application) plan:
3. After the assignment is completed in the services->instances and subscriptions menu create an instance for the standard plan. After the services is provision first assign the correct authorization to use it.
4. A role collection needs to be created containing the roles and assign it to the person doing the rest of the activities:
   • CustomDomainAdmin
   • CustomDomainViewer
5. If you open the application no error prompt should be shown. If this is the case this part is completed.

Configuration steps – Custom Domain SaaS subscription setup

The Custom Domain Manager need to be open to perform the next steps.

1. Start with adding a reserved domain to the Custom Domain Manager application by navigating to the menu at the top called Domains and click the button Add Reserved Domain. This will open a pop-up window to enter the domain for which the certificate will be or is created via the Custom Domain Manager.
   • My advice is to enter the main domain including the subdomain. If you use a second custom domain for the same region and main domain you will run into the error:
2. After the reserved domain is added in the other tab called custom domains register the custom domain via the button Create Custom Domain and option for you Subaccount’s SaaS subscription:
3. In this step it is very important to select the Integration Suite application in the correct landscape. You cannot use a custom domain linked to the main landscape for the extension landscape and vice versa:
4. In the next step of the wizard you select the created reserved domain from step 1 and if you already specified the subdomain in step 1 you can leave it empty in the last step of the wizard. If all goes well it should shown one entry in the custom domain tab something like below:
5. Before setting up TLS and the server certificate a SaaS route need to be created. In the top menu navigate to SaaS Routes and if you first setup the SaaS routing for the SAP Integration Suite service in the same subaccount you can leave the checkbox Continue with current subaccount’s list of subscriptions selected. If you setup Custom Domain Manager in another subaccount make sure you selected the correct extension landscape for the custom domain as described in step 3. Provide the TenantID from the other subaccount available in the subaccount Overview menu. After supplying it and it finds a matching landscape the next step button will be clickable and you can select the Integration Suite to be linked. For possible issues please see the troubleshooting section of this blog.
6. Update the standard route to the runtime URL otherwise endpoints/iFlow cannot be called via this setup. The runtime URL can be found in the integration suite monitoring menu and navigate to an deployed artifact containing e.g. a HTTP adapter:
7. After selecting a hostname for the route it should be completed for the Saas Route part. To be able to use the custom domain you need to create TLS record and server certificate. The server certificate is created from within Custom Domain Manager via the CSR procedure meaning you cannot use an already existing certificate. Standard documentation can be followed with some small additions:
   • Give the TLS configuration a sensible name. I used the complete custom domain including subdomain and post-fixed it with: tls. The rest is following the wizard.
   • For the Server Certificate I used a wild-card certificate specific for this purpose. This has the advantage if in the future an additional SAP Integration Suite environment is added the certificate doesn’t have to be changed related to the SAN names activated for it compared to if you create the certificate specific for the custom domains SaaS Routes. The certificate has the structure *.[subdomain].[maindomain].[extension] in which the star will be the hostname for the Integration Suite runtime.
8. If the above steps are completed the last step is to create the CNAME mapping in the DNS provider. For this step it is important to make the CNAME mapping towards the correct extension landscape. In the help.sap.com documentation at the moment of writing this blog it states to use the API endpoint from the subaccount as described in step 1 in section Integration Suite extension landscape validation but it needs to reflect the extension landscape. To prevent error:In the CNAME mapping change as example:
   • From main: api.cf.eu20.hana.ondemand.com
   • To extension: api.cf.eu20-001.hana.ondemand.com

Be informed after the custom domain is active, routing activation will take maximum 24 hours, you can still use the default domain for integration endpoints. Only exception is the OAuth token URL (authentication) this one is only available with the standard SAP domain as described in note 3291485.

Possible solution for the OAuth URL if API management is used, is to create an API proxy with a custom domain and use the integration OAuth token endpoint as target so you don’t have to use the standard domain.

Troubleshooting

During the setup I encountered multiple challenges. I tried to list them all below in random order:

• Cloud Foundry CLI – is not supported for the situation, at least not for the routing etc. If you try to create a SaaS route for Integration Suite when you created a custom domain for the CF organization (for re-usables purposes) it will throw the below error:
• Cloud Foundry CLI – cannot list domains for a landscape other then the API endpoint provided in the subaccount. In the API endpoint provided in the subaccount it will state no domains configured and if you try to use the extension landscape you get an unauthorized error message.
• Cloud Foundry CLI – sharing custom domains certificates is only possible within the same landscape. You cannot share across landscapes in the same region for example eu20 and eu20-001.
• Custom Domain Manager – Custom Domain created for CF organization in the main landscape (eu20) cannot link with services in subaccounts in the extension landscape (eu20-001). If you try to create a SaaS Route for another subaccounts subscription after entering the TenandID you will get this generic error message:
• Custom Domain Manager – First the setup for custom domain in our organization was in another subaccount not containing an Integration Suite or a service in the extension landscape and when creating a custom domain for your CF organization or Saas Subscription you can only select the landscape linked to the subaccount (CF organization) or for the Saas Subscriptions in the same subaccount. Currently it is required to use custom domain in the same subaccount as the one of the integration suite environments.

Conclusion

When the steps are known to get custom domains setup for Integration Suite in the situation mentioned in this blog it is pretty easy and straightforward. It seems I encountered a situation which is not that common and especially in combination with custom domains.

Documentation & Links

If you like to read more information about custom domains and the setup it requires for other cases I can recommend reading the below helpful information:

• Developer tutorial Custom Domain Manager: https://developers.sap.com/tutorials/btp-custom-domain-manager-getting-started.html
• SAP Blog from Denys van Kempen for applications: https://blogs.sap.com/2022/10/07/sap-btp-developer-onboarding-custom-domains/
• Help.sap.com documentation Custom Domain Manager: https://help.sap.com/docs/CUSTOM_DOMAINS/6f35a23466ee4df0b19085c9c52f9c29/4f4c3ff62fd2413089dce8a973620167.html?locale=en-US

If you have questions or remarks please be so kind to leave a comment. A like is appreciated.