Jazz Authorization Server is based on the IBM WebSphere Liberty server. Because Jazz Authorization Server authenticates users, it must be configured with a user registry. WebSphere Liberty server has capabilities similar to the full WebSphere Application Server; it can be configured to use a Lightweight Directory Access Protocol (LDAP) registry, or users can be defined in local files.
This article will focus on steps to help configure JAS with a File based User Registry and LDAP User registry.
Installation
CLM
- To deploy JAS to an existing environment and migrate to JAS, visit this Section on our Infocenter
- For a new deployment of CLM, Install the applications via IBM Installation Manager and Select the option "Enable Jazz Security Architecture SSO" during the installation
JAS
- Download Jazz Authorization Server install bit from jazz.net, under All Downloads Section for the specific version
- Install Jazz Authorization Server application via Installation Manager, instructions available on our Infocenter
Setup and Configure JAS with a User Registry
Configuration files
- Copy the files from
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults
folder one level up to JazzAuthServer_install_dir/wlp/usr/servers/jazzop/
- Files we would modify are
server.xml
, appConfig.xml
, ldapUserRegistry.xml
and localUserRegistry.xml
-
appConfig.xml
- Contains Jazz Group/Role mappings and UserRegistry file information
-
ldapUserRegistry.xml
- Configuring Liberty with an LDAP user registry
-
localUserRegistry.xml
- Configuring Liberty file based registry
Configure JAS with Liberty file based registry
- By default the bundled Liberty profile is configure with File based user registry.
- Open the file
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/localUserRegistry.xml
- Add new Users or Groups and save the file
<server>
<!-- Sample basic user registry definition
The passwords for the "ADMIN" and "clmadmin" users are the same as the user names.
If those users are to be retained, the wlp/bin/securityUtility script should be used
to encode new passwords. Otherwise, new users should defined with encoded passwords.
-->
<basicRegistry>
<user name="ADMIN" password="{xor}HhsSFhE="/>
<user name="clmadmin" password="{xor}PDMyPjsyNjE="/>
<user name="clmuser" password="plaintext_password"/>
<group id="JazzAdmins" name="JazzAdmins">
<member name="ADMIN"/>
<member name="clmadmin"/>
</group>
<group id="JazzUsers" name="JazzUsers">
<member name="clmuser"/>
</group>
<group id="JazzGuests" name="JazzGuests">
</group>
<group id="JazzProjectAdmins" name="JazzProjectAdmins">
</group>
</basicRegistry>
<administrator-role>
<user>clmadmin</user>
</administrator-role>
</server>
- You can either enter Plain Text Passwords or encrypt the passwords using the securityUtility
Configure JAS with LDAP registry
- By default the bundled Liberty profile is configured with file based user registry
- To change the configuration to LDAP registry, edit
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults/appConfig.xml
file
- Towards the end of the file change from
-
<include location="localUserRegistry.xml" optional="true"/>
<!--include location="ldapUserRegistry.xml" optional="true"/-->
TO
-
<!--include location="localUserRegistry.xml" optional="true"/-->
<include location="ldapUserRegistry.xml" optional="true"/>
- To Configure the LDAP User Registry, guidance from LDAP administrators / Network admins may be necessary to complete the configuration Typical information needed from your LDAP Admin
- LDAP Server Name and Port (LDAP Server hostname and Port)
- The Base DN (LDAP Root Tree where Users/Groups can be queried from_)
- bindDN and bindPassword (User ID and password for the user who can query the LDAP directory)
- Group and User filter (inetOrgPerson, groupOfNames etc)
- User ID and Group ID mappings (sAMAccountName, cn etc)
- Example configuration for different LDAPs information is available in our Infocenter
- We have included a few examples from different LDAP environments (MS Active Directory, Tivoli and ApacheDS) to help guide the configuration.
- Edit
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults/ldapUserRegistry.xml
and modify the ldapRegistry configuration for your LDAP registry
Microsoft Active Directory
-
<server>
<ldapRegistry ldapType="Microsoft Active Directory" baseDN="CN=Users,DC=test,DC=com"
bindDN="CN=CLM Admin,CN=Users,DC=test,DC=com" bindPassword="********"
host="ldapserver" id="ldapserver:389" ignoreCase="true" port="389" realm="ldapserver:389"
recursiveSearch="true" referal="follow" sslEnabled="false">
<activedFilters
userFilter="(&(sAMAccountName=%v)(objectcategory=user))"
groupFilter="(&(cn=%v)(objectcategory=group))"
userIdMap="user:sAMAccountName"
groupIdMap="*:cn"
groupMemberIdMap="memberOf:member" >
</activedFilters>
</ldapRegistry>
</server>
IBM Tivoli Directory Server
-
<server>
<ldapRegistry ldapType="IBM Tivoli Directory Server" baseDN="o=test.com"
bindDN="uid=clmadmin,c=in,ou=Users,o=test.com" bindPassword="********"
host="ldapserver" id="ldapserver:389" ignoreCase="true" port="389"
realm="ldapserver:389" recursiveSearch="true" sslEnabled="false">
<idsFilters
groupFilter="(&(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
groupIdMap="*:cn"
groupMemberIdMap="groupOfUniqueNames:uniquemember"
userFilter="(&(uid=%v)(objectclass=person))"
userIdMap="*:uid">
</idsFilters>
</ldapRegistry>
</server>
Apache DS
-
<server>
<ldapRegistry ldapType="Custom" baseDN="dc=example,dc=com" host="localhost"
id="localhostexample:10389" ignoreCase="true" port="10389" referal="follow"
realm="localhostexample:10389" recursiveSearch="true" sslEnabled="false">
<customFilters
groupFilter="(&(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
groupIdMap="*:cn"
groupMemberIdMap="groupOfUniqueNames:uniquemember"
userFilter="(&(uid=%v)(objectclass=inetOrgPerson))"
userIdMap="*:uid" >
</customFilters>
</ldapRegistry>
</server>
Encrypt Passwords
Group to Role Mappings
- Groups to Jazz Roles mappings are picked from JTS configuration when JAS is configured with LDAP. When running JTS/Setup select the User registry type as LDAP and configure to the same LDAP registry that is configured with JAS and enter the group mappings under the property Jazz to LDAP Group Mapping (The steps are included later in this article)
Configure Database for JAS
When you first install JAS, it comes configured to use a local Derby database for storing information. It is not recommended to use Derby database for a production environment and note that Derby database won't work in a clustered JAS environment, since that information won't be available to all the instances.
The basic steps to configure the database are:
- Create database tables on a database server which all JAS instances can access
- Update the JAS configuration file (appConfig.xml) to use the database server
The following links provide information for both Oracle and DB2, and sample SQL scripts are available that can create the necessary tables. But note that you will need to customize these scripts for your own environment.
The JAS database is used to store client registration information (i.e. all the applications that are configured to use the JAS for authentication) and information about authentication tokens that have been issued to clients. The client registration information is small and static, so it takes very little space in the database, but the token information is dynamic, and the space that it uses is proportional to the number of times a client will authenticate with a CLM application. Also, tokens have expiration periods; token information is retained until it expires. Therefore, an environment in which there are many authentications taking place and in which token expiration times are fairly long will require more storage space in the database.
Also, the JAS will load all unexpired tokens for a particular user into memory. If there are many tokens outstanding for a single user, more Java heap memory may be required than in the default configuration. In particular, since RTC build engines are usually configured to authenticate as a single designated "build" user, lots of build activity may result in the need to increase the Java heap size for the JAS.
Database storage size can be reduced by shortening the token expiration periods. There are two of them, one for access tokens and one for refresh tokens. The default access token expiration time is 6 hours, so it generally won't cause a problem. But the default refresh token time is 7 days, which can cause them to accumulate quite a bit. To reduce that expiration time, adjust the value for the "authorizationGrantLifetime" attribute of the <oauthProvider> element in the
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/appConfig.xml
file. The default configuration is
<oauthProvider id="JazzOP"
httpsRequired="true"
autoAuthorize="true"
customLoginURL="/jazzop/form/login"
accessTokenLifetime="7201"
authorizationGrantLifetime="604801">
<autoAuthorizeClient>client01</autoAuthorizeClient>
<databaseStore dataSourceRef="OAuthFvtDataSource" />
</oauthProvider>
The value "604801" is 7 days plus 1 second, in seconds. It can be reduced to make refresh tokens expire quicker and therefore not accumulate as much in the database.
If the Java heap size needs to be increased, it can be done by creating the
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/jvm.options
file and adding Java memory options to it, one per line. For example, these entries will increase the heap size to 1GB:
-Xms1G
-Xmx1G
For more information, see
work item 471597
Test JAS Configuration
Jazz Team Server (JTS) Setup with JAS
- For a new deployment, CLM installation should be enabled for Jazz Security Architecture SSO
- Accessing the JTS setup page, https://jtsserver:port/jts/setup , would not prompt for a Username / Password
- Express setup would be disabled for a CLM instance enabled for Jazz Security Architecture SSO
- Run through the setup following the prompt until you reach "Register Applications" Page
- Enter the Jazz Authentication Server details. The URL you enter should be accessible by all and is as important as the Jazz Public URI
- DONOT register applications at this stage, delete the listed applications that was found and proceed to next step
File based registry
- In the Next step (Step 6), "Select a type of User Registry, select Non-LDAP External Registry
- Create a user with userID details from users configured in localUserRegistry.xml
- Click on Save and Log in and Login as a User with JazzAdmin role
- Assign a License to the User
- Go back to Register Applications page (Step 5) and register all the applications
- Complete the setup
LDAP Registry
- Ensure pop-up blocker is disabled on the browser, or Pop-ups are allowed for CLM and JAS URLs
- In the Next step (Step 6), "Select a type of User Registry, select LDAP
- Enter the LDAP Details, there are 3 sections as mentioned below
- - LDAP Server and Bind User details
- - Base USer DN and USer Properties mapping
- - Group DN, Role and Property mapping
- Assign a license and click Next
- A Login window would be displayed, Login as a user with JazzAdmin role assigned
- Go back to Register Applications page (Step 5) and register all the applications
- Complete the setup
Enable an Existing CLM setup for Jazz Security Architecture
- Complete the Jazz Authorization Server Setup, Configuration and testing as per instructions within this article
- Enable CLM applications for Jazz Security Architecture single sign-on following the instructions on our InfoCenter
External links: