JASUserRegistryConfig < Deployment

Engineering Lifecycle Management Wiki - Deployment
Community information and contribution guidelines
TWiki > Deployment Web > DeploymentInstallingUpgradingAndMigrating > JazzAuthorizationServer > JASUserRegistryConfig
Revision 25 - 2025-05-21 - 18:38:54 - RichardRakich
<div id="header-title" style="padding: 10px 15px; border-width:1px; border-style:solid; border-color:#FFD28C; background-image: url(<nop>https://jazz.net/wiki/pub/Deployment/WebPreferences/TLASE.jpg); background-size: cover; font-size:120%">
---+!! Configure JAS with a User Registry - LDAP or File Based  
%DKGRAY% Authors: Main.ShubjitNaik <br>
Build basis: JAS and ELM version 6.0.x, 7.x
%ENDCOLOR%</div></sticky>

<!-- Page contents top of page on right hand side in box -->
<sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;">
%TOC{title="Page contents"}%
</div></sticky>

<sticky><div style="margin:15px;"></sticky>

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

 *ELM* %BR%
   * To deploy JAS to an existing environment and migrate to JAS, visit this [[https://www.ibm.com/docs/en/elm/7.0.2?topic=management-enabling-jazz-security-architecture-sso-after-upgrade][Section]] on our Infocenter
   * For a new deployment of ELM, Install the applications via IBM Installation Manager and Select the option "Enable Jazz Security Architecture SSO" during the installation%BR%%BR%
   <img src="https://jazz.net/wiki/pub/Deployment/JASAndSCIM/Enable_JAS_SSO.jpg" alt="Enable_JAS_SSO.jpg" width="650" height="250" /> %BR%

 *JAS* %BR%
   * Download Jazz Authorization Server install bit from [[https://jazz.net/downloads/elm/releases/7.0.2?p=allDownloads][jazz.net]], under All Downloads Section for the specific version%BR%%BR%
   <img src="https://jazz.net/wiki/pub/Deployment/JASAndSCIM/JAS_Download.jpg" alt="JAS_Download.jpg" width="400" height="75" /> %BR%%BR%
   * Install Jazz Authorization Server application via Installation Manager, instructions available on our [[https://www.ibm.com/support/knowledgecenter/SSYMRC_7.0.2/com.ibm.jazz.install.doc/topics/t_s_server_installation_im.html][Infocenter]]%BR%%BR%
   <img src="https://jazz.net/wiki/pub/Deployment/JASAndSCIM/JAS_Install.jpg" alt="JAS_Install.jpg" width="600" height="200" /> %BR%

---++ 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



---+++ To 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/appConfig.xml= file
   * Towards the end of the file change from
   * <verbatim> <include location="localUserRegistry.xml" optional="true"/>
    <!--include location="ldapUserRegistry.xml" optional="true"/--></verbatim>
   *TO*
   * <verbatim> <!--include location="localUserRegistry.xml" optional="true"/-->
    <include location="ldapUserRegistry.xml" optional="true"/></verbatim> %BR%

   * 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 [[https://www.ibm.com/support/knowledgecenter/SSYMRC_6.0.3/com.ibm.jazz.install.doc/topics/t_config_ldap_connection_liberty.html][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/ldapUserRegistry.xml= and modify the ldapRegistry configuration for your LDAP registry

---++++ Microsoft Active Directory

   * <verbatim><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" sslEnabled="false">  
        
        <activedFilters
                        userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user))"
                        groupFilter="(&amp;(cn=%v)(objectcategory=group))"
                        userIdMap="user:sAMAccountName"
                        groupIdMap="*:cn"
                        groupMemberIdMap="memberOf:member" >
                </activedFilters>
    </ldapRegistry>

</server></verbatim>

---++++ IBM Tivoli Directory Server

   * <verbatim> <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="(&amp;(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
         groupIdMap="*:cn"
         groupMemberIdMap="groupOfUniqueNames:uniquemember"
         userFilter="(&amp;(uid=%v)(objectclass=person))"
         userIdMap="*:uid">
    </idsFilters>

    </ldapRegistry>
    </server> </verbatim>

---++++ Apache DS

   * <verbatim><server>
        <ldapRegistry ldapType="Custom" baseDN="dc=example,dc=com" host="localhost" 
              id="localhostexample:10389" ignoreCase="true" port="10389"  
              realm="localhostexample:10389" recursiveSearch="true" sslEnabled="false">
              
             <customFilters
                    groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
                    groupIdMap="*:cn" 
                    groupMemberIdMap="groupOfUniqueNames:uniquemember"
                    userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))"
                    userIdMap="*:uid" >
              </customFilters>
       </ldapRegistry>
</server> </verbatim>


---+++ To 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
   * File based user registry should not be used for production environments.
      * No password management functionality
      * No password policy enforcement
      * No direct user ability to change passwords.

   <verbatim>
<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> </verbatim>

   * You can either enter _Plain Text Passwords_ or encrypt the passwords using the [[https://jazz.net/wiki/bin/view/Deployment/JASUserRegistryConfig#Encrypt_Passwords][securityUtility]]

---++++ Map Administrators for Jazz Authorization Server

Map Groups or Users as JAS Administrators who can perform JAS CLI operations, register Applications to JAS and access !WebSphere Liberty !AdminConsole JAS

   <verbatim><oauth-roles>
        <authenticated>
            <special-subject type="ALL_AUTHENTICATED_USERS" />
        </authenticated>
        <clientManager>
            <group name="MYJazzAdmins" />
            <group name="JazzAdmins"/>
            <user name = "clmadmin" />
        </clientManager>
    </oauth-roles> </verbatim>

---++++ Encrypt Passwords

   * To encrypt passwords, run the script =JazzAuthServer_install_dir/wlp/bin/securityUtility=
   * After the script completes, copy the output to the password attribute associated with the user ID (or bindPassword)
   * To run the securityUtility script, use the following syntax:
   * <verbatim>$ securityUtility encode userPassword </verbatim>
     where _userPassword_ is the password to encode

---++ 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.

   * [[https://jazz.net/wiki/bin/view/Deployment/PerformanceClusteredJAS#DB2][Configure IBM DB2 Database]]
   * [[https://jazz.net/wiki/bin/view/Deployment/PerformanceClusteredJAS#Oracle][Configure Oracle Database]]
   * [[https://jazz.net/wiki/bin/view/Deployment/PerformanceClusteredJAS#Microsoft_SQL_Server][Configure Microsoft SQL Server Database]]

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 &lt;oauthProvider&gt; element in the =JazzAuthServer_install_dir/wlp/usr/servers/jazzop/appConfig.xml= file. The default configuration is

<verbatim>
<oauthProvider id="JazzOP"
  httpsRequired="true"
  autoAuthorize="true"
  customLoginURL="/jazzop/form/login" 
  accessTokenLifetime="7201" 
  authorizationGrantLifetime="604801">
  <autoAuthorizeClient>client01</autoAuthorizeClient>
  <databaseStore dataSourceRef="OAuthFvtDataSource" /> 
</oauthProvider>
</verbatim>

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.

For more information, see [[https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/471597][work item 471597]]

---++ JVM 

The default JVM heap allocated to a !WebSphere Liberty server is 60MB. This applies to JAS as well and to increase the Java heap size, you can create jvm.options file under =JazzAuthServer_install_dir/wlp/usr/servers/jazzop/jvm.options= and include the JVM memory parameters, one per line. For example, these entries will increase the heap size to 2GB:

<verbatim>
-Xms2G
-Xmx2G
</verbatim>

For more information see [[https://www.ibm.com/docs/en/was-liberty/core?topic=manually-customizing-liberty-environment][Manually Customizing Liberty Environment]]

---++ Test JAS Configuration

   * Now that JAS is configured with a User registry, it is time to start the server and test the configuration
   * Start the server (Linux example)
    <verbatim>
    $ cd JazzAuthServer_install_dir
    $ ./start-jazz </verbatim>
   * Access the following URLs to test JAS
      * JAS Configuration URL %BR%
        https://fully_qualified_domain_name_of_JAS_server:defined_port/oidc/endpoint/jazzop/.well-known/openid-configuration %BR%
        and
        https://fully_qualified_domain_name_of_JAS_server:defined_port/oidc/endpoint/jazzop/registration
        _default value for the registration URL is_ ={"data":[]}=

---++ 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 %BR%
     <img src="%ATTACHURLPATH%/JTS_Setup.png" alt="JTS_Setup.png" width="600" height="125" /> %BR%

   * 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* %BR%
   <img src="%ATTACHURLPATH%/JAS_Server.png" alt="JAS_Server.png" width="400" height="250" /> %BR%
   

---+++ File based registry

   * In the Next step (Step 6), "Select a type of User Registry, select *Non-LDAP External Registry* %BR%
   <img src="%ATTACHURLPATH%/Basic_Config.png" alt="Basic_Config.png" width="350" height="175" /> %BR%

   * 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

*User to Role Mappings*

   * Groups to Jazz Roles mappings are picked from JTS configuration when JAS is configured with LDAP or SCIM. More details on the next section. 

Ensure pop-up blocker is disabled on the browser, or Pop-ups are allowed for ELM and JAS URLs. Here are instructions to configure JTS with LDAP User Registery

   * In the Next step (Step 6), "Select a type of User Registry, select *LDAP* %BR%
   <img src="%ATTACHURLPATH%/LDAP_Config.png" alt="LDAP_Config.png" width="350" height="225" /> %BR%
   * Enter the LDAP Details, there are 3 sections as mentioned below %BR%
      1 - LDAP Server and Bind User details %BR%
      <img src="%ATTACHURLPATH%/LDAP_Registry.png" alt="LDAP_Registry.png" width="500" height="300" /> %BR%%BR%
      2 - Base USer DN and USer Properties mapping %BR%
      <img src="%ATTACHURLPATH%/LDAP_User.png" alt="LDAP_User.png" width="520" height="250" /> %BR%%BR%
      3 - Group DN, Role and Property mapping %BR%
      <img src="%ATTACHURLPATH%/LDAP_Group.png" alt="LDAP_Group.png" width=600" height="575" /> %BR%%BR%
   * 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

---+++ ELM User group-to-role mapping 

User Groups to Jazz Roles mappings (!JazzAdmins, !JazzUsers etc) are picked from JTS configuration when JAS is configured with LDAP. When Users accesses an ELM application URL, they are redirected to JAS for Authentication. Post successful authentication JTS performs the ldapsearch Query to fetch groups with LDAP details mentioned under<br>
JTS > Advanced Properties > *com.ibm.team.repository.service.jts.internal.userregistry.ldap.LDAPUserRegistryProvider* for User group to Jazz role mappings. 

=Note: We can only map direct LDAP groups in JTS. Special Subjects like ALL_AUTHENTICATED_USERS or NESTED_GROUPS would not work with JAS based deployments=
<br>

Here is an extract from JTS logs with debug enabled, where it is mapping to the Jazz Groups configured in JTS.

<verbatim>DEBUG m.repository.servlet.internal.oidc.OidcAuthHandler [TID: 37404299] - Using group-to-role mapping 
"{cn=MYJazzAdmins,CN=Groups,DC=clm,DC=com:[JazzAdmins],cn=MYJazzGuests,CN=Groups,DC=clm,DC=com:[JazzGuests],cn=MYJazzProjectAdmins,CN=Groups,DC=clm,DC=com:[JazzProjectAdmins],cn=MYJazzUsers,CN=Groups,DC=clm,DC=com=com:[JazzUsers]}" for 300000 ms

/jts/service/com.ibm.team.repository.service.internal.IExternalUserRegistryRestService/externalUserRegistryConfiguration] 
DEBUG ce.jts.internal.userregistry.ldap.LDAPUserRegistry [TID: 7FEA9AFC] - Query to fetch group full names - ldapsearch -h ldap://ldapserver:389 -b "CN=Groups,DC=clm,DC=com" "(| (cn=MYJazzAdmins)(cn=MYJazzGuests)(cn=MYJazzProjectAdmins)(cn=MYJazzUsers))"
</verbatim>

For new installations, during 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_

---++ 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 [[https://www.ibm.com/docs/en/elm/7.0.2?topic=management-enabling-jazz-security-architecture-sso-after-upgrade][InfoCenter]]
%BR%
---+++++!! Related topics: [[JazzAuthorizationServer][Jazz Authorization Server]], [[DeploymentWebHome][Deployment web home]]

---+++++!! External links:          

   * [[https://www.ibm.com][IBM]]

<sticky></div></sticky>
Copyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.