[keycloak-dev] Proposal: REST Endpoint for creating TOTP

[Roland Werner]

Hi,

I noticed that the REST API (
https://www.keycloak.org/docs-api/6.0/rest-api/index.html) does contain an
endpoint "Remove TOTP from the user", but none that allows to create a TOTP
for a user in the first place.

I'm proposing to add this "create-totp" endpoint and would also contribute
it. The call would look like this:

curl -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer
<token>' -i http://
<keycloak-url>:<port>/auth/admin/realms/myrealm/users/<user-id>/create-totp

and the reply as follow:
{
  "totpSecret": "aA3mIuIzvxTmC5gqUqpl",
  "qrCode": "iVBORw0KGgoAAA...AAABJRU5ErkJggg=="
}

I would check the existence of TOTP on the requested user and would reply
with 400-Bad-Request and the message
{
  "errorMessage": "User already has totp. Remove first."
}
in that case (just to make sure that this doesn't happen on accident).
One question in that respect: The JavaDocs of
org.keycloak.representations.idm.UserRepresentation says that isTotp is
deprecated, but doesn't say what to use instead. Can someone point me to
the right direction here?

I am aware that the current practice in Keycloak when adding a TOTP to a
user is to instantly request a generated OTP and only if that is correct
add the credential-type to the user. Obviously this would not apply for the
REST endpoint. However, as the endpoint is only reachable for an admin I
don't think this would result in a significant security loss, especially as
the "remove-totp" endpoint can also be used without the need to enter an
OTP.

I suggest to align the code with the behavior of the remove-totp endpoint,
such that
- it uses PUT
- it is called on given user
- it requires the same admin rights

This reason for my approach is that we want to introduce a process in our
organisation where every user in the given realm is forced to use an OTP to
login and there is no self-registration but instead the users are handed
over the QR-Code outside of Keycloak (on paper or digitally). In the
meantime we use a custom plugin, but I would love to see this also make its
way into the standard Keycloak.

What do you think?

Thanks and Regards,
Roland