JBoss.orgCommunity Documentation

Chapter 28. Custom User Attributes

28.1. In admin console
28.2. In registration page
28.3. In user account profile page

If you have custom user data you want to store and manage in the admin console, registration page, and user account service, you can easily add support for it by extending and modifying various Keycloak themes.

To be able to enter custom attributes in the admin console, take the following steps

  1. Create a new theme within the themes/admin/mytheme directory in your distribution. Where mytheme is whatever you want to name your theme.
  2. Create a theme.properties file in this directory that extends the main admin console theme.
    parent=keycloak
    import=common/keycloak
    
  3. Copy the file themes/admin/base/resources/partials/user-attribute-entry.html into the a mirror directory in your theme: themes/admin/mytheme/resources/partials/user-attribute-entry.html. What you are doing here is overriding the user attribute entry page in the admin console and putting in what attributes you want. This file already contains an example of entering address data. You can remove this if you want and replace it with something else. Also, if you want to edit this file directly instead of creating a new theme, you can.
  4. In the user-attribute-entry.html file add your custom user attribute entry form item. For example
        <div class="form-group clearfix block">
            <label class="col-sm-2 control-label" for="mobile">Mobile</label>
            <div class="col-sm-6">
                <input ng-model="user.attributes.mobile" class="form-control" type="text" name="mobile" id="mobile" />
            </div>
            <span tooltip-placement="right" tooltip="Mobile number." class="fa fa-info-circle"></span>
        </div>
    
    The ng-model names the user attribute you will store in the database and must have the form of user.attributes.ATTR_NAME.
  5. Change the theme for the admin console. Save it, then refresh your browser, and you should now see these fields in the User detail page for any user.

To be able to enter custom attributes in the registration page, take the following steps

  1. Create a new theme within the themes/login/mytheme directory in your distribution. Where mytheme is whatever you want to name your theme.
  2. Create a theme.properties file in this directory that extends the main admin console theme.
    parent=keycloak
    import=common/keycloak
    styles= ../patternfly/lib/patternfly/css/patternfly.css ../patternfly/css/login.css ../patternfly/lib/zocial/zocial.css css/login.css
  3. Copy the file themes/login/base/register.ftl into the a mirror directory in your theme: themes/login/mytheme/register.ftl. What you are doing here is overriding the registration page and adding what attributes you want. This file already contains an example of entering address data. You can remove this if you want and replace it with something else. Also, if you want to edit this file directly instead of creating a new theme, you can.
  4. In the register.ftl file add your custom user attribute entry form item. For example
    <div class="form-group">
       <div class="${properties.kcLabelWrapperClass!}">
           <label for="user.attributes.mobile" class="${properties.kcLabelClass!}">Mobile number</label>
       </div>
    
       <div class="col-sm-10 col-md-10">
           <input type="text" class="${properties.kcInputClass!}"  id="user.attributes.mobile" name="user.attributes.mobile"/>
       </div>
    </div>
    
    Make sure the input field id ane name match the user attribute you want to store in the database. This must have the form of user.attributes.ATTR_NAME. You might also want to replace the label text with a message property. This will help later if you want to internationalize your pages.
  5. Change the theme for the login to your new theme. Save it, then refresh your browser, and you should now see these fields in the registration.

To be able to manage custom attributes in the user account profile page, take the following steps

  1. Create a new theme within the themes/account/mytheme directory in your distribution. Where mytheme is whatever you want to name your theme.
  2. Create a theme.properties file in this directory that extends the main admin console theme.
    parent=patternfly
    import=common/keycloak
    
    styles= ../patternfly/lib/patternfly/css/patternfly.css ../patternfly/css/account.css css/account.css
  3. Copy the file themes/account/base/account.ftl into the a mirror directory in your theme: themes/account/mytheme/account.ftl. What you are doing here is overriding the profile page and adding what attributes you want to manage. This file already contains an example of entering address data. You can remove this if you want and replace it with something else. Also, if you want to edit this file directly instead of creating a new theme, you can.
  4. In the account.ftl file add your custom user attribute entry form item. For example
    <div class="form-group">
       <div class="col-sm-2 col-md-2">
           <label for="user.attributes.mobile" class="control-label">Mobile number</label>
       </div>
    
       <div class="col-sm-10 col-md-10">
           <input type="text" class="form-control" id="user.attributes.mobile" name="user.attributes.mobile" value="${(account.attributes.mobile!'')?html}"/>
       </div>
    </div>
    Make sure the input field id ane name match the user attribute you want to store in the database. This must have the form of user.attributes.ATTR_NAME. You might also want to replace the label text with a message property. This will help later if you want to internationalize your pages.
  5. Change the theme for the account to your new theme. Save it, then refresh your browser, and you should now see these fields in the account profile page.