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.