Chapter 17. JBoss Portal Identity Portlets
Prev |  | Next

## Chapter 17. JBoss Portal Identity Portlets

### Emanuel Muckenhuber

`<emuckenh@redhat.com>`

## 17.1. Introduction

Since JBoss Portal 2.6.2 two new Identity Portlets are shipped by default:

- The User Portlet

- The Identity Management Portlet

As the names indicate - the User Portlet is responsible for actions related to the end user. Whereas the Identity Management Portlet contains all the functionality for managing users and roles.

### Warning

The Identity portlets will evolve over time, therefore usage and configuration might change.

### 17.1.1. Features

The identity portlets provide the following features:

- Email verification: The users can receive an email with a link on which they must click to confirm the creation of the new account. (Disabled by default,see Section 17.2.4, “jBPM based user registration”)

- Captcha support: The users are prompted to copy letters from a deformed image. (Disabled by default, see Section 17.2.1, “Captcha support”)

- Lost password: The users can receive a new password by email, any user with access to the admin portlet can also reset another user's password and send the new one by email in one click. (Disabled by default, see Section 17.2.2, “Lost password”)

- jBPM based user registration: Several business processes are available out of the box (this includes administration approval), this can be extended to custom ones. See Section 17.2.4, “jBPM based user registration”.

- User and role management: Ability for the administrator to add and edit users as well as adding,

## 17.2. Configuration

This section covers the configuration of the Identity Portlets.

### 17.2.1. Captcha support

CAPTCHA is an acronym for `Completely Automated Public Turing test to tell Computers and Humans Apart`. This is providing a mechanism to prevent automated programs from using different services. The User Portlet uses JCaptcha to provide a challenge-response.

### Note

By default the captcha service needs a XServer to generate the images. For using the captcha service without a XServer make sure you run the jvm with the following option:

    -Djava.awt.headless=true

The registration page with captcha.

The captcha support can be enabled by changing the portlet preference 'captcha' to 'true'. If enabled, captcha will be used for the registration and lost password action.

    ...
    <portlet>
    ...
    	<display-name>User portlet</display-name>
    ...
    	<portlet-preferences>
    		<preference>
    			<name>captcha</name>
    			<value>true</value>
          	</preference>
    	</portlet-preferences>
    </portlet>
    ...

### 17.2.2. Lost password

The lost password feature enables the end user to reset his password by entering his username.

### Note

This feature requires a properly configured MailModule. See Section 3.4, “Setting up the email service”.

The lost password page with captcha enabled.

The lost password feature can be enabled by changing the portlet preference 'lostPassword' to 'true'. If captcha is enabled it will be also used for verifying the lost password action.

    ...
    <portlet>
    ...
    	<display-name>User portlet</display-name>
    ...
    	<portlet-preferences>
    		<preference>
    			<name>lostPassword</name>
    			<value>true</value>
    		</preference>
    	</portlet-preferences>
    </portlet>
    ...

### 17.2.3. Reset password

The reset password feature is similar to the lost password feature, but it is used in the User Management Portlet to reset the password of a user. That means changing the password of a user is slightly simplified, because a random password will be generated and sent to the users e-mail address.

    ...
    <portlet>
    ...
    	<display-name>User management portlet</display-name>
    ...
    	<portlet-preferences>
    		<preference>
          		<name>resetPassword</name>
          		<value>true</value>
    		</preference>
    	</portlet-preferences>
    </portlet>
    ...

### 17.2.4. jBPM based user registration

JBoss Portal supports three different subscription modes by default:

- Automatic subscription (no jBPM required), the users can register and directly login.

- E-Mail validation, the users need to click on a link sent by email before being able to login.

- E-Mail validation and admin approval, the users need to validate their email, then an admin needs to approve the newly created account.

### Note

The subscription mode has to be defined in the configuration file as explained here: Section 17.2.5, “The configuration file”.

### Warning

Make sure that the application server is restarted after re-deploying the Identity Portlets. This is required to make sure that the registration and approval process works properly!

Approve or reject pending registrations (jbp_identity_validation_approval_workflow).

### 17.2.5. The configuration file

The Identity Portlets use some metadata which can be easily changed in the main configuration file, which is located at `jboss-portal.sar/portal-identity.sar/conf/identity-ui-configuration.xml` as shown here:

    <identity-ui-configuration>

    	<subscription-mode>automatic</subscription-mode>
    	<admin-subscription-mode>automatic</admin-subscription-mode>
    	<overwrite-workflow>false</overwrite-workflow>
    	<email-domain>jboss.org</email-domain>
    	<email-from>no-reply@jboss.com</email-from>
    	<password-generation-characters>a...Z</password-generation-characters>
    	<default-roles>
    		<role>User</role>
    	</default-roles>

    	<!-- user interface components -->
    	<ui-components>
    		<ui-component name="givenname">
    			<property-ref>user.name.given</property-ref>
    		</ui-component>
    		<ui-component name="familyname">
    			<property-ref>user.name.family</property-ref>
    		</ui-component>
    		...
    </identity-ui-configuration>

- subscription-mode: defines the User Portlet registration process

  - automatic: no validation nor approval (default)
  - jbp_identity_validation_workflow: e-mail validation, no approval
  - jbp_identity_validation_approval_workflow: e-mail validation and approval
  - custom: Take a look at Customizing the workflow

- admin-subscription-mode: jBPM process used in the User Management Portlet for creating users

  - automatic: no validation nor approval (default)
  - jbp_identity_validation_workflow: e-mail validation, no approval
  - jbp_identity_validation_approval_workflow: e-mail validation and approval
  - custom: Take a look at Customizing the workflow

- overwrite-workflow: if set to 'true' the workflow will be overwritten during the next startup (default: false)

- email-domain: e-mail domain used in the validation e-mail by the template (can be anything)

- email-from: e-mail fro field used by the validation e-mail

- password-generation-characters: characters to use to generate a random password

- default-roles: one or more default roles

  - available element: role

- ui-components: Defines the available user interface components. Take a look at the next section for further details.

Due to the differentiation between subscription-mode and admin-subscription-mode it is possible to require e-mail validation and approval for new registrations and e-mail validation only when a user is created in the user management portlet.

### 17.2.6. Customize e-mail templates

The email templates can be found in the folder: portal-identity.sar/conf/templates/
New languages can be added by creating a new file like: emailTemplate_fr.tpl

## 17.3. User interface customization

The following three examples describe common use cases for customizing the User Portlet.

- Example 1: Describes how to tag a input field as required and add it to the registration page.

- Example 2: Shows how to create a simple dropdown menu.

- Example 3: Describes how to add new properties.

### Note

This is not a JavaServer Faces tutorial. Basic knowledge of this technology is a precondition for customizing the User Portlet Interface.

### 17.3.1. Example 1: required fields

This example explains how to change optional properties to required properties, of course once this is done, we will also need to add the corresponding fields in the registration page.
Here are the modifications in portal-identity.sar/conf/identity-ui-configuration.xml, we simply changed the required element to true on our two fields corresponding to the given and family names.

    <identity-ui-configuration>
    ...
    	<!-- user interface components -->
    		...
    		<ui-component name="givenname">
    			<property-ref>user.name.given</property-ref>
    			<required>true</required>
    		</ui-component>
    		<ui-component name="familyname">
    			<property-ref>user.name.family</property-ref>
    			<required>true</required>
    		</ui-component>
    		...
    </identity-ui-configuration>

Now that we changed those values to "required" we need to give a chance to the user to enter those values, here are the changes done in portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/register.xhtml

    ...
    	<h:outputText value="#{bundle.IDENTITY_GIVENNAME}"/>
      	<h:inputText id="givenname" value="#{manager.uiUser.attribute.givenname}"
      			required="#{metadataservice.givenname.required}"/>
      	<h:panelGroup />
      	<h:message for="givenname" />

      	<h:outputText value="#{bundle.IDENTITY_FAMILYNAME}"/>
      	<h:inputText id="lastname"  value="#{manager.uiUser.attribute.familyname}"
      			required="#{metadataservice.familyname.required}"/>
      	<h:panelGroup />
      	<h:message for="lastname"/>
    ...

That's it - from now on the given name and family name will be required on registration. We dynamically obtain the values from the descriptor. Now if i just wanted to make them back to optional, i would change the values only in the descriptor, letting the user enter or not those values.

### 17.3.2. Example 2: dynamic values (dropdown menu with predefined values)

If the data to enter is a choice instead of a free-text value, you can also define those in the descriptor like shown here:

    <identity-ui-configuration>
    ...
    	<!-- user interface components -->
    		...
    		<ui-component name="interests">
    			<property-ref>portal.user.interests</property-ref>
    			<values>
    				<value key="board">snowboarding</value>
    				<value key="ski">skiing</value>
    				<value key="sledge">sledging</value>
    			</values>
    		</ui-component>
    		...
    </identity-ui-configuration>

In portal-identity.sar/portal-identity.war/WEB-INF/jsf/common/profile.xhtml - change inputText to a selectOneMenu:

    	...
    	<h:outputText value="#{bundle.IDENTITY_INTERESTS}"/>
    	<h:selectOneMenu id="interests" value="#{manager.uiUser.attribute.interests}"
    		required="#{metadataservice.interests.required}">
    	<f:selectItems value="#{metadataservice.interests.values}" />
    	</h.selectOneMenu>
      	<h:panelGroup />
    	<h:message for="interests"/>
    ...

For localizing dynamic values it is also possible to use the resource bundle. This can be done by adding the key with a prefix (to i.e. Identity.properties) like in the following listing. The key will be stored in the users property and is used to identify the element. The value of the configuration file will only be used if no localization information is found.

    ...
    IDENTITY_DYNAMIC_VALUE_BOARD=localized snowboarding
    IDENTITY_DYNAMIC_VALUE_SKI=localized skiing
    IDENTITY_DYNAMIC_VALUE_SLEDGE=localized sledging
    ...

### Note

If the value is not required a blank element will be added at the top.

### 17.3.3. Example 3: adding new properties

### Note

Please make sure you read at least the section about user profile configuration: Section 16.3, “User profile configuration”, to add a new value on the interface it also has to be defined in your model, as shown on Step 1.

step 1: add a new property to profile-config.xml e.g. a dynamic property called gender:

    ...
       <property>
          <name>user.gender</name>
          <type>java.lang.String</type>
          <access-mode>read-write</access-mode>
          <usage>optional</usage>
          <display-name xml:lang="en">Gender</display-name>
          <description xml:lang="en">The gender</description>
          <mapping>
             <database>
                <type>dynamic</type>
                <value>user.gender</value>
             </database>
          </mapping>
       </property>
    ...

### Note

It is recommended to use the 'User Information Attribute Names' from the Portlet Specification for defining properties.

step 2: add the property to the identity-ui-configuration: (portal-identity.sar/conf/identity-ui-configuration.xml)

    ...
    	<ui-component name="gender">
    		<property-ref>user.gender</property-ref>
    		<required>true</required>
    		<values>
    			<value key="male">Male</value>
    			<value key="female">Female</value>
    		</values>
    	</ui-component>
    ...

### Note

The property-ref must match a property from the profile-config.xml.

step 3: add your custom ui-component to the profile page: (portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile.xhtml)

    ...
    	<h:outputText value="#{bundle.IDENTITY_GENDER}"/>
    	<h:selectOneMenu id="gender" value="#{manager.uiUser.attribute.gender}"
    			required="#{metadataservice.gender.required}">
    		<f:selectItems value="#{metadataservice.gender.values}" />
    	</h.selectOneMenu>
      	<h:panelGroup />
    	<h:message for="gender"/>
    ...

### Note

Don't forget to add the localization elements.

### 17.3.4. Illustration

Illustration of the relationship between the configuration files.

The JSF-View in more detail:

- manager.uiUser.attribute: manages and stores the dynamic properties

  - examples: manager.uiUser.attribute.gender, manager.uiUser.attribute.interests

        <h:inputText id="gender" value="#{manager.uiUser.attribute.gender}" />

- metadataservice

  - required - references the required attribute from the ui-component
    example: metadataservice.gender.required

        <h:inputText id="gender" value="#{manager.uiUser.attribute.gender}" required="#{metadataservice.gender.required}"/>

  - values - references the values list from the ui-component
    example: metadataservice.gender.values

        <h:selectOneMenu id="interests" value="#{manager.uiUser.attribute.interests}">
        	<f:selectItems value="#{metadataservice.interests.values}" />
        </h:selectOneMenu>

  - validator - references the name of a registered JSF validator
    example:metadataservice.gender.validator - the first validator of the validator list
    example: metadataservice.gender.validators[0] - the validator list with an index

        <f:validator validatorId="#{metadataservice.gender.validator}"/>

  - converter - references the name of a registered JSF converter
    example: metadataservice.gender.converter

        <f:converter converterId="#{metadataservice.gender.converter}"/>

  - readOnly - references the access-mode of profile-config.xml
    possible usage i.e. in /WEB-INF/jsf/common/profile.xhtml

        <h:inputText value="#{manager.uiUser.attribute.nickname}" disabled="#{metadataservice.nickname.readOnly}" />

### Warning

The values of the profile-config.xml have a higher priority than the values in the user portlet configuration. That means if the 'usage' is 'mandatory' in profile-config.xml and 'required' is 'false' it will be overwritten by the value from the profile config!

### 17.3.5. Customizing the View Profile page

By default not all values of the user profile will be displayed on the View profile page. For customization it is possible to add further properties to the page by editing the file: portal-identity.sar/portal-identity.war/WEB-INF/jsf/profile/viewProfile.xhtml

## 17.4. Customizing the workflow

### Note

For more details about jBPM please read the jBPM documentation

The process definitions are located in: portal-identity.sar/conf/processes. To create a custom workflow, you can extend the existing process description file: custom.xml.

Available variables in the business process:

- name: portalURL
  type: java.lang.String
  description: represents the full url of the portal e.g. http://localhost:8080/portal

- name: locale
  type: java.util.Locale
  description: the requested locale at registration

- name: email
  type: java.lang.String
  description: the e-mail address of the user in case of registration.
  In case of changing the e-mail the new e-mail address.

- name: user
  type: org.jboss.portal.core.identity.services.workflow.UserContainer
  description: Seralizable Object containing user information through the jBPM process

- name: validationHash
  type: java.lang.String
  description: hash used for the validation part. Only available after executing SendValidationEmailAction

### Note

Make sure that the filename and the process name match! e.g. conf/processes/custom.xml and process-definition name="custom".

When using a custom workflow it is possible to customize the status message after registering in the locale bundle: ( e.g. portal-identity.sar/conf/bundles/Identity.properties)

    ...
    IDENTITY_VERIFICATION_STATUS_REGISTER_CUSTOM=Customized message here
    ...

### 17.4.1. Duration of process validity

By default requests (e.g. e-mail validation and registrations) expire after some time in the validation state. Therefore it is not required to add additional maintenance mechanism to invalidate a request. The default expiration time is 2 days, but is quite easy to change the timing by editing the duedate attribute in the process definition. changes in: portal-identity.sar/conf/processes/*.xml

    <process-definition>
    ...
      <state name="validate_email">
      	  <timer name="time_to_expire" duedate="2 days" transition="timedOut" />
      </state>
    ...
    </process-definition>

For further information take a look at the jBPM documentation on Duration.

## 17.5. Disabling the Identity Portlets

Due to the fact that the former user portlets are still included in JBoss Portal 2.6.2 it is possible to activate it in the Portal Admin interface, by using the PortletInstances:

- UserPortletInstance: The former user portlet
- RolePortletInstance: The former role managment portlet

### 17.5.1. Enabling the Identity Portlets

When migrating from former versions of JBoss Portal the Identity User Portlets won't be displayed by default, but Windows can be created on basis of the existing Portlet Instances which are deployed by default. (The instances names being `IdentityUserPortletInstance` and `IdentityAdminPortletInstance`.)

Prev | Up | Next
Chapter 16. JBoss Portal Identity Management | Home | Chapter 18. Authentication and Authorization