The user registry bridge is configured like other custom adapters. You can use the Jython
or Jacl scripting language with the wsadmin scripting tool to define the user registry bridge in the
federated repositories configuration.
Before you begin
Shut down WebSphere® Application Server and the wsadmin command window.
Important: If you are migrating from the stand-alone user registry on the local
operating system to federated repositories on the local operating system, you must first configure
the current user registry under federated repositories. For more information, see Managing the realm
in a federated repository configuration.
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.
About this task
For additional information about the commands to use for this topic, see
IdMgrRepositoryConfig command group for the AdminTask object.
Use the following steps to add a user registry bridge to any federated repositories configuration
and to any realm that is defined within the configuration.
Procedure
- Start the wsadmin scripting tool.
You can use the following command to start
the wsadmin scripting
tool:
wsadmin -conntype none
- 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:
- Using Jython:
-
AdminTask.createIdMgrCustomRepository('-id urbcustom
-adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge')
- Using Jacl:
-
$AdminTask createIdMgrCustomRepository {-id urbcustom
-adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge}
The following example configures a custom repository to use the
com.ibm.ws.wim.adapter.urbridge.URBridge class and sets urbRACF as the identifier:
- Using Jython:
-
AdminTask.createIdMgrCustomRepository('-id urbRACF
-adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge')
- Using Jacl:
-
$AdminTask createIdMgrCustomRepository {-id urbRACF
-adapterClassName com.ibm.ws.wim.adapter.urbridge.URBridge}
Avoid trouble: The user registry bridge handles requests to one user
registry only. Therefore, if you define multiple repositories, each user registry implementation
must have a separate instance of the user registry bridge and you must define each implementation as
a separate repository with a unique repository ID..
The Resource Access Control
Facility (RACF) manages all the RACF attributes; therefore, you do not need to add any custom
properties to use the user registry bridge adapter with RACF.
- 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 your configuration. You 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:
- Using Jython:
-
AdminTask.setIdMgrCustomProperty('-id urbcustom
-name uniqueUserIdProperty -value "uniqueId"')
- Using Jacl:
-
$AdminTask setIdMgrCustomProperty {-id urbcustom
-name uniqueUserIdProperty -value "uniqueId"}
To configure the user registry bridge to use a custom user registry, you must 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 that is
provided by WebSphere Application Server for the local operating
system.
You 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.
Avoid trouble: The mapping between a federated repository property and user registry
property is one-to-one. You can map only one federated repository property to a user registry
property.
- Add a base entry to the user registry bridge configuration.
- Use the addIdMgrRealmBaseEntry command to add the base entry to the
realm, which will link the realm with the repository.
Note: 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, you
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 the security.xml file. For
information about how to set the realm name, see Realm configuration settings.
- Save your configuration changes.
Enter the following commands to save the new
configuration and close the wsadmin scripting tool:
- Using Jython:
-
AdminConfig.save()
exit
- Using Jacl:
-
$AdminConfig save
exit
- 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. If you want to customize the sample SAF mapping module for federated
repositories, see Configuring a custom System Authorization Facility (SAF) mapping module for
federated repositories.
Note: If you are using the SAF distributed identity mapping feature, you do
not need to configure this mapping module.
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. You 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 command group for the AdminTask object.
- 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.
You can use variables to define custom properties. However, these
variables are resolved only in the WebSphere Application Server connected
mode. For information about how to define environment variables, see Creating, editing, and deleting
WebSphere variables.
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>