Setting up SAPGUI SSO on a Linux client
Encryption and SSO (Single Sign-On) for SAPGUI logins from a Linux client machine can be set up using X.509 certificates.
[Currently, SAP does not provide a Linux version of their SAP Secure Login Client (which is a software utility that usually uses Kerberos tokens, though the X.509 certificate method is also supported) – as of March 2023, Secure Login Client only available for Windows and macOS, so not in scope for this blog about Linux].
We first consider getting encryption-via-SNC working, so that even when doing manual (password-based) logins, at least the communication is encrypted, and thus not vulnerable to being deciphered by Wireshark or whatever. The idea of encryption is that as both the client machine and the SAP server can use the SAPCRYPTOLIB, and the public key certificate presented by the client machine is in the trusted certificate list of the SAP system’s SAP Cryptolib PSE, then the SAPGUI-traffic between client and server is encrypted and thus protected from being deciphered by bad actors.
Then in a second iteration of the setup (section “Using SSO”) we set up the full SSO for SAPGUI over SNC, using an X.509 certificate to logon. The idea of SSO is that the client machine presents a (public key) certificate identifying a SAP user by their SNC name to the target SAP system, and if that certificate is in the trusted certificate list of the SAP system’s SAP Cryptolib PSE, then the SAP system will allow the logon attempt. (We can thus consider SSO-over-SNC as a functionality-superset of Encryption-over-SNC).
We don’t consider much about what SAP server-side config should look like for this client-side logon method to work (beyond some necessary activity in tcode STRUST) – instead, we just assume that the SAP system is setup for SNC in the right way already. [A blog I wrote that shows how to do the SNCwizard setup for server-side config is here:
Note: this blog is the verbose-and-extended version of the excellent advice (which I followed) from Rob Liversage that he provided in a comment elsewhere on this SAP website – so if you prefer the concise original advice on how to get this stuff working, then it’s here:
Getting the media and basic preparation
[Update May 2023: SAPGUI for Java 7.80 now ships with the needed sapcryptolib, see comment from Johannes Gerlich below: https://blogs.sap.com/2023/03/27/setting-up-sapgui-sso-on-a-linux-client/comment-page-1/#comment-673019 We leave the below advice as-is though – officially as blogs are essentially always a historical snapshot, and unofficially to save the lazy author having to do much editing work].
On the Linux client machine, you need to download (or copy over to the machine) the SAPCRYPTOLIB archive… so for this, you need an S-user with Software Download rights (or you need to know someone in your organisation with such rights – ask them nicely for help, explain your use case and business case, etcetera etcetera).
[.. since Q2 2023 the new-look Software Centre is at https://me.sap.com/softwarecenter ]
Search on “sapcryptolib”, choose the non-versioned answer and go to Maintenance Software Component. Then choose the correct OS architecture from the box, “LINUX ON X86_64 64BIT” (as of March 2023, SAP haven’t yet provided an arm64(a.k.a. aarch64) SAPGUI for Java for Linux, which means that amd64(a.k.a. “X86_64”) OS architecture is therefore the only viable option for sapcryptolib also), and the latest version, then the I-Ching-like icon “Related Info” and then “Content Info”:
Then download the .SAR file.
To unpack the SAP ARchive, you need a utility called SAPCAR… again we are in Software Downloads, and this time search on “sapcar”. Again choose the non-versioned SAPCAR, Maintenance Software Component. And again choose the correct OS architecture, then download via Content Info…
Copy the SAR and the SAPCAR files over to your Linux machine in case you downloaded them using a different machine. Once you have both the SAR and the SAPCAR in some folder on the Linux machine, you can unpack the SAR archive. (If the SAPCAR isn’t executable yet, first make it so using chmod).
chmod +x SAPCAR_1115-70006178.EXE
./SAPCAR_1115-70006178.EXE -xvf SAPCRYPTOLIBP_8548-20011697.SAR
Now in your folder you will have the newly extracted sapgenpse utility (and a few other files), so this sapgenpse is what we need for the next steps.
Then it will be a good idea to define two environment variables – either in your bash profile at ~/.profile; or, in my case I just used the /etc/environment file – since this is a one-user machine, no problem… (if instead there would be multiple users, or if you don’t have sudo-permissions, it would be better to use e.g. each user’s ~/.profile). Anyway in this example, elevating ourselves with sudo, we edit /etc/environment, using nano or whatever you prefer:
sudo nano /etc/environment
Add then save these two lines to the file (obviously you adjust the example filepaths according to your own case):
The first environment variable says where libsapcrypto.so is located (same location as wherever sapgenpse is, since these were unpacked together). This is needed by SAPGUI for Java client software, when any SNC-related connections to SAP should be established.
The second environment variable identifies the directory where the SAPSNCS.pse is going to be created via sapgenpse’s get_pse command. It’s a good idea to create this directory now (i.e. before you use get_pse):
Then logout and login, so the new environment variables of /etc/environment (or ~/.profile) get picked up.
Remember kids, the SNC tricks of this blog are only going to work, if your SAP system has been configured to accept X.509 certificates.
The SNC parameters would be visible in RZ10 (typically in the Default profile of the SAP system), but we are not going to review those here, as this blog is not about configuring server-side SNC.
Using SNC encryption only
In this section we are considering a scenario, where you are happy enough with password-based logins, but you would like (or need, or demand) all the SAPGUI traffic to be encrypted.
We deliberately generate a “dummy client certificate” that will not enable us to do SSO, so we specify a nonsense subject line, one which does not correspond to the SNC name of any SAP user in the target system.
When generating the certificate, be sure to call the new PSE created exactly as follows: SAPSNCS.pse …whereas for the actual CN= and O= details, you can make those up yourself:
./sapgenpse get_pse -s 2048 -p SAPSNCS.pse "CN=sapsnc O=murmelssonic"
[Using the code-sample format so that copy-pasted quote-marks work properly].
You can hit <Enter> (twice), to avoid password-protecting your new PSE file, or you can supply a password (I didn’t as nobody else has access to my Linux VM).
So this creates a so-called PSE (“Personal Security Environment” – SAP terminology), but for our purposes it is enough to think of this as creating a public key certificate (and a private key), contained in the PSE file. And that PSE file is created in whatever filepath you defined as the SECUDIR above in “Getting the media and basic preparation”.
Next step is to go to the SAP system you want SNC logon to work with, and download (export) the relevant certificate. Obviously it helps a lot if you can already logon to the target system e.g. via password logon, or via SSO from a MacBook or Windows machine, and then you also need rights to tcode STRUST… if this is more access than you have, then hopefully you know someone who can get and send you the exported certificate.
So in our example we do a password login to an SAP system (in our case SID=NPL), then go to STRUST, double-click on left-hand menu under SNC Cryptolib (if this doesn’t exist, you are not going to be doing SNC login so you can stop reading), then double click on the subject field of the SNC SAPCryptolib “Own certificate” in the right-hand pane, so that its details appear lower down the page, then choose menu Certificate -> Export…
Choose Binary or Base64 format (doesn’t matter), choose a location on your local computer, give this certificate a filename and Save it. If you saved it to another computer, then copy it across to your Linux machine. So my copy of the exported SAP system certificate is stored in ~/sapstuff along with the sapgenpse utility files; called it sncnpl.cert, but obviously you can call your exported server certificate whatever you like.
Next step is to use this downloaded certificate and import it to the certificate list of the Linux VM’s PSE bundle, so we use sapgenpse utility for that also (in directory ~/sapstuff in my case):
./sapgenpse maintain_pk -v -a sncnpl.cert -p SAPSNCS.pse
Then, we want to export our newly modified certificate of the PSE, as follows:
./sapgenpse export_own_cert -p SAPSNCS.pse
This command runs and then displays the output (exported) X.509 certificate in the terminal window you executed the command in. You need to now copy-paste the text beginning with line —–BEGIN CERTIFICATE—– and ending with line —–END CERTIFICATE—– (including those two lines in the block of text)… and save that text to a new file, using nano, or vi, or any text editor you like. My example is called exportedlocal.cert:
Back on the SAP server in STRUST, we go into Change mode, make sure the SNC SAPCryptolib certificate is still in focus (double-click on its subject line to make sure it appears in lower window), then scroll down to right-hand window near the bottom of the page, and click on Import certificate icon… then upload your exportedlocal.cert from local machine to server. Then click on Add to Certificate List, and Save the STRUST transaction from the upper menu.
So the list should now contain the relevant uploaded certificate:
Once this is done, you can attempt to logon to the SAP system using a Connection Item with SNC enabled – and e.g. Encryption only or Max. Available options, in the Security tab of the Connection Item.
In SAPGUI for Java, you Create New Connection Item, then click on the Message Server list button, Create New Message Server, specify the SID e.g. “NPL”, the hostname e.g. “vhcalnplci”, and the port e.g. “3601” (Message Server has port 36nn where nn is Instance Number of ASCS server). Then Save.
Note that in this client side configuration, the (SAP system’s) “SNC name”-field should appear as Display-only (greyed-out) info provided from the SAP system’s Message Server – it should contain the SNC SAPCryptolib name of the SAP system as defined in STRUST, plus the prefix “p:” to match it with its relevant RZ10 parameter-value for parameter “/snc/identity/as”; so if the SAP system has, say, “CN=NPL” as value of Subject in SAPCryptolib certificate, then in the SAPGUI client configuration, it would appear as “p:CN=NPL”.
Although in this section’s scenario case there is (by design) no known SAP user with dummy SNC Name “p:CN=sapsnc O=murmelssonic”, so SSO will not be working, however the sessions will be encrypted, so no Wireshark eavesdroppers or other bad actors will be able to see your username and password when you do login, nor will they see any transaction data when you work in the SAPGUI session.
Your connection attempt should result in being presented with the standard manual login screen (with the warning message at bottom of screen that (SSO is not possible as) no such user with that SNC name):
So on this standard SAP logon screen you enter your SAP username and password, login, and the whole session (including, importantly, your login attempts) is encrypted by SAP SNC – which is what this section’s scenario wanted to achieve.
Since from our previous activity for SNC encryption only, we currently have the file ~/sec/SAPSNCS.pse, which defined a nonsense subject, so as preparation for this section’s SSO enablement, what we need to do is get rid of that file (delete it); or in case we might want to switch back to using it later, then we could just rename that PSE to make it a backup file. So choose one of these two commands, according to your preference:
mv SAPSNCS.pse SAPSNCS.pse_bac
So we have created space for a new SAPSNCS.pse (as that is what it must be named) which we are now going to generate, again using the sapgenpse utility… but first, in the SAP system (NPL) and the SAP client (001) you are interested in, check if our SAP user MARMOT has an SNC name defined, and if not, we define it. So the tcode is SU01. Change User. Go to the SNC tab, in our case we define an SNC Name (add “p:” as prefix to Subject line of the local SAPSNCS.pse we are about to generate) and also allow password login. So we have:
The build command you would need this time for your new PSE is then:
./sapgenpse get_pse -s 2048 -p SAPSNCS.pse "CN=MARMOT@GARP.RHUBARB"
Then you modify the new Linux VM’s PSE by importing via maintain_pk the file you exported from the SAP server previously (see section above “Using SNC encryption only” for details):
./sapgenpse maintain_pk -v -a sncnpl.cert -p SAPSNCS.pse
…and then you export the updated X.509 certificate:
./sapgenpse export_own_cert -p SAPSNCS.pse
…and save the output certificate details from your terminal to a new file (again see previous section for details on copying and saving the relevant block of text); i called this file exportedlocaldd.cert but of course you can call yours whatever you like.
Then import this exportedlocaldd.cert to the Certificate List of SNC SAPCryptolib PSE in STRUST of the target SAP system, just as we did for the other X.509 certificate in the previous section. Remember to Save your changes.
Now that the client certificate for our subject CN=MARMOT@GARP.RHUBARB is in the trusted certificate list, so the logon from Linux VM to the relevant SAP system will work by SSO. Before testing the login, it’s a good idea to quit SAPGUI software client altogether then reopen it, so that SAPGUI caches the latest version of SAPSNCS.pse from your SECUDIR (and doesn’t e.g. keep any cached details from the previous file that was called SAPSNCS.pse, which we were using in the above section “Using SNC encryption only”).. So yeh, then you reopen the SAPGUI client, and logon to the target SAP system e.g. by double-clicking the relevant Connection Item. Then as if by magic, a success message:
“SNC Logon by 001 MARMOT for p:CN=MARMOT@GARP.RHUBARB”
…appears in the bottom bar of the SAPGUI screen, informing you of this SSO logon event:
…so that completes our task of getting SSO for SAPGUI working on a Linux client. Time for an ice-cream!
The Linux client I used was Xubuntu 22.04, haven’t tested this on any other Linux distros – good luck now with whatever distro and release you are using!
Also note: this blog doesn’t operate a Helpdesk, so you might need to BYODS (Bring Your Own Debugging Skills). If there were some errors in my explanations though, feel free to point those out and I will try to improve the text. (Questions about server-side or AD-side configuration steps for SNC, are not considered in the blog, and of course I have no way of knowing if your or your organisation’s SNC configuration is suitable or enabling for the client-side config scenarios described below, so hopefully the comments section won’t be getting filled with chat about such server-side topics 🙂 ).
[For Apple MacBook users, there is the macOS sibling-blog to this one, which is rather long due to covering server-side SNC config with SNCwizard and due to there being more MacBook options to demo – PSE-Method like for Linux, plus SLC-Method using SAP Secure Login Client; also there are differences between using amd64 MacBook and arm64 (M1, M2..) MacBook. Anyway here is the link:
And then I even did a Windows version in case anyone is interested: