r30 - 2024-08-15 - 14:34:03 - TimFeeneyYou are here: TWiki >

Deployment Web > DeploymentInstallingUpgradingAndMigrating > JazzAuthorizationServer > JASAndSCIM

Configure Jazz Authorization Server for SCIM

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

Page contents

Important Notes and Pre-requisites
Installation
Setup and Configure JAS for SCIM with LDAP Registry
Jazz Team Server (JTS) Setup with JAS and SCIM
Configure SCIM Property To UserID Mapping
- SCIM Property to User ID Mapping attribute Parameters
Enable an Existing CLM setup for Jazz Security Architecture
Importing Users
Troubleshooting JTS Setup issues
- Error: Call to SCIM provider failed. Unexpected Character "69": line 1, Column 1
- Error: Internal Server Error. Details: A call to the SCIM provider failed.

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.
This article will focus on the configuration steps to setup CLM / ELM with JAS for SCIM.

Important Notes and Pre-requisites

It is recommended to upgrade to CLM and JAS Version 6.0.6.1 (with the latest iFix) or higher to configure SCIM with JAS
To configure SCIM you must use Lightweight Directory Access Protocol (LDAP) for User registries in JAS
The screenshots on the SCIM configurations in CLM / ELM are from version 6.0.6.1. In earlier versions there are additional options in SCIM configuration

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 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 and ldapUserRegistry.xml
appConfig.xml - Contains Jazz Group/Role mappings and UserRegistry file information
ldapUserRegistry.xml - Configuring Liberty with an LDAP user 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> 
```

Configure JAS with LDAP registry

To configure SCIM you must use Lightweight Directory Access Protocol (LDAP)
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/appConfig.xml file and towards the end of the file change the following

 <include location="localUserRegistry.xml" optional="true"/>
    <!--include location="ldapUserRegistry.xml" optional="true"/-->

 <!--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) in this article to help guide the configuration
We have also included SCIM related configurations in ldapUserRegistry.xml

Edit [JazzAuthServer_Install_Dir]/wlp/usr/servers/jazzop/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" sslEnabled="false">  
        
        <activedFilters
                        userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user))"
                        groupFilter="(&amp;(cn=%v)(objectcategory=group))"
                        userIdMap="user:sAMAccountName"
                        groupIdMap="*:cn"
                        groupMemberIdMap="memberOf:member" >
                </activedFilters>

        <attributeConfiguration>
             <attribute name="cn" propertyName="displayName" entityType="PersonAccount"/>
             <!-- propertyName is the scim property, name is the ldap property-->
        </attributeConfiguration>

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

   </server>

Users or Groups listed under <administrator-role> tag are SCIM Administrators
The configuration under < attributeConfiguration > is mandatory as the displayName SCIM property is mapped to Name attribute in CLM / ELM. You can change the LDAP attribute mapping from cn to as per your organization's requirement.

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>

    <attributeConfiguration>
             <attribute name="cn" propertyName="displayName" entityType="PersonAccount"/>
             <!-- propertyName is the scim property, name is the ldap property-->
     </attributeConfiguration>

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

Users or Groups listed under <administrator-role> tag are SCIM Administrators
The configuration under < attributeConfiguration > is mandatory as the displayName SCIM property is mapped to Name attribute in CLM / ELM. You can change the LDAP attribute mapping from cn to as per your organization's requirement
< 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"
               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>

              <attributeConfiguration>
                   <attribute name="cn" propertyName="displayName" entityType="PersonAccount"/>
                   <!-- propertyName is the scim property, name is the ldap property-->
              </attributeConfiguration>

       </ldapRegistry>

        <administrator-role>
                <user>myscimdmin</user>
        </administrator-role>

</server>

The configuration under < attributeConfiguration > is mandatory as the displayName SCIM property is mapped to Name attribute in CLM / ELM. You can change the LDAP attribute mapping from cn to as per your organization's requirement
Users or Groups listed under <administrator-role> tag are SCIM Administrators
There are instances during JTS Setup , the SCIM configuration test would report a Timestamp mismatch error. Including the < timestampFormat > 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 to example 100k users, add the following within the ldapRegistry.xml within the < server > 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

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

<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 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 Oracle, MSSQL and DB2 database servers 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

Now that JAS is configured with LDAP and SCIM, it is time to start and test if it is configured right

Start the server (Linux example)

    $ cd JazzAuthServer_install_dir
    $ ./start-jazz

Access the following URLs to test JAS and SCIM configuration
- JAS Configuration URL (Default value for a new setup is data [ ] )
  https://fully_qualified_domain_name_of_JAS_server:defined_port/oidc/endpoint/jazzop/.well-known/openid-configuration
  https://fully_qualified_domain_name_of_JAS_server:defined_port/oidc/endpoint/jazzop/registration
- Confirm the SCIM API for Users with this URL
  https://fully_qualified_domain_name_of_JAS_server:defined_port/ibm/api/scim/Users
- Confirm the SCIM API for Groups with this URL
  https://fully_qualified_domain_name_of_JAS_server:defined_port/ibm/api/scim/Groups

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

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

In the Next step (Step 6), "Select a type of User Registry", select SCIM
Enter the SCIM Provider URL and Bind User Information

Note: The Jazz Group to Registry Group Mapping configuration is important for User to jazz group role mapping. When Users accesses an ELM application URL, they are redirected to JAS for Authentication. Post successful authentication JTS will fetch group information with SCIM details mentioned under com.ibm.team.repository.service.jts.internal.userregistry.scim.SCIMUserRegistryProvider

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
Complete the setup

Configure SCIM Property To UserID Mapping

By default the CLM login Id is configured to Ldap UserId attribute, example sAMAccountName or uid. If you wish to change the the CLM Login value to another LDAP attribute here are the steps.

If you have configured the userIdMap value in ldapUserRegistroy.xml file to different LDAP attribute , then change the SCIM configuration property in JTS Admin page
Navigate to https:/jtsserver:port/jts/admin page and Click Server > Advanced Properties and search for the property SCIM Property to User ID mapping

Change the value as per the details in this table. Also change “User Name” that is used to login LDAP registry.

mobile	phoneNumbers/type=mobile	LDAP User Mobile
Ldap UserId Attribute	SCIM Property to UserId Mapping	User Name
sAMAccountName, uid	userName (default value)	LDAP User Uid
mail	emails	LDAP User Email
mail	emails/type=work	LDAP User Email 2

SCIM Property to User ID Mapping attribute Parameters

SCIM provider displays user information in following format

 
    {"emails":[{"value":"shubjitnaik@testmail.com", "where":"work"},{"value":"shubjit1@homemail.com", "where":"home"}], 
    "location":"https:\/\/jasserver:9643\/ibm\/api\/scim\/Users\/uid=shubjit,ou=Users,dc=ldap,dc=com",
    "displayName":"Shubjit Naik","schemas":["urn:scim:schemas:core:1.0"],"id":"uid=shubjit,ou=Users,dc=ldap,dc=com",
    "name":{"formatted":"Shubjit Naik","givenName":"Shubjit","familyName":"Naik"},"userName":"shubjit"}

To retrieve this information access the URL format below

https://[JAS_SERVER]:[JAS_PORT]/ibm/api/scim/Users/uid=shubjit,ou=Users,dc=ldap,dc=com

By default, the userName attribute value is used as CLM login Id, in this case it is shubjit
In the above example if you wish to use email to Login to clm, changing the value of "SCIM Property to User ID mapping" to emails would not work as there are multiple email addresses associated with the user and it would result in an error
The format to be used here is emails/where=work which will extract shubjitnaik@testmail.com as the value to Login to CLM

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

By default User Synchronization operation by default picks UserID=sAMAccountName for Microsoft AD and UserId=uid for IBM Tivoli Directory Server and ApacheDS.
If you wish to change the User ID mapping, follow the instructions under "Configure SCIM Property To UserID Mapping" in this article
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 you intended to configure
If the verification is complete, you can then "Synchronize the users from configured groups to CLM
- Navigate to https:/jtsserver:port/jts/admin page > Home and Click on Synchronize Jazz Team Server Users With External User Registry

Troubleshooting JTS Setup issues

Error: Call to SCIM provider failed. Unexpected Character "69": line 1, Column 1

During JTS setup , Step 6 or when you change the User Registry type to SCIM in JTS Admin > Advanced properties the following Error is encountered

   A call to the SCIM provider failed. Description: Internal Server Error. 
   Details: Unexpectd character "69": line1, column 1, uri=https://<JAS_URL>/ibm/api/scim/Users?count=1&startIndex=1&attributes=*

Cause - JAS Server running our of memory. Following errors would be registered in JAS logs

[3/10/21 10:20:13:366 EST] 00000036 com.ibm.ws.webcontainer.srt                                  W SRVE8115W: WARNING: Cannot set status. Response already committed.
[3/10/21 10:28:40:693 EST] 000001a4 SystemErr                                                    R Exception in thread "Default Executor-thread-90" 
[3/10/21 10:28:40:695 EST] 000001a4 SystemErr                                                    R java.lang.OutOfMemoryError
[3/10/21 10:28:40:696 EST] 000001a4 SystemErr                                                    R : 
[3/10/21 10:28:40:696 EST] 000001a4 SystemErr                                                    R Java heap space
[3/10/21 10:28:40:696 EST] 000001a4 SystemErr                                                    R    at 
[3/10/21 10:28:40:696 EST] 000001a4 SystemErr                                                    R java.util.concurrent.ConcurrentLinkedQueue
FFDC1015I: An FFDC Incident has been created: "java.lang.OutOfMemoryError: Java heap space com.ibm.ws.tcpchannel.internal.WorkQueueManager workerRun(req)" at ffdc_21.03.10_10.28.40.0.log

Resolution - Increase the Java Heap space allocated to JAS. By default 500 MB is allocated. To increase the heap perform the following

Create a new file jvm.options in [JAS_HOME]\wlp\usr\server\jazzop\
Add the following values and save the file
```
-Xms2G
-Xmx4G
```
Restart the JAS server and try JTS setup again

Error: Internal Server Error. Details: A call to the SCIM provider failed.

During JTS setup , step 6 or when we change the User Registry type in JTS Admin > Advanced properties the following Error is encountered

   A call to the SCIM provider failed. Description: Internal Server Error. 
   Details: A call to the SCIM provider failed. Description: https://<JAS_URL>/ibm/api/scim/Users?count=1&startIndex=1&attributes=*

Cause : The URL https://[JAS_URL]/ibm/api/scim/Users?count=1&startIndex=1&attributes=* fails to load. You would see errors similar to

{"Errors":[{"code":"500","description":"com.ibm.wsspi.security.wim.exception.WIMSystemException: CWIML1013E: The user registry operation could not be completed. 
The entered value of the property manager is not valid for the entity uid=user1,ou=Users,dc=test,dc=com. The value of the property must be correct and must be of the correct data type."}]}

Our investigations revealed that there are identifier attributes like manager or secretary which links to users that does not exist in the LDAP registry. Based on the above error if we lookup for the user uid=user1 on the LDAP registry, the attribute manager linked to a non existing user. In such cases you would encounter an error.

Resolution - You can remap the identifier attributes. For example, manager could be remapped as shown in example snippet below.

<ldapRegistry ... >
    ...
    <attributeConfiguration>
      ...
      <!--
            1. We are mapping the manager property to a non-existent attribute so that no value is found.
            2. We are mapping the newly defined extended property myManager to manager. We have 
                 defined the syntax as a string so that it will not treat it as an Identifier and try to look it up.
        -->
      <attribute name="notsupported" propertyName="manager" syntax="Identifier" entityType="PersonAccount" />
      <attribute name="manager" propertyName="myManager" syntax="String" entityType="PersonAccount" />
    </attributeConfiguration>
   ...
  </ldapRegistry>
  
  <federatedRepository ...>
    <!--
         Add an extended property myManager that we can use to look up any managers.
      -->
    <extendedProperty dataType="String" name="myManager" entityType="PersonAccount" />
  </federatedRepository>

Post restart of JAS server try loading the URL https://[JAS_URL]/ibm/api/scim/Users?count=1&startIndex=1&attributes=*

External links:

Deployment

Community information and contribution guidelines

Status icon key:

To do
Under construction
New
Updated
Constant change
None - stable page

Smaller versions of status icons for inline text:

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.