Keycloak - Update user's username

User in Keycloak has a username and email attribute. User's username (used for login) is different from user's email address. In lot of applications user's email address gets used as username. This brings up the usecase where user changes his/her email and the user's username in Keycloak must also be updated.

Keycloak by default doesn't allow admin to update user's username either via UI or API. To update username one need to first enable it at the realm level. Following are the steps:

1. Authenticate as admin

URL: POST https:///auth/realms//protocol/openid-connect/grants/access

2. Get realm

URL: GET https:///auth/admin/realms/

Response:
{
  "id": "bbb4b7eb-ea1e-4ca2-a925-896763cef01a",
  "realm": "",
  "notBefore": 0,
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000,
  "accessCodeLifespan": 60,
  "accessCodeLifespanUserAction": 300,
  "accessCodeLifespanLogin": 1800,
  "enabled": true,
  "sslRequired": "external",
  "registrationAllowed": false,
  "registrationEmailAsUsername": false,
  "rememberMe": false,
  "verifyEmail": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "userCacheEnabled": true,
  "realmCacheEnabled": true,
  "bruteForceProtected": false,
  "maxFailureWaitSeconds": 900,
  "minimumQuickLoginWaitSeconds": 60,
  "waitIncrementSeconds": 60,
  "quickLoginCheckMilliSeconds": 1000,
  "maxDeltaTimeSeconds": 43200,
  "failureFactor": 30,
  "publicKey": "",
  "certificate": "",
  "requiredCredentials": [
    "password"
  ],
  "otpPolicyType": "totp",
  "otpPolicyAlgorithm": "HmacSHA1",
  "otpPolicyInitialCounter": 0,
  "otpPolicyDigits": 6,
  "otpPolicyLookAheadWindow": 1,
  "otpPolicyPeriod": 30,
  "browserSecurityHeaders": {
    "contentSecurityPolicy": "frame-src 'self'",
    "xFrameOptions": "SAMEORIGIN"
  },
  "smtpServer": {},
  "eventsEnabled": false,
  "eventsListeners": [
    "jboss-logging"
  ],
  "enabledEventTypes": [],
  "adminEventsEnabled": false,
  "adminEventsDetailsEnabled": false,
  "identityFederationEnabled": false,
  "internationalizationEnabled": false,
  "supportedLocales": [],
  "browserFlow": "browser",
  "registrationFlow": "registration",
  "directGrantFlow": "direct grant",
  "resetCredentialsFlow": "reset credentials",
  "clientAuthenticationFlow": "clients"
}

3. Update realm to allow updating username

URL: PUT https:///auth/admin/realms/

Body:
{
 "editUsernameAllowed": true,
}

4. Get user

URL: GET https:///auth/admin/realms//users/a552d630-a696-43ea-9c56-9fe132e5a9a4

Response:
{
  "id": "a552d630-a696-43ea-9c56-9fe132e5a9a4",
  "createdTimestamp": 1483624857856,
  "username": "test",
  "enabled": true,
  "totp": false,
  "emailVerified": true,
  "requiredActions": []
}

5. Update user's username

URL: https:///auth/admin/realms//users/a552d630-a696-43ea-9c56-9fe132e5a9a4

Body:
{
"username": "test1",
"enabled": true,
"emailVerified": true
}

note: Keycloak 1.5.0 updates the enabled and emailVerified attributes to false upon update when not explicitly passed. I haven't checked if there are other such attributes.

6. Get user

URL: GET https:///auth/admin/realms//users/a552d630-a696-43ea-9c56-9fe132e5a9a4

Response:
{
  "id": "a552d630-a696-43ea-9c56-9fe132e5a9a4",
  "createdTimestamp": 1483624857856,
  "username": "test1",
  "enabled": true,
  "totp": false,
  "emailVerified": true,
  "requiredActions": []
}

7. Validate by performing login with username test1 and password.

Feel free to leave comment.