[BUG] API token encoding

Ignition
1

Hello!
I know this is not a place for bug reports (I have already sent a ticket to support), but since it was a real headscratcher for me I wanted to share here what I found, maybe it helps someone else.

1. The behavior you unexpectedly encountered
When the name of an API token contains an umlaut like ü, requests with a JSON body return "401 Unauthorized", while API tokens without umlaut work fine.

2. The behavior you were expecting to see
All endpoints should behave the same no matter if the token name includes an umlaut or not (as long as they require the same permissions and the tokens have the same security levels of course).

3. A list of the steps you took that exposed the issue

  • Log in to the Gateway

  • Create one API key where the name contains an umlaut like ü, and another one without any umlaut

  • If not present, create a security level for the API tokens, e.g. Authorized -> APIToken -> Write

  • Assign this security level to the tokens

  • In the Gateway -> Platform -> Security -> General settings -> Roles & Permissions, select the same level for Gateway Write Permissions and select "User must belong to at least one of these security levels"

  • Select two API endpoints, where one has a JSON request body and the other one does not. For example, Get General Alarm Settings config (GET /data/api/v1/resources/singleton/ignition/general-alarm-settings) and Create General Alarm Settings (POST /data/api/v1/resources/ignition/general-alarm-settings)

  • Send a request without JSON body, this should work fine for both tokens

  • Send a request with JSON body and get the response "401 Unauthorized" for the token with umlaut, while the token without umlaut works

  • Unfortunately I found no option to easily debug what was happening, so I did some digging and added some logging, then saw that for those endpoints that failed, when logging the token's security levels, it did not find any, presumably because the token had a wrong encoding, ü instead of ü, so it could not be found when checking its security levels.

4. A list of helpful information about the situation you were in

5. Solution

  • It is relatively easy to get around, just don’t use any umlauts in API token names, but if you did and are wondering why some requests are returning 401, then this might be the reason
2

This is not too surprising, use of unicode characters is generally discouraged in HTTP headers.

When you do use it, the value should be encoded (URL encoding, b64, etc...) in a way that both sides have agreed on.

2 Likes
3

Hi!

Thanks for the quick reply. Good point, it does make sense not to use unicode characters in HTTP headers. What, at least to me, does not make sense though, is that the name I give to the token in the gateway becomes part of that same token. Unless you specifically inspect the token, you might miss that. I agree that this is not a bug then, but I still think it could be improved to avoid this trouble for others in the future. Some ideas:

  • clarify in the documentation that the name becomes part of the token and should therefore not include any unicode characters
  • either add something like a warning/tooltip or description to the name field when adding a new API key, hinting that unicode characters should not be part of the name
  • add some parsing/formatting to the token creation to replace unicode characters for the token itself

Thanks again and have a great day!