Configure the user registry bridge for federated repositories

The user registry bridge is configured like other custom adapters. We can use the Jython or Jacl scripting language with the wsadmin scripting tool to define the user registry bridge in the federated repositories configuration.

Shut down WebSphere Application Server and wsadmin window.

Important: If we are migrating from the stand-alone user registry on the local operating system to federated repositories on the local operating system, first configure the current user registry under federated repositories. For more information, see Managing the realm in federated repository.

Authorization failures might occur if users or groups are mapped to roles before migration and you use those users or groups after migrating to user registry bridge. This situation occurs because the mapping contains registry-specific information. After migration, re-map the users or groups to avoid authorization failures.

For additional information about the commands to use for this topic, see IdMgrRepositoryConfig command group (AdminTask).

Use the following steps to add a user registry bridge to any federated repositories configuration and to any realm defined within the configuration.

1. Start the wsadmin scripting tool. We can use the following command to start the wsadmin scripting tool:
   wsadmin -conntype none

2. Use the createIdMgrCustomRepository command to add a new repository configuration for the user registry bridge.

   The following example configures a custom repository to use the com.ibm.ws.wim.adapter.urbridge.URBridge class and sets urbcustom as the identifier:

   Jython:

   AdminTask.createIdMgrCustomRepository('-id urbcustom -adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge')

   Jacl:

   $AdminTask createIdMgrCustomRepository {-id urbcustom -adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge}

   (zos) The following example configures a custom repository to use the com.ibm.ws.wim.adapter.urbridge.URBridge class and sets urbRACF as the identifier:

   Jython:

   AdminTask.createIdMgrCustomRepository('-id urbRACF -adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge')

   Jacl:

   $AdminTask createIdMgrCustomRepository {-id urbRACF -adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge}

   The user registry bridge handles requests to one user registry only. If you define multiple repositories, each user registry implementation must have a separate instance of the user registry bridge and define each implementation as a separate repository with a unique repository ID..

   (zos) The Resource Access Control Facility (RACF) manages all the RACF attributes; therefore, we do not need to add any custom properties to use the user registry bridge adapter with RACF. gotcha

3. Optional: Add the necessary registry-specific properties as custom properties. Use the setIdMgrCustomProperty command repeatedly to add multiple properties. Use this command once per property to add multiple properties to the configuration. We must use both the name and value parameters to add the custom property for the specified repository. For example, to add a custom property of uniqueUserIdProperty, enter the following command:

   Jython:

   AdminTask.setIdMgrCustomProperty('-id urbcustom -name uniqueUserIdProperty -value "uniqueId"')

   Jacl:

   $AdminTask setIdMgrCustomProperty {-id urbcustom -name uniqueUserIdProperty -value "uniqueId"}

   To configure the user registry bridge to use a custom user registry, add the registryImplClass property and specify the exact registry implementation class. For example, specify com.xyz.abc.MyCustomRegistry as the value for the property.

   To configure the user registry bridge to use the local operating system user registry, do not specify the registryImplClass property. The user registry bridge identifies the underlying user registry implementation provided by WebSphere Application Server for the local operating system.

   We can set other optional properties as custom properties to define the mapping between federated repository properties and user registry properties, such as uniqueUserIdProperty, userSecurityNameProperty, userDisplayNameProperty, uniqueGroupIdProperty, groupSecurityNameProperty, and groupDisplayNameProperty. For more information about the available custom properties and their default values, see Security custom properties. To override any of these properties at the user registry level, configure the property as a custom property.

   The mapping between a federated repository property and user registry property is one-to-one. We can map only one federated repository property to a user registry property.gotcha

4. Add a base entry to the user registry bridge configuration. Use the addIdMgrRepositoryBaseEntry command to specify the name of the base entry for the specified repository. For example:

   Jython:

   (dist)(iseries)

   AdminTask.addIdMgrRepositoryBaseEntry('-id urbcustom -name o=custom')

   (zos)

   AdminTask.addIdMgrRepositoryBaseEntry('-id urbRACF -name o=local')

   Jacl:

   (dist)(iseries)

   $AdminTask addIdMgrRepositoryBaseEntry {-id urbcustom -name o=custom}

   (zos)

   $AdminTask addIdMgrRepositoryBaseEntry {-id urbRACF -name o=local}

5. Use the addIdMgrRealmBaseEntry command to add the base entry to the realm, which will link the realm with the repository.

   The default realm name is defaultWIMFileBasedRealm. If this realm name was previously renamed, use the new realm name instead of defaultWIMFileBasedRealm. For example, to ensure consistency, we can set the realm name of the federated repository configuration to be the same name as the local operating system user registry as specified in security.xml. For information about how to set the realm name, see Realm configuration settings.

   Use the following command:

   Jython:

   (dist)(iseries)

   AdminTask.addIdMgrRealmBaseEntry('-name defaultWIMFileBasedRealm -baseEntry o=custom')

   (zos)

   AdminTask.addIdMgrRealmBaseEntry('-name defaultWIMFileBasedRealm -baseEntry o=local')

   Jacl:

   (dist)(iseries)

   $AdminTask addIdMgrRealmBaseEntry {-name defaultWIMFileBasedRealm -baseEntry o=custom}

   (zos)

   $AdminTask addIdMgrRealmBaseEntry {-name defaultWIMFileBasedRealm -baseEntry o=local}

6. Save the configuration changes. Enter the following commands to save the new configuration and close the wsadmin scripting tool:

   Jython:

   AdminConfig.save()
   exit

   Jacl:

   $AdminConfig save exit

7. (zos) Configure the System Authorization Facility (SAF) mapping module to ensure the property availability of SAF authorization.

   For more information about how to configure a SAF mapping module, see Installing and configuring a custom System Authorization Facility mapping module for WebSphere Application Server, where a sample SAF mapping module is provided for you to install and use. To customize the sample SAF mapping module for federated repositories, see Configuring a custom System Authorization Facility (SAF) mapping module for federated repositories.

   Note: For the SAF distributed identity mapping feature, we do not need to configure this mapping module.

   (zos) Note: Some additional steps might be required if RACF is configured in a realm other than the defaultWIMFileBasedRealm. When a new realm is created, some properties take defaults that are not the same as those used by defaultWIMFileBasedRealm and are not appropriate for use with a federated RACF user registry. We must use the setIdMgrRealmURAttrMapping command to set the following values:

   • The value of userSecurityNameMapping property, propertyForOutput parameter must be set to principalName.

   • The value of groupSecurityNameMapping property, propertyForOutput parameter must be set to cn.

   For more information on how to use the setIdMgrRealmURAttrMapping command, see IdMgrRealmConfig (AdminTask).

8. Restart the application server.

Results

The following code is an example of a basic configuration in the wimconfig.xml file for a user registry bridge accessing a custom user registry:

<config:repositories adapterClassName="com.ibm.ws.wim.adapter.urbridge.URBridge" id="urbcustom">
<config:baseEntries name="o=custom"/>
  <config:CustomProperties name="registryImplClass" value="com.ibm.registry.impl.FileRegistrySample"/>
  <config:CustomProperties name="usersFile" value="${USER_PROPS}"/>
  <config:CustomProperties name="groupsFile" value="${GROUP_PROPS}"/>
</config:repositories> 

In the previous example, the ${USER_PROPS} and ${GROUP_PROPS} variables are used to define the values of the custom properties.

We can use variables to define custom properties. However, these variables are resolved only in the WAS connected mode. For information about how to define environment variables, see WebSphere variables.

(zos) The following code is an example from a wimconfig.xml file configured for a user registry bridge accessing the local operating system registry using RACF:

<config:repositories xsi:type="config:FileRepositoryType"     adapterClassName="com.ibm.ws.wim.adapter.file.was.FileAdapter"
   id="InternalFileRepository" supportPaging="false"     messageDigestAlgorithm="SHA-1">
         <config:baseEntries name="o=defaultWIMFileBasedRealm"/>
</config:repositories>
<config:repositories adapterClassName="com.ibm.ws.wim.adapter.urbridge.URBridge"
   id="urbRACF" supportPaging="false">
          <config:baseEntries name="o=local"/>
</config:repositories>
<config:realmConfiguration defaultRealm="defaultWIMFileBasedRealm">
      <config:realms delimiter="/" name="defaultWIMFileBasedRealm" securityUse="active">
            <config:participatingBaseEntries name="o=defaultWIMFileBasedRealm"/>
            <config:participatingBaseEntries name="o=local"/>
            <config:uniqueUserIdMapping propertyForInput="uniqueName"                propertyForOutput="uniqueName"/>
            <config:userSecurityNameMapping propertyForInput="principalName"                propertyForOutput="principalName"/>
            <config:userDisplayNameMapping propertyForInput="principalName"                propertyForOutput="principalName"/>
            <config:uniqueGroupIdMapping propertyForInput="uniqueName"                propertyForOutput="uniqueName"/>
            <config:groupSecurityNameMapping propertyForInput="cn"                propertyForOutput="cn"/>
            <config:groupDisplayNameMapping propertyForInput="cn" propertyForOutput="cn"/>
      </config:realms>
</config:realmConfiguration>

Subtopics

• User registry bridge for federated repositories
  The user registry bridge is a read-only adapter that provides an interface between federated repositories and an underlying user registry implementation, which can be either a local operating system user registry or a custom user registry implementation.

Related concepts

(zos) Distributed identity mapping using SAF

Related tasks

Manage the realm in federated repository

WebSphere variables

(zos) Configure a custom System Authorization Facility mapping module for WebSphere Application Server

(zos) Configure a custom System Authorization Facility (SAF) mapping module for federated repositories

IdMgrRepositoryConfig (AdminTask)

Security custom properties

Realm configuration settings