167 lines
No EOL
8.8 KiB
XML
Executable file
167 lines
No EOL
8.8 KiB
XML
Executable file
<!--
|
|
~ 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> |