Introduction
In this blog post you will learn how to setup and activate custom domains (standard setup not mTLS) for SAP Integration Suite API management runtime based on Cloud Foundry via de self-service procedure. If you already have a custom domain activate and in the past this was performed by SAP, this is the blog for you.
To keep this blog to the point the focus is to provide detailed steps and information for this case. Information about obtaining a certificate, create a virtual host for API Management 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:Provide required authorizationsCreate/Update service keysSAP Integration Suite, API management is setup and running. Launchpad is accessible.SAP API management a test API is published and working with the standard SAP domain.DNS administrator authorization or a contact within the organization authorized to perform the required activity.Certificate administrator authorization or a contact within the organization authorized to perform the required activity.A HTTP Client like Postman for executing API calls.Access to api.sap.com for details on the required API actions
API Management Service key
Before we are able to call any APIs for information and activities with API management it is important a service key is created with specific authorizations: APIManagement.SelfService.Administrator using the plan apiportal-apiaccess. To create an instance you need to navigate towards: Home page Global account->subaccount for integration suite->left hand menu Services->Instances and subscriptions->create instance with the following details, using the correct Space:
As a result the output should look like below:
This service key is required for all upcoming activities to validate existing virtual hosts and create/update a virtual host for custom domain usage.
APIM virtual host overview
Assumption is the service key is created and active. As a first step try to retrieve a token for the service key, my examples are from Postman:
As noticed you can here also validate when the response is positive the authorization is properly linked.
After this step is completed you can call the endpoint:
{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests
with the hostname from the service key, with the HTTP GET method this should result in the overview of virtual hosts for the API Management instance. If you currently only have the SAP standard domain this is the only record to be returned.
APIM create virtual host (optional)
This step is optional and only required if not additional virtual host is already created
A virtual host for APIM can easily be created calling the endpoint:
{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests including the body as:
APIM read virtual hosts – available
Retrieving all virtual hosts for an APIM instance is handled via the same URL mentioned a couple of times in this blog:
{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests
a response looks like:
Important fields are highlighted which are required to create/update a custom domain for the created virtual host.
APIM create keystore for custom domain
Compared to SAP Cloud Integration custom domain which is handled via de Custom Domain Manager UI for APIM this is not working in the same concept. This also means the required certificate needs to be created differently and more information is required. For APIM a certificate needs to be bought/requested from the used CA within the company without using an CSR from SAP. In this blog we are using a wildcard certificate which is used for all APIM environments.
The certificate details you need to create a keystore are:
private key public keycertificate chain including root and intermediate certificates
Important is that the certificate needs to be in a .pem format. In our case we already get the certificates delivered in .pem format. It is important the the public key part including the certificate chain is created in the following order in which the first entry is at the top:
public key client certificateintermediate certificates (if any is available)root CA
And saved as a .pem file. The exact steps to create the keystore including the required content is described in SAP documentation: https://help.sap.com/docs/integration-suite/sap-integration-suite/manage-certificates . To create a JAR file we used the JAVA JDK as a download (not required to install) in combination with PowerShell:
In PowerShell the following commmands are used:
Create JAR keystore: {location java JDK}binjar -cf customdomain.jar main.pem privateKey.pemUpdate JAR keystore with META-INF information: {location java JDK}binjar -uf customdomain.jar META-INF/descriptor.properties
When the creation is successful this keystore needs to be uploaded.
APIM upload keystore for custom domain
The upload step is very simple. Navigate within SAP Integration Suite overview page towards: Left hand menu Configure->APIs->Tab: Certificates :
and click the create button with the following setup:
Important is to select Key Store and New Store. The Store Name and Name value can be anything you like within the boundaries of what SAP allows and in the upload field you need to select the created JAR file. If you select update it will give a warning the create is the approach. In case you select update and you upload a new certificate the already existing one is overwritten with the same name.
If the upload is going as expected it will be listed in the tab Certificates.
APIM activate custom domain
If all previous steps are completed successfully, activation can start. Be aware of the following:
The used root CA for custom domain needs to be trusted by applications/systems to be able to make a working connection.Make a decision if the custom domain needs to be the default domain when creating or importing an API proxy. We decided not to use the custom domain as default virtual host.After custom domain activation you need toupdate any existing DNS CNAME records. The target URL will change. However this URL will only be available after the activation is executed via an API call. This target value can be located in field lbHost in the response from the activation when this is positive.redeploy all API proxies using the custom domain and as a second step all API products. This to make sure the correct certificate is used. This is especially important when the custom domain is already used and the certificate chain is changed.
Activation for custom domain is handled via an API call:
{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests
With the following content:
The values in fields virtualHostUrl and lbHost are important for updating the CNAME record in DNS.
APIM create/update custom domain DNS CNAME
To make sure the custom domain can be reached and is forwarded to the correct endpoint a DNS CNAME record is required for every APIM virtual host activated for custom domain. In our case we already had a CNAME record for our custom domain pointing to the standard SAP domain [
virtualHostUrl value -> lbHost value
Be aware in case you use multiple virtual host in an APIM environment the lbHost value might be the same but this is not causing any issues related to call the correct endpoints.
After it is validated via DNS checkers the CNAME record is updated the first step is to activate 1 API proxy and the linked API product and validate the correct routing and certificates are handled. We decided to edit the API proxy and perform a dummy change and updated the revision with details about the redeployment. Other options are also available.
In our case we used temporary a testing endpoint specific for the custom domain validation. We also provided this endpoint to application, system and partner contacts for validation purposes and to request them to validate if the root CA is available in the trust store.
Conclusion
The switch from SAP managed custom domains for our organization towards self-service is a logical one. We got confronted with the self-service approach 5 working days prior to the current certificate expiring which gave us clear time contraints. Luckily the creation of the virtual host and retrieval of the overview of virtual hosts was already known for us and the service key already existed.
Looking at the SAP documentation most steps are stated (high-level) in multiple pages however from our perspective some pieces of documentation raised questions from our end. With a ticket towards SAP we received definitive clarification to get this change done correctly without any disruptions. This is the reason the blog was written.
Hopefully this blog is giving others the insights and information required to make this working properly within the own organization.
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:
Request or update an APIM custom domain: https://help.sap.com/docs/sap-api-management/sap-api-management/requesting-for-custom-domain-for-virtual-host Create a JAR keystore: https://help.sap.com/docs/integration-suite/sap-integration-suite/manage-certificatesConfigure DNS for a custom domain: https://help.sap.com/docs/custom-domain/custom-domain-service/configure-dns-for-custom-domain
IntroductionIn this blog post you will learn how to setup and activate custom domains (standard setup not mTLS) for SAP Integration Suite API management runtime based on Cloud Foundry via de self-service procedure. If you already have a custom domain activate and in the past this was performed by SAP, this is the blog for you. To keep this blog to the point the focus is to provide detailed steps and information for this case. Information about obtaining a certificate, create a virtual host for API Management or updating DNS records are only briefly touched.PrerequisitesTo 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:Provide required authorizationsCreate/Update service keysSAP Integration Suite, API management is setup and running. Launchpad is accessible.SAP API management a test API is published and working with the standard SAP domain.DNS administrator authorization or a contact within the organization authorized to perform the required activity.Certificate administrator authorization or a contact within the organization authorized to perform the required activity.A HTTP Client like Postman for executing API calls.Access to api.sap.com for details on the required API actionsAPI Management Service keyBefore we are able to call any APIs for information and activities with API management it is important a service key is created with specific authorizations: APIManagement.SelfService.Administrator using the plan apiportal-apiaccess. To create an instance you need to navigate towards: Home page Global account->subaccount for integration suite->left hand menu Services->Instances and subscriptions->create instance with the following details, using the correct Space:As a result the output should look like below:This service key is required for all upcoming activities to validate existing virtual hosts and create/update a virtual host for custom domain usage.APIM virtual host overviewAssumption is the service key is created and active. As a first step try to retrieve a token for the service key, my examples are from Postman:As noticed you can here also validate when the response is positive the authorization is properly linked.After this step is completed you can call the endpoint:{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests with the hostname from the service key, with the HTTP GET method this should result in the overview of virtual hosts for the API Management instance. If you currently only have the SAP standard domain this is the only record to be returned.APIM create virtual host (optional)This step is optional and only required if not additional virtual host is already createdA virtual host for APIM can easily be created calling the endpoint: {hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests including the body as:{ “accountId”: “{accountId}”, “virtualHostUrl”: “{desired virtual host prefix}”, “isDefaultVirtualHostRequest”: false, “operation”: “CREATE”}To be sure the virtual host is created it should result in a positive response and it should become visible in APIM within the API proxy section, as example below:APIM read virtual hosts – availableRetrieving all virtual hosts for an APIM instance is handled via the same URL mentioned a couple of times in this blog: {hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequests a response looks like:Important fields are highlighted which are required to create/update a custom domain for the created virtual host.APIM create keystore for custom domainCompared to SAP Cloud Integration custom domain which is handled via de Custom Domain Manager UI for APIM this is not working in the same concept. This also means the required certificate needs to be created differently and more information is required. For APIM a certificate needs to be bought/requested from the used CA within the company without using an CSR from SAP. In this blog we are using a wildcard certificate which is used for all APIM environments.The certificate details you need to create a keystore are:private key public keycertificate chain including root and intermediate certificatesImportant is that the certificate needs to be in a .pem format. In our case we already get the certificates delivered in .pem format. It is important the the public key part including the certificate chain is created in the following order in which the first entry is at the top: public key client certificateintermediate certificates (if any is available)root CAAnd saved as a .pem file. The exact steps to create the keystore including the required content is described in SAP documentation: https://help.sap.com/docs/integration-suite/sap-integration-suite/manage-certificates . To create a JAR file we used the JAVA JDK as a download (not required to install) in combination with PowerShell:In PowerShell the following commmands are used:Create JAR keystore: {location java JDK}binjar -cf customdomain.jar main.pem privateKey.pemUpdate JAR keystore with META-INF information: {location java JDK}binjar -uf customdomain.jar META-INF/descriptor.propertiesWhen the creation is successful this keystore needs to be uploaded.APIM upload keystore for custom domainThe upload step is very simple. Navigate within SAP Integration Suite overview page towards: Left hand menu Configure->APIs->Tab: Certificates :and click the create button with the following setup:Important is to select Key Store and New Store. The Store Name and Name value can be anything you like within the boundaries of what SAP allows and in the upload field you need to select the created JAR file. If you select update it will give a warning the create is the approach. In case you select update and you upload a new certificate the already existing one is overwritten with the same name.If the upload is going as expected it will be listed in the tab Certificates.APIM activate custom domainIf all previous steps are completed successfully, activation can start. Be aware of the following:The used root CA for custom domain needs to be trusted by applications/systems to be able to make a working connection.Make a decision if the custom domain needs to be the default domain when creating or importing an API proxy. We decided not to use the custom domain as default virtual host.After custom domain activation you need toupdate any existing DNS CNAME records. The target URL will change. However this URL will only be available after the activation is executed via an API call. This target value can be located in field lbHost in the response from the activation when this is positive.redeploy all API proxies using the custom domain and as a second step all API products. This to make sure the correct certificate is used. This is especially important when the custom domain is already used and the certificate chain is changed.Activation for custom domain is handled via an API call:{hostname from servicekey URL}/apiportal/operations/1.0/Configuration.svc/VirtualHostRequestsWith the following content:{ “accountId” : “{accountId from read operation}”, “virtualHostUrl”: “{full custom domain with virtual host prefix}”, “isDefaultVirtualHostRequest” : false, “isForCustomDomain”: true, “keyStoreName”: “{created during keystore upload}”, “keyStoreAlias”: “{created during keystore upload}”, “operation” : “UPDATE”, “virtualHostId”:”{virtualHostId from read operation}”}A positive response should look like:The values in fields virtualHostUrl and lbHost are important for updating the CNAME record in DNS. APIM create/update custom domain DNS CNAMETo make sure the custom domain can be reached and is forwarded to the correct endpoint a DNS CNAME record is required for every APIM virtual host activated for custom domain. In our case we already had a CNAME record for our custom domain pointing to the standard SAP domain [test.apimanagement.eu20.hana.ondemand.com] as provided by SAP when they initially handled the custom domain activities for APIM. As mentioned in the previous paragraph the CNAME now needs to be:virtualHostUrl value -> lbHost valueBe aware in case you use multiple virtual host in an APIM environment the lbHost value might be the same but this is not causing any issues related to call the correct endpoints.After it is validated via DNS checkers the CNAME record is updated the first step is to activate 1 API proxy and the linked API product and validate the correct routing and certificates are handled. We decided to edit the API proxy and perform a dummy change and updated the revision with details about the redeployment. Other options are also available.In our case we used temporary a testing endpoint specific for the custom domain validation. We also provided this endpoint to application, system and partner contacts for validation purposes and to request them to validate if the root CA is available in the trust store.ConclusionThe switch from SAP managed custom domains for our organization towards self-service is a logical one. We got confronted with the self-service approach 5 working days prior to the current certificate expiring which gave us clear time contraints. Luckily the creation of the virtual host and retrieval of the overview of virtual hosts was already known for us and the service key already existed.Looking at the SAP documentation most steps are stated (high-level) in multiple pages however from our perspective some pieces of documentation raised questions from our end. With a ticket towards SAP we received definitive clarification to get this change done correctly without any disruptions. This is the reason the blog was written.Hopefully this blog is giving others the insights and information required to make this working properly within the own organization.Documentation & LinksIf 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:Request or update an APIM custom domain: https://help.sap.com/docs/sap-api-management/sap-api-management/requesting-for-custom-domain-for-virtual-host Create a JAR keystore: https://help.sap.com/docs/integration-suite/sap-integration-suite/manage-certificatesConfigure DNS for a custom domain: https://help.sap.com/docs/custom-domain/custom-domain-service/configure-dns-for-custom-domain Read More Technology Blog Posts by Members articles
#SAP
#SAPTechnologyblog
