For SAP Business Technology Platform (BTP), the btp command-line interface (CLI) is the alternative to the SAP BTP Cockpit for all users who like to work in a terminal or want to automate operations using scripts. With the btp CLI you can execute both account management operations and service management operations. The btp CLI documentation provides details and there are introductory tutorials available as well, like Get Started with the SAP BTP CLI. The btp CLI is applicable to SAP BTP accounts using Feature Set B, which is now (December 2022) almost all SAP BTP accounts.
With the availability of SAP HANA Cloud as a multi-environment service, the btp CLI becomes the main CLI for HANA Cloud administration, as well as for other SAP BTP services, and HANA Cloud-specific documentation is provided here.
Despite these resources, there is one gap I found difficult to address: hence this blog post. How do you run the btp CLI securely in an automation script, when the btp login command requires a password, and (if two-factor authentication is enabled) a time-sensitive code to be entered manually? The approach here relies on SAP Identity Authentication Service (IAS). IAS is the recommended solution for identity management, and for connecting SAP BTP to external identity providers.
(The same approach applies to the Cloud Foundry cf CLI. Most of the steps are the same, and the cf login command is listed where it is relevant below)
The post goes through the process step by step, but here's an overview:
As the passcode is good only for one login, it does not introduce security problems to supply it when connecting. The curl command does reference the PK12 file, but it does not send the private key over the network.
This blog post does not deal with obtaining SAP IAS. If you are a customer, you buy IAS and get an e-mail containing a link to the landing page of the administration console for Identity Authentication. You can confirm the registration of your first administrator user. The IAS administration console has a URL of the form
https://<tenant ID>.accounts.ondemand.com/admin
The tenant ID may be a user-friendly name: for example, for our HANA Cloud product management accounts, we might have a tenant https://hanapm.accounts.ondemand.com.
From here on, we assume you are (or can talk to) an IAS administrator with rights to add users and change IAS settings. See this documentation page for how to assign authorizations in IAS.
The documentation for this step is here. From the IAS administration console, go to Applications & Resources > Tenant Settings
Enable certificate authentication for the user type that corresponds to your technical user (probably "employee")
To log in with the btp CLI using IAS as the identity provider, you must establish trust with the IAS tenant at the global account level (not just from within an individual subaccount). For instructions on how to do this from the BTP Cockpit, see the documentation.Once you've done this, you'll see a value in the BTP CLI column ("hanapm" in the screenshot below). This is the tenant ID and you'll need this when logging in with the btp CLI.
To carry out operations within a subaccount, you will need to establish trust within the subaccount as well. Again, you do this from the BTP Cockpit by going to the subaccount and then choosing Security > Trust Configuration.
From the IAS administration console, go to Users & Authorizations > User Management and add a user. Here I'll use technical_user_1@sap.com (an email address which, so far as I know, does not correspond to anyone). Mark them as a category that has certificate authentication enabled, and check the E-Mail Verified box to prevent an email being sent to check the recipient. The user will need a password, which you will enter to generate a certificate.
Depending on the tasks you want to carry out from your automation scripts, the technical user will need some appropriate roles in your BTP account. If you want the script to list all subaccounts, for example, you will need to grant it the Global Account Viewer role collection. If you want to work with HANA Cloud databases you will need to grant it the HANA Cloud Administrator role collection in whichever subaccounts you want to use.
As you add the user to the global account and any subaccounts you need, remember to specify the IAS tenant as the custom identity provider, so that the IAS credentials can be used to log in.
The IAS and BTP Cockpit setup is now all done (so long as you've made no mistakes. I certainly went through this more than once). Now you need to act as the technical user and connect. The first step is to generate a certificate.
In your browser, go to the IAS user profile page at https://<tenant-id>accounts.ondemand.com and log in as the technical user, using the IAS password you defined when creating the user.
You should see a Certificates tile in the page.
Click generate, provide a password for the certificate. A file named cert.p12 is automatically downloaded to your computer, which is a PK12-encoded bundle of a private key and an X.509 certificate. You should keep this file in a location that is accessible to the btp cli but protected from other users.
You need to run two commands to connect. For these to work, you need a relatively recent version of both the curl and btp command-line tools. It is also helpful to have the jq command-line tool to extract information from the JSON document that is a response to the curl command.
Step one is to obtain a one-time passcode, which you do using a command like this:
The response is a JSON document containing the passcode:
{"passcode":"crxng855xt71t12hn08bwc1xkv7"}
Here is a way to run this command from a bash shell script, storing the passcode (without quotation marks) in the variable ias_passcode:
You can then supply this passcode, which is valid for only one login and for five minutes, in the password field of the btp login command:
And that should, if you are lucky, be it.
You can also login with the cf login command using the same approach. Supply a one-time passcode as the password and supply the --origin option with the "Origin Key (Cloud Foundry)" from BTP Cockpit (see the screenshot in the "In BTP Cockpit, establish trust with IAS" section above. The cf login command:
A few troubleshooting tips:
With the availability of SAP HANA Cloud as a multi-environment service, the btp CLI becomes the main CLI for HANA Cloud administration, as well as for other SAP BTP services, and HANA Cloud-specific documentation is provided here.
Despite these resources, there is one gap I found difficult to address: hence this blog post. How do you run the btp CLI securely in an automation script, when the btp login command requires a password, and (if two-factor authentication is enabled) a time-sensitive code to be entered manually? The approach here relies on SAP Identity Authentication Service (IAS). IAS is the recommended solution for identity management, and for connecting SAP BTP to external identity providers.
(The same approach applies to the Cloud Foundry cf CLI. Most of the steps are the same, and the cf login command is listed where it is relevant below)
The post goes through the process step by step, but here's an overview:
- Set up trust between your SAP BTP global account and your IAS tenant.
- Configure your IAS tenant to enable certificate generation and authentication
- Define a technical user in IAS and generate a certificate. The certificate is a PK12 bundle that contains both a private key and a public key, and you need to keep it secure in a location where the btp client can have access to it.
- Grant the technical user the role collections it needs in your SAP BTP account.
- To login from an automation script, first use the curl command-line utility together with your certificate to obtain a passcode, which is good only for one login attempt and for a short time (five minutes)
- With the btp CLI, login, supplying the passcode in the password field.
As the passcode is good only for one login, it does not introduce security problems to supply it when connecting. The curl command does reference the PK12 file, but it does not send the private key over the network.
Set up IAS
This blog post does not deal with obtaining SAP IAS. If you are a customer, you buy IAS and get an e-mail containing a link to the landing page of the administration console for Identity Authentication. You can confirm the registration of your first administrator user. The IAS administration console has a URL of the form
https://<tenant ID>.accounts.ondemand.com/admin
The tenant ID may be a user-friendly name: for example, for our HANA Cloud product management accounts, we might have a tenant https://hanapm.accounts.ondemand.com.
From here on, we assume you are (or can talk to) an IAS administrator with rights to add users and change IAS settings. See this documentation page for how to assign authorizations in IAS.
Configure IAS to enable certificate generation and authentication
The documentation for this step is here. From the IAS administration console, go to Applications & Resources > Tenant Settings
IAS Tenant Administration
Enable certificate authentication for the user type that corresponds to your technical user (probably "employee")
In BTP Cockpit, establish trust with IAS
To log in with the btp CLI using IAS as the identity provider, you must establish trust with the IAS tenant at the global account level (not just from within an individual subaccount). For instructions on how to do this from the BTP Cockpit, see the documentation.Once you've done this, you'll see a value in the BTP CLI column ("hanapm" in the screenshot below). This is the tenant ID and you'll need this when logging in with the btp CLI.
BTP Cockpit (global account)
To carry out operations within a subaccount, you will need to establish trust within the subaccount as well. Again, you do this from the BTP Cockpit by going to the subaccount and then choosing Security > Trust Configuration.
Create a technical user in IAS
From the IAS administration console, go to Users & Authorizations > User Management and add a user. Here I'll use technical_user_1@sap.com (an email address which, so far as I know, does not correspond to anyone). Mark them as a category that has certificate authentication enabled, and check the E-Mail Verified box to prevent an email being sent to check the recipient. The user will need a password, which you will enter to generate a certificate.
Grant the technical user roles as needed in BTP Cockpit
Depending on the tasks you want to carry out from your automation scripts, the technical user will need some appropriate roles in your BTP account. If you want the script to list all subaccounts, for example, you will need to grant it the Global Account Viewer role collection. If you want to work with HANA Cloud databases you will need to grant it the HANA Cloud Administrator role collection in whichever subaccounts you want to use.
As you add the user to the global account and any subaccounts you need, remember to specify the IAS tenant as the custom identity provider, so that the IAS credentials can be used to log in.
Generate a certificate
The IAS and BTP Cockpit setup is now all done (so long as you've made no mistakes. I certainly went through this more than once). Now you need to act as the technical user and connect. The first step is to generate a certificate.
In your browser, go to the IAS user profile page at https://<tenant-id>accounts.ondemand.com and log in as the technical user, using the IAS password you defined when creating the user.
You should see a Certificates tile in the page.
Generate a certificate
Click generate, provide a password for the certificate. A file named cert.p12 is automatically downloaded to your computer, which is a PK12-encoded bundle of a private key and an X.509 certificate. You should keep this file in a location that is accessible to the btp cli but protected from other users.
... and connect
You need to run two commands to connect. For these to work, you need a relatively recent version of both the curl and btp command-line tools. It is also helpful to have the jq command-line tool to extract information from the JSON document that is a response to the curl command.
Step one is to obtain a one-time passcode, which you do using a command like this:
curl \
--cert-type P12 \
--cert ./cert.p12:<certificate password> \
https://<tenant-id>.accounts.ondemand.com/service/users/passcodeThe response is a JSON document containing the passcode:
{"passcode":"crxng855xt71t12hn08bwc1xkv7"}
Here is a way to run this command from a bash shell script, storing the passcode (without quotation marks) in the variable ias_passcode:
ias_passcode=$(curl \
--no-progress-meter \
--cert-type P12 \
--cert ./cert.p12:${cert_password} \
https://${idp_id}.accounts.ondemand.com/service/users/passcode \
| jq -r ".passcode")You can then supply this passcode, which is valid for only one login and for five minutes, in the password field of the btp login command:
btp login \
--url https://cpcli.cf.sap.hana.ondemand.com \
--idp <tenant_id> \
--subdomain <global_account_subdomain_id> \
--user technical_user_1@sap.com \
--password ${ias_passcode}And that should, if you are lucky, be it.
You can also login with the cf login command using the same approach. Supply a one-time passcode as the password and supply the --origin option with the "Origin Key (Cloud Foundry)" from BTP Cockpit (see the screenshot in the "In BTP Cockpit, establish trust with IAS" section above. The cf login command:
cf login \
-a <cf-api-endpoint> \
-u technical_user_1@sap.com \
-p ${ias_passcode} \
-- origin <origin-key>A few troubleshooting tips:
- The support for "cert-type P12" in curl is relatively recent. If you have only an older version of curl, you may have to split the PK12 file into separate private key and certificate files using (for example) openssl, and then supply those on the curl command line. (Please add a comment if you need this and I'll add the commands).
- The support for --idp in the btp CLI is also relatively recent. You can get the most recent version from SAP Development Tools (ondemand.com).
- If your login attempt is refused, you may want to try interactively, first supplying the technical user password (not the one-time passcode) as the password. This will tell you if you have the user and authentication set up properly. After that, try the one-time passcode instead of the password.
- SAP Managed Tags:
6 Comments
