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.
![[iSeries]](../../iseries.gif)
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}
![[z/OS]](../../ngzos.gif)
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}
Note: 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: ![[Updated in November 2011]](../../delta.gif)
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.
![[Updated in November 2011]](../../deltaend.gif)
nov2011
gotcha
- 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:
- Using Jython:
AdminTask.addIdMgrRepositoryBaseEntry('-id urbcustom
-name o=custom')
AdminTask.addIdMgrRepositoryBaseEntry('-id urbRACF
-name o=local')
- Using Jacl:
$AdminTask addIdMgrRepositoryBaseEntry {-id urbcustom
-name o=custom}
$AdminTask addIdMgrRepositoryBaseEntry {-id urbRACF
-name o=local}
- 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
![[iSeries]](../../iseries.gif)
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.
![[z/OS]](../../ngzos.gif)
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>