User Authentication

• Summary
• Environment
• Decoding JWTs
• Accessing APIs as Technical User
• Accessing APIs as User
• Accessing Service APIs
• Example for Saas Service

Summary

The central point of the user authentication commands is obtaining JSON web tokens or JWTs. Either

• to decode them and see which privileges and other information are passed along within them, or
• to use them as authorization for related rest APIs, e.g., services or the server.

Obtaining the tokens always happens through a service instance of the “User Account and Authentication Service” (technical name xsuaa).

For details and background information regarding the service, please consult the official documentation:

• https://help.sap.com/docs/CP_AUTHORIZ_TRUST_MNG
• https://help.sap.com/docs/IDENTITY_AUTHENTICATION
• https://docs.cloudfoundry.org/api/uaa/

Commands for this area are:

   === user authentication (uaa) ===
~  uaad   --uaa-decode TOKEN                                     decode JSON web token
~  uaac   --uaa-client [TENANT]                                  obtain uaa token for generic client
~  uaap   --uaa-passcode PASSCODE [TENANT]                       obtain uaa token for one-time passcode
~  uaau   --uaa-user USERNAME PASSWORD [TENANT]                  obtain uaa token for username password
~  uaasc  --uaa-service-client SERVICE [TENANT]                  obtain service token for generic client
~  uaasp  --uaa-service-passcode SERVICE PASSCODE [TENANT]       obtain service token for one-time passcode
~  uaasu  --uaa-service-user SERVICE USERNAME PASSWORD [TENANT]  obtain service token for username password
          ...    [TENANT]                                        obtain token for tenant, fallback to paas tenant
          ...    --decode                                        decode result token
          ...    --userinfo                                      add detailed user info for passcode or username

~  are read-only commands

Environment

It can be beneficial to pass credentials, especially long-term credentials like a password, along through environment variables instead of commandline arguments. This is, for example, the default approach in pipeline solutions like Jenkins and Github Actions.

Decoding JWTs

Without even setting up MTX Tool, you can always take any web token you have in your clipboard and run mtx uaad <jwt>.

Beyond this simple use case you might want to decode, for example, a user’s session JWT, in order to see which privileges that particular user has. In order to achieve this:

• Ask for the user’s subdomain. In our example it will be skyfin-company.
• Run mtx uaap 123 skyfin-company, i.e., use a made up passcode.
• MTX Tool will tell you the correct, landscape-dependent UAA url, which the user should use to get their one-time passcode. In our example it is https://skyfin-company.authentication.sap.hana.ondemand.com/passcode.
• Using the user’s one-time passcode run mtx uaap vjcOkwoVFL4ig17YIebYJYgKODSK6rsL skyfin-company --decode.

Accessing APIs as Technical User

If your server exposes an endpoint with JWT authentication, which is the default in CAP, then you can access these endpoint with a generic client JWT that mtx can get for you.

Set the Authorization header as Bearer <jwt> in HTTP requests for the endpoints to pass validation. We use curl for this, but any other HTTP client works as well.

Accessing APIs as User

Instead of acting as a generic client, you can access APIs as a regular user, provided the user in question gives you a one-time-passcode, that their tenant’s UAA published.

As an example, let’s say the user in question works for a tenant with subdomain microogle in the BTP region eu10, then they can obtain their passcode by logging in at https://microogle.authentication.eu10.hana.ondemand.com/passcode

Using this one-time passcode, you can either get a regular JWT for accesses as that user, or their extended user info:

Like before, if the command is run without the subdomain or tenant_id parameter, the tool will assume you mean the provider subaccount (paas).

Using this passcode, you can also obtain extended information about the user. However, the contents of this vary based on how the underlying identity provider and UAA are set up. In the identity provider, you can map assertion attributes into the SAML bearer assertion of each user, and in the UAA these will be propagated as user information under certain conditions.

For a list of possible attributes that SAP Identity Authentication Services (IAS) can map see Link. If these assertions match user_attributes that UAA expects, see Link, and the UAA’s configuration xs-security.json allows "foreign-scope-references": ["user_attributes"], then they will show up as extended user information.

Similarly to using a one-time passcode, you can access APIs as some user if you have both the username and password of that user.

Accessing Service APIs

You can access services in the same way that the server accesses them, usually for debugging purposes. You will need to know the label of the service and it needs to be bound to the app which is configured for user authentication.

For example destination is the label of the BTP destination service. You will also need to choose a trusted subdomain to use, for example skyfin-company.

If the subdomain belongs to the xsapp provider subaccount, then it will always be trusted. If the subdomain belongs to a different subaccount, it will only be trusted if that account has successfully subscribed to the xsapp.

So, mtx uaasc destination skyfin-company, will give you the corresponding JWT, which can then be decoded or used as Authorization header in an HTTP client.

Example for Saas Service

Here is an example of retrieving a JWT for the bound destination service: