keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/custom-attributes.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<chapter id="custom-user-attributes">
    <title>Custom User Attributes</title>
    <para>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 <link linkend="themes">themes</link>.</para>
    <section>
        <title>In admin console</title>
    <para>To be able to enter custom attributes in the admin console, take the following steps</para>
    <para>
        <orderedlist>
            <listitem>
                Create a new theme within the <literal>themes/mytheme/admin</literal> directory in your distribution.
                Where <literal>mytheme</literal> is whatever you want to name your theme.
            </listitem>
            <listitem>
                Create a <literal>theme.properties</literal> file in this directory that extends the main admin console
                theme.
                <programlisting><![CDATA[parent=keycloak
import=common/keycloak
]]></programlisting>
            </listitem>
            <listitem>
                Copy the file <literal>themes/base/admin/resources/partials/user-attributes.html</literal> into the
                a mirror directory in your theme: <literal>themes/mytheme/admin/resources/partials/user-attributes.html</literal>.
                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.
            </listitem>
            <listitem>
                In the <literal>user-attributes.html</literal> file add your custom user attribute entry form item.  For example
<programlisting><![CDATA[    <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>
]]></programlisting>
                The <literal>ng-model</literal> names the user attribute you will store in the database and must have the
                form of <literal>user.attributes.ATTR_NAME</literal>.
            </listitem>
            <listitem>
                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.
            </listitem>
        </orderedlist>
    </para>
    </section>
    <section>
        <title>In registration page</title>
    <para>To be able to enter custom attributes in the registration page, take the following steps</para>
    <para>
        <orderedlist>
            <listitem>
                Create a new theme within the <literal>themes/mytheme/login</literal> directory in your distribution.
                Where <literal>mytheme</literal> is whatever you want to name your theme.
            </listitem>
            <listitem>
                Create a <literal>theme.properties</literal> file in this directory that extends the main admin console
                theme.
                <programlisting><![CDATA[parent=keycloak
import=common/keycloak
styles= ../patternfly/lib/patternfly/css/patternfly.css ../patternfly/css/login.css ../patternfly/lib/zocial/zocial.css css/login.css]]></programlisting>
            </listitem>
            <listitem>
                Copy the file <literal>themes/base/login/register.ftl</literal> into the
                a mirror directory in your theme: <literal>themes/mytheme/login/register.ftl</literal>.
                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.
            </listitem>
            <listitem>
                In the <literal>register.ftl</literal> file add your custom user attribute entry form item.  For example
<programlisting><![CDATA[
<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>
]]></programlisting>
                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 <literal>user.attributes.ATTR_NAME</literal>.  You might also want to replace the label text
                with a message property.  This will help later if you want to internationalize your pages.
            </listitem>
            <listitem>
                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.
            </listitem>
        </orderedlist>
    </para>
    </section>
    <section>
        <title>In user account profile page</title>
    <para>To be able to manage custom attributes in the user account profile page, take the following steps</para>
    <para>
        <orderedlist>
            <listitem>
                Create a new theme within the <literal>themes/mytheme/account</literal> directory in your distribution.
                Where <literal>mytheme</literal> is whatever you want to name your theme.
            </listitem>
            <listitem>
                Create a <literal>theme.properties</literal> file in this directory that extends the main admin console
                theme.
                <programlisting><![CDATA[parent=patternfly
import=common/keycloak

styles= ../patternfly/lib/patternfly/css/patternfly.css ../patternfly/css/account.css css/account.css]]></programlisting>
            </listitem>
            <listitem>
                Copy the file <literal>themes/base/account/account.ftl</literal> into the
                a mirror directory in your theme: <literal>themes/mytheme/account/account.ftl</literal>.
                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.
            </listitem>
            <listitem>
                In the <literal>account.ftl</literal> file add your custom user attribute entry form item.  For example
<programlisting><![CDATA[
<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>]]></programlisting>
                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 <literal>user.attributes.ATTR_NAME</literal>.  You might also want to replace the label text
                with a message property.  This will help later if you want to internationalize your pages.
            </listitem>
            <listitem>
                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.
            </listitem>
        </orderedlist>
    </para>
    </section>



</chapter>