cumulocity

Cumulocity REST-API Passing TFA Header Token

I have a cumulocity tenant which requires two-factor authentication. I want to create a new microservice application in this tenant following this example, by calling the /applications endpoint with a POST request. This works already in a dummy tenant without MFA, however not on the tenant with MFA.

Even when I provide the TFAToken in the header as described here. I get a 401 Unauthorized Error

"message": "Invalid credentials! : TFA TOTP code required.",

Am I required to pass the TFA token from the authenticator in a special format - I have simply insertet the 6 digits without any spaces. Is there an encoding required?

Example Call

curl --location --request POST 'my_tenant/application/applications' \
--header 'TFAToken: 000000' \
** some other headers **
--data-raw '{
}'

Any help or pointers are much appreciated :)

Solution

  • You cannot use TOTP in combination with a basic auth request. The part of the documentation you referenced is only applicable if you use TFA via SMS. It seems the documentation is not fully clear about that but in the UI where you activate TOTP it says "TOTP requires OAuth Internal login mode."

    Therefore when using TOTP you have to follow the OAuth process for authentication:

    1. Request your JWT token

    This can be achieved via a form-urlencoded request against the oauth endpoint. https://cumulocity.com/guides/10.7.0-beta/reference/login/

    POST /tenant/oauth HTTP/1.1
Host: examples.cumulocity.com
Content-Type: application/x-www-form-urlencoded

grant_type=PASSWORD&username=<<myUser>>&password=<<myPassword>>&tfa_code=<<myTfaCode>>&tenant_id=<<myTenant>

    2. Use the JWT for following API calls

    In the response headers of the previous request you should see a Set-Cookie header. From this header you can grab the JWT. Note that the Set-Cookie header sets more than one cookie. You want to grab the authorization one (pretty long base64 string). You can then do your request with bearer token authentication:

    curl --location --request POST 'my_tenant/application/applications' \
--header 'Authorization: Bearer <<the copy+pasted base64 string from the Set-Cookie header>>' \
** some other headers **
--data-raw '{
}'