Configure Jazz Authorization Server for SCIM todo.png

Author: ShubjitNaik
Build basis: JAS and CLM version 6.0.2 and higher

Jazz Authorization Server (JAS) can be configured to use the System for Cross-domain Identity Management (SCIM) for the WebSphere Liberty profile. SCIM is a standard for cloud-based identity management for single sign-on (SSO) in browsers. It is a RESTful protocol for identity account management operations.
Starting in Rational solution for Collaborative Lifecycle Management (CLM) 6.0.2, Jazz Authorization Server supports SCIM in the Liberty profile. This article will focus on configuration steps to setup CLM with JAS for SCIM.

Important Notes and Pre-requisites

  • Starting in Collaborative Lifecycle Management (CLM) 6.0.2, Jazz Authorization Server (JAS) supports SCIM in the Liberty profile
  • To configure SCIM you must use Lightweight Directory Access Protocol (LDAP)

  • For Microsoft Active Directory LDAP Server, CLM and JAS version 6.0.2 or higher needs to be deployed
  • For any other LDAP Registries, the minimum version of CLM and JAS required to configure SCIM is 6.0.4 (GA in 2017) or higher
  • Currently the User Synchronization operation by default picks UserID=sAMAccountName for Microsoft AD and UserId=uid for IBM Tivoli Directory Server and ApacheDS. It is recommended to disable the Nighty Sync operation until verification is completed.
  • Screenshots added for Non-Microsoft AD configurations are from CLM and JAS versions 6.0.4 M2

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

    Enable_JAS_SSO.jpg

JAS

  • Download Jazz Authorization Server install bit from jazz.net, under All Downloads Section for the specific version

    JAS_Download.jpg

  • Install Jazz Authorization Server application via Installation Manager, instructions available on our Infocenter

    JAS_Install.jpg

Setup and Configure JAS for SCIM with LDAP 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

Enable SCIM

  • First Enable the Jazz Authorization Server to support SCIM
  • Edit JazzAuthServer_install_dir/wlp/usr/servers/jazzop/server.xml and include the following in the list of features
  • <feature>scim-1.0</feature> 
  • To configure SCIM you must use Lightweight Directory Access Protocol (LDAP)

Configure JAS with LDAP registry

  • By default the bundled Liberty profile is configure with File based user registry and we need to configure it to point to the LDAP server to get information
  • To do that, edit JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults/appConfig.xml file and 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 fro 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
  • We have also included SCIM related configurations in ldapRegistry.xml
  • Users or Groups listed under <administrator-role> tag are SCIM administrators

  • Edit JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults/ldapUserRegistry.xml and modify to match your environment, examples below

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="(&amp;(sAMAccountName=%v)(objectcategory=user))"
                            groupFilter="(&amp;(cn=%v)(objectcategory=group))"
                            userIdMap="user:sAMAccountName"
                            groupIdMap="*:cn"
                            groupMemberIdMap="memberOf:member" >
                    </activedFilters>
        </ldapRegistry>
    
           <federatedRepository>
                    <primaryRealm name="FVTRegistry">
                            <participatingBaseEntry name="CN=Users,DC=test,DC=com"/>
                    </primaryRealm>
            </federatedRepository>
    
            <administrator-role>
               <user>clmadmin</user>
               <group>MyJazzAdmins</group>
            </administrator-role> &lt;/font&gt;
    
       </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" searchTimeout="10m" 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>
    
        <ldapEntityType name="PersonAccount">
                    <searchBase>c=in,ou=Users,o=test.com</searchBase>
         </ldapEntityType>
                <ldapEntityType name="Group">
                    <searchBase>ou=JazzGroups,ou=Groups,o=test.com</searchBase>
          </ldapEntityType>
    
        </ldapRegistry>
    
          <administrator-role>
                     <user>myscimadmin</user>
          </administrator-role>
        </server> 
  • < ldapEntityType > tag is not mandatory, but can be used to limit the User and group query scope

Apache DS

  • <server>
            <ldapRegistry ldapType="Custom" baseDN="dc=example,dc=com" host="ldapserver" 
                   id="ldapserver:10389" ignoreCase="true" port="10389" 
                   realm="ldapserver:10389" recursiveSearch="true" referal="follow" 
                   sslEnabled="false" timestampFormat="yyyyMMddHHmmss.SSSSSSZ">
                  
                 <customFilters
                        groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
                        groupIdMap="*:cn" 
                        groupMemberIdMap="groupOfUniqueNames:uniquemember"
                        userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))"
                        userIdMap="*:uid" >
                  </customFilters>
           </ldapRegistry>
    
            <administrator-role>
                    <user>myscimdmin</user>
            </administrator-role>
    
    </server> 
  • There are instances during JTS Setup , the SCIM configuration test would report a Timestamp mismatch error. Including the attribute as shown above resolves the error.

Search results limit Large User User Registry

  • Default Search results limit for Users and Groups is set to 4000 for SCIM. To increase it example 100k users, add the following within the ldapRegistry.xml within the pair
  • <federatedRepository maxSearchResults="100000" /> 

Encrypt Passwords

  • To encrypt passwords entered in "bindPassword", run the script JazzAuthServer_install_dir/wlp/bin/securityUtility
  • After the script completes, copy the output to the bindPassword attribute for the ldapRegistry section
  • To run the securityUtility script, use the following syntax:
  • $ securityUtility encode userPassword 
    where userPassword is the password to encode

Group Mappings

  • Map Groups to the respective Jazz Roles
  • Edit JazzAuthServer_install_dir/wlp/usr/servers/jazzop/appConfig.xml
  •  <application
         id="com.ibm.team.integration.jazzop"
         location="jazzop.war"
         name="com.ibm.team.integration.jazzop"
         context-root="jazzop"
         type="war">
            <application-bnd>
                <security-role name="JazzAdmins">
                    <group name="MYJAZZADMINS"/>
                </security-role>
                <security-role name="JazzUsers">
                    <group name="MYJAZZUSERS"/>
                </security-role>
                <security-role name="JazzProjectAdmins">
                    <group name="MYJAZZPROJECTADMINS"/>
                </security-role>
                <security-role name="JazzGuests">
                    <group name="MYJAZZGUESTS"/>
                </security-role>
                <security-role name="JazzDebug">
                    <group name="MYJAZZDEBUG"/>
                </security-role>
            </application-bnd>
        </application>

  • Map Groups and Users who would Administrate JAS
  • <oauth-roles>
            <authenticated>
                <special-subject type="ALL_AUTHENTICATED_USERS" />
            </authenticated>
            <clientManager>
                <group name="MYJAZZADMINS" />
                <user name = "MYSCIMADMIN" />
            </clientManager>
        </oauth-roles> 

Configure Database for JAS

When you first install the 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.

Test SCIM


Jazz Team Server (JTS) Setup with JAS and SCIM

  • For a new deployment, CLM installation should be enabled for Jazz Security Architecture SSO
  • Ensure pop-up blocker is disabled on the browser, or Pop-ups are allowed for CLM and JAS URLs
  • 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
    JTS_Setup.png

  • Run through JTS setup following the prompts until you reach "Register Applications" Page
  • Enter the Jazz Authorization Server details. The URL you enter should be accessible by all and is as important as the Jazz Public URI

    JAS_Server.png

  • DONOT register applications at this stage, delete the listed applications that was found and proceed to next step

  • In the Next step (Step 6), "Select a type of User Registry", select SCIM

    SCIM_Config.png

  • Enter the SCIM Provider URL and Bind User Information
    SCIM_Registry.png

  • Enter the Base Group DN and Group mapping information

    Version 6.0.3 and below
    SCIM_User_Group.png

    Version 6.0.4 and above
    SCIM_User_Group_604.png

  • Click Test Connection, Save and Next, A Login window would be displayed, Login as a user with JazzAdmin role assigned
  • Assign a License for the User
  • 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 SCIM 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
  • Access the JTS Setup URL and click next until you reach step 6
  • "Select a type of User Registry", select SCIM and follow instructions similar to a new JTS setup
  • Click Test Connection and Next to save the Configuration

Importing Users

* Currently the User Synchronization operation by default picks UserID=sAMAccountName for Microsoft AD and UserId=uid for IBM Tivoli Directory Server and ApacheDS. It is recommended to disable the Nighty Sync operation until verification is completed.

  • To disable Nightly Sync, Login to JTS/admin page, Click Server > Advanced Properties and set Enable Nightly Sync with SCIM provider to false
  • Test by importing a user manually
  • Click on Users > Active Users > Import Users
  • Enter a search term, click on the User and Import the user
  • In the Active User Page, click on the newly imported user and confirm the UserId maps to what is configured in JAS
    • Default is uid for Tivoli and Apache DS and sAMAccountName for Microsoft AD
  • If the verification is complete, you can chose to enable the Nightly Sync or proceed with Manual Import of User
  • To Manually Import users , use the repotools command and import from acsv file. Instructions are available on the IBM Knowledge Center

Related topics: Jazz Authorization Server, Deployment web home

External links:

This topic: Deployment > WebHome > DeploymentInstallingUpgradingAndMigrating > JazzAuthorizationServer > JASAndSCIM
History: r16 - 2017-02-23 - 11:17:52 - ShubjitNaik
 
This site is powered by the TWiki collaboration platformCopyright © 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.