This chapter explains how to use the OPSS identity store service. Topics include:
This section describes key concepts of the OPSS identity store service:
The identity store service enables you to query the identity store for user and role (group) information.
By default, a service instance supports querying against a single LDAP identity store. You can configure the service to support a virtualized identity store which queries multiple LDAP identity stores. This feature, known as identity virtualization, is described in Section 7.3, "Configuring the Identity Store Service".
Figure 7-1 shows the architecture of the identity store service. Depending on the configuration, the service can support either an XML file or one or more LDAP servers as the identity store.
When the service is configured for LDAP, it queries a single LDAP store by default. You can also configure the service to query multiple LDAP stores.
The identity store service supports:
Oracle WebLogic Server
Third-party application servers
The service configuration depends on the application server; you must specify the provider that supports the service.
The identity store service is available in a stand-alone Java SE environment.
For more information, see Section 7.3.6, "Java SE Environments".
Before you can make use of the identity store service, you need to configure the identity store provider. OPSS supports both file-based (XML) and LDAP-based providers.
This fragment from the jps-config.xml
file shows the configuration of both XML and LDAP providers. The serviceProvider
elements are children of the serviceProviders
element.
<serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider"> <description>LDAP-based IdentityStore Provider</description> </serviceProvider> <serviceProvider type="IDENTITY_STORE" name="idstore.xml.provider" class="oracle.security.jps.internal.idstore.xml.XmlIdentityStoreProvider"> <description>XML-based IdentityStore Provider</description> </serviceProvider>
If Active Directory is the identity store provider, set USERNAME_ATTR and USER_LOGIN_ATTR properties to be sAMAccountName
in jps-config.xml
(or jps-config-jse.xml
) if the default value (cn
) is to be overridden. For example:
<property value="sAMAccountName" name="username.attr"/> <property value="sAMAccountName" name="user.login.attr"/>
For details, see Section 8.8.1, "Configuring the Identity Store Provider".
This section describes how to configure the identity store service to LDAP-based stores. Topics include:
This section explains the different configuration parameters for the identity store service. It includes:
You use the following parameters to configure the service for multi-LDAP queries:
The virtualize
property - This property can be either true (multi-LDAP lookup) or false (single-LDAP lookup). The default is false
.
Global Connection Parameters (if 'virtualize
' is enabled) - The calling application uses these parameters to specify global LDAP configuration such as the search base, create base, and so on. If any of these parameters are not configured, OPSS uses default values.
Back-end Connection Parameters - These parameters are specific to each LDAP store. One set of back-end parameters is specified for each LDAP. You do not need to set these parameters unless you wish to overwrite existing values.
Table 7-1 shows the global parameters and their default values, if applicable.
Table 7-1 Global LDAP Identity Store Parameters
Parameter | Default Value |
---|---|
group.create.bases |
same as user.create.bases |
group.filter.object.classes |
groupofuniquenames The global value is used if explicitly provided. |
group.mandatory.attrs |
- |
group.member.attrs |
uniquemember |
group.object.classes |
groupofuniquenames |
group.search.bases |
- |
group.selected.create.base |
- |
group.selected.search.base |
- |
groupname.attr |
cn If the global value is explicitly given, it is used. |
max.search.filter.length |
- |
search.type |
- |
user.create.bases |
If only one authenticator, uses it as the create base value. If multiple authenticators, no default value is set; user must explicitly set the global value. |
user.filter.object.classes |
inetorgperson |
user.login.attr |
uid |
user.mandatory.attrs |
- |
user.object.classes |
inetorgperson If the global value is explicitly given, it is used. |
user.search.bases |
Same as group.search.bases |
username.attr |
cn The global value is used if explicitly provided. |
As mentioned earlier, these are specific to the back-end LDAP store. For details, see:
You configure LDAP authenticators in Oracle WebLogic Server using either the WebLogic console or WLST command-line. At runtime, Oracle WebLogic Server passes the configuration details to OPSS. Oracle WebLogic Server allows you to configure multiple authenticators in a given context, and selects the first authenticator to initialize the identity store service by default. This process is explained in Section 3.2.2.1, "Multiple Authenticators".
After the authenticators are configured, the identity store service can be set up to query one LDAP identity store or multiple stores. Configuring for multiple stores requires setting up the virtualize
property.
This section explains how to set up these options.
You can configure the identity store service to query only one LDAP store. See Example 7-2 which displays a fragment of the jps-config.xml
file with a single LDAP service instance.
In cases when the virtualize
property cannot be set, you can configure the identity store service to query more than one LDAP store and override the configuration in WebLogic Server. See Example 7-1 which displays a fragment of the jps-config.xml
file where a multiple LDAP service instance is defined using a comma separated list of LDAP urls.
As in the single LDAP setup, you start by configuring the authentication providers in Oracle WebLogic Server.
Next, perform these steps in Fusion Middleware Control:
Select the WebLogic domain in the navigation pane on the left.
Navigate to Security, then Security Provider Configuration.
Expand the Identity Store Provider section of the page.
Click Configure (corresponding to "Configure parameters for User and Role APIs to interact with identity store").
The Identity Store Configuration page appears.
Under Custom Properties, click Add.
Add the new property as follows:
Property Name=virtualize Value=true
Note:
Be sure to add the property to the identity store service instance in the default context.Click OK.
To configure the virtualize property using WLST, perform these steps:
Create a py
script file to connect to the administration server in the domain of interest. You need to specify the userName
, userPass
, localHost
, and portNumber
for the operation.
See Appendix E, "Configuring OPSS Service Provider Instances with a Script" for details about this script.
Navigate to $ORACLE_HOME/common/bin
.
Run the wlst.sh
command to execute the script.
For example, if the domain configuration file contains an authenticator named idstore.ldap, the following command:
wlst.sh /tmp/updateServiceInstanceProperty.py -si idstore.ldap -key "virtualize" -value "true"
configures the provider for multi-LDAP lookup.
To configure the timeout setting using WLST, perform these steps:
Run the following WLST command to list all adapters: listAdapters()
.
Run the following WLST command to set the timeout for each adapter. 120 second timeout is an example, set to zero for no timeout.
modifyLDAPAdapter('<ADAPTER NAME>', 'OperationTimeout', 120000)
Restart WebLogic Server.
If desired, you can update jps-config.xml
to set query parameters listed in Section 7.3.1, "What is Configured?". These parameters are optional; default values are provided.
After configuring for multi-LDAP query, restart the WebLogic administration and managed servers.
Example 7-2 shows a sample jps-config.xml
file configured for single-LDAP queries in the Oracle WebLogic Server environment:
Example 7-2 Single-LDAP Configuration in Oracle WebLogic Server
<!-- JPS WLS LDAP Identity Store Service Instance --> <serviceInstance name=idstore.ldap provider=idstore.ldap.provider> <property name=idstore.config.provider value=oracle.security.jps.wls.internal.idstore. WlsLdapIdStoreConfigProvider/> <property name=CONNECTION_POOL_CLASS value=oracle.security.idm.providers.stdldap.JNDIPool/> </serviceInstance>
Example 7-3 shows a sample jps-config.xml
file configured for multi-LDAP queries in the Oracle WebLogic Server environment:
Example 7-3 Multi-LDAP Configuration in Oracle WebLogic Server
<jpsConfig xmlns="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" schema-major-version="11" schema-minor-version="1"> <serviceProviders> <serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider"> <description>LDAP-based IdentityStore Provider</description> </serviceProvider> </serviceProviders> <serviceInstances> <!-- IDstore instance connecting to multiple ldap --> <serviceInstance name="idstore.virtualize" provider="idstore.ldap.provider"> <!-- following property indicates using WLS ldap Authenticators --> <property name="idstore.config.provider" value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"/> <!-- following property enables virtualization i.e., support for multiple stores --> <property name="virtualize" value="true"/> <!-- Front end ldap properties (if not supplied, will use default values) --> <extendedProperty> <name>user.create.bases</name> <values> <value>cn=users_front,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <extendedProperty> <name>group.create.bases</name> <values> <value>cn=groups_front,dc=us,dc=example,dc=com</value> </values> </extendedProperty> </serviceInstance> </serviceInstances> <jpsContexts default="default"> <!-- the identity store uses multiple ldaps --> <jpsContext name="default"> <!-- use multiple ldap --> <serviceInstanceRef ref="idstore.virtualize"/> <!-- .....other services --> </jpsContext> </jpsContexts> </jpsConfig>
Note that:
the virtualize
property of the service instance is set to true
, enabling multi-LDAP queries.
the extendedProperty
element enables you to set front-end parameters if desired to override default values.
For more information, see "Front-End Parameters" in Section 7.3.1, "What is Configured?".
Identity Virtualization supports a "split profile," where an application makes use of attributes for a single identity that are stored on two different sources.
This feature requires additional configuration beyond that described in this chapter. For details, see Appendix J, "Adapter Configuration for Identity Virtualization".
OPSS supports the set of LDAP-based Oracle WebLogic Server authentication providers (WebLogic authenticators) for access to identity stores. If the out-of-the-box WebLogic authenticators are not applicable to your LDAP server type, you can customize a generic authenticator for this task.
This section explains how you can configure such an authenticator when the 'virtualize' flag is enabled for the identity store service.
Note the following points in this context:
When using a generic LDAP authenticator, you need to tell the Identity Store Service of the exact LDAP type so that it can find the proper LDAP plug-in. You do this by overriding the 'idstore.type
' property in jps-config.xml
.
As the 'virtualize
' flag is enabled, and the Oracle WebLogic Server domain has two or more authenticators (for example, the defaultAuthenticator and generic LDAP), you need to tell the Identity Store Service which LDAP server's 'idstore.type
' is to be overridden.
You provide this information as follows in jps-config.xml
:
<serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
<property name="idstore.config.provider"
value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"
/>
<property name="CONNECTION_POOL_CLASS"
value="oracle.security.idm.providers.stdldap.JNDIPool" />
<property value="true" name="virtualize" />
<!-- the following refer to the Generic ldap name configured on the WLS
authenticator provider, you get this name from WebLogic config.xml file or admin
console -->
<serviceInstanceRef ref="myGenericLDAPName"/>
</serviceInstance>
<!-- the following provide the overriding to the Generic ldap (e.g. AD)
-->
<!-- "myGenericLDAPName" is the name used on WLS for the generic LDAP
authenticator provider -->
<serviceInstance name="myGenericLDAPName" provider="idstore.ldap.provider">
<!-- the following overrides the 'idstore.type' property to
"ACTIVE_DIRECTORY" -->
<property name="idstore.type" value="ACTIVE_DIRECTORY" />
</serviceInstance>
If you need to override an additional LDAP provider instance, simply add another similar entry to the file.
Topics in this section include:
See the example in Section 24.3.2, "Configuring an LDAP Identity Store in Java SE Applications," for details.
To configure the identity store service to handle multiple LDAPs in third-party application servers:
Modify the jps-config.xml
file to configure service instances for each supported LDAP directory.
Restart the application server to make the changes effective.
Example 7-4 shows a sample jps-config.xml
file configured to run multi-LDAP queries for third-party application servers:
Example 7-4 Multi-LDAP Configuration in Third-Party Application Servers
<jpsConfig xmlns="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.example.com/oracleas/schema/11/jps-config-11_1.xsd" schema-major-version="11" schema-minor-version="1"> <serviceProviders> <serviceProvider type="IDENTITY_STORE" name="idstore.ldap.provider" class="oracle.security.jps.internal.idstore.ldap.LdapIdentityStoreProvider"> <description>LDAP-based IdentityStore Provider</description> </serviceProvider> </serviceProviders> <serviceInstances> <!-- instance 'idstore.oid' to represent an ldap server 'oid' --> <serviceInstance name="idstore.oid" provider="idstore.ldap.provider"> <property name="subscriber.name" value="dc=us,dc=example,dc=com"/> <property name="idstore.type" value="OID"/> <property name="security.principal.key" value="oid.ldap.credentials"/> <property name="security.principal.alias" value="JPS"/> <property name="ldap.url" value="ldap://hostname.example.com:389,ldap://hostname.example.com:389"/> <extendedProperty> <name>user.search.bases</name> <values> <value>cn=users,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <extendedProperty> <name>group.search.bases</name> <values> <value>cn=groups,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <property name="username.attr" value="uid" /> <property name="groupname.attr" value="cn" /> </serviceInstance> <!-- instance 'idstore.ad' to represent an ldap server 'ad' --> <serviceInstance name="idstore.ad" provider="idstore.ldap.provider"> <property name="subscriber.name" value="dc=us,dc=example,dc=com"/> <property name="idstore.type" value="ACTIVE_DIRECTORY"/> <property name="security.principal.key" value="msad.ldap.credentials"/> <property name="security.principal.alias" value="JPS"/> <property name="ldap.url" value="ldap://hostname.example.com:389,ldap://hostname.example.com:389"/> <extendedProperty> <name>user.search.bases</name> <values> <value>cn=users,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <extendedProperty> <name>group.search.bases</name> <values> <value>cn=groups,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <property name="username.attr" value="uid" /> <property name="groupname.attr" value="cn" /> </serviceInstance> <!-- IDStore service "idservice.virtualize" to connect to multiple ldaps ( 'oid' and 'ad') using libOVD--> <serviceInstance name="idservice.virtualize" provider="idstore.ldap.provider"> <!--following property enables virtualization i.e., support for multiple stores --> <property name="virtualize" value="true"/> <!-- backend ldap instance "idstore.oid"--> <serviceInstanceRef ref="idstore.oid"/> <!-- backend ldap instance "idstore.ad"--> <serviceInstanceRef ref="idstore.ad"/> <!-- Front end ldap properties (if not supplied, will use default values) --> <extendedProperty> <name>user.create.bases</name> <values> <value>cn=users_front,dc=us,dc=example,dc=com</value> </values> </extendedProperty> <extendedProperty> <name>group.create.bases</name> <values> <value>cn=groups_front,dc=us,dc=example,dc=com</value> </values> </extendedProperty> </serviceInstance> </serviceInstances> <jpsContexts default="default"> <!-- IdStore service connect to multiple ldaps ('oid'+'ad') through libOVD--> <jpsContext name="default"> <!-- use multiple ldaps ('oid'+'ad') through libOVD--> <serviceInstanceRef ref="idservice.virtualize"/> <!-- .....other services --> </jpsContext> </jpsContexts> </jpsConfig>
Note that:
the first service instance defines the provider for Oracle Internet Directory.
the second service instance defines the provider for Microsoft Active Directory.
the virtualize
property of the service instance is set to true
, enabling multi-LDAP queries.
the extendedProperty
elements enable you to set front-end parameters if desired to override default values.
For more information, see "Front-End Parameters" in Section 7.3.1, "What is Configured?".
In a Java SE environment, all configurations are set in the jps-config-jse.xml
file. According to your needs, you can:
Define a new identity store service instance.
Add the new service instance to the JPS context, replacing any previously defined IdentityStore instance.
Enable the virtualize flag in the identity store service; see Example 7-4.
For further information, see Section 24.3.2, "Configuring an LDAP Identity Store in Java SE Applications".
To programmatically query the LDAP identity store, you use OPSS to obtain the JPS context; this acts like a bridge to obtain the store instance. Subsequently you use the User and Role API to query the store.
Example 7-5 Querying the LDAP Identity Store Programmatically
try { //find the JPS context JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory(); JpsContext ctx = ctxFactory.getContext(); //find the JPS IdentityStore service instance //(assuming the backend is ldap type) LdapIdentityStore idstoreService = (LdapIdentityStore)ctx.getServiceInstance(IdentityStoreService.class) //get the User/Role API's Idmstore instance oracle.security.idm.IdentityStore idmIdentityStore = idstoreService.getIdmStore(); //use the User/Role API to query id store // //alternatively, instead of using IdentityStore, use the //IdentityDirectory to access LDAP oracle.igf.ids.IdentityDirectory ids = idstoreService.getIdentityStore(); // ref. chapter "Developing with the Identity Directory API" // on how to use IdentityDirectory } catch (Exception e) { e.printStackTrace() }
To see how to enable the 'virtualize
' property in the identity store service, refer to Example 7-4.
For additional information about using MBeans, see Section E.2, "Configuring OPSS Services with MBeans".
Connections between the identity store and an LDAP server can be SSL-enabled. This section explains how the connections are configured in the various scenarios. Use the following table to determine the correct procedure to use:
If virtualize flag is set to | And the User and Role API is in use | And the Identity Directory Service is in use |
---|---|---|
virtualize=false (that is, virtualize flag is not set) | Specify truststore using JSSE parameters, as explained in Section 8.3.2.
For example: -Djavax.net.ssl.trustStore=trust_store_path_name |
Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3. |
virtualize=true (that is, virtualize flag is set) | Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3. | Use the adapters.jks file as shown in Section 7.5.2 and Section 7.5.3. |
When the connection to the identity store originates at a client residing in Oracle WebLogic Server, SSL configuration is handled by Oracle WebLogic Server. For details, see Section 8.3.2.
Both the Identity Directory API and the User and Role API can operate in a multi-LDAP identity store configuration (virtualize = true).
In this scenario, you can SSL-enable the connection from the identity store to the LDAP servers.
The procedure is as follows:
Create a keystore to contain the LDAP server certificate(s) for use by the service. You will need to provide passwords for the WebLogic Admin Server and the keystore, respectively.
Create the keystore using the script $MW_HOME/oracle_common/bin/libovdconfig.sh with the -createKeystore
option:
libovdconfig.sh -host wls_host -port wls_adminserver_port -userName wls_user_name -domainPath full_path_domain_home -createKeystore
where:
host
is the Oracle WebLogic Server host
port
is the Oracle WebLogic Server Admin Server port
username
is the Oracle WebLogic Server admin user name
domainPath
is the complete path to the domain home
Export the certificate from the LDAP directory using the appropriate export command.
Note:
For more information about theexport
command, see the relevant LDAP directory's Administration guide.Import this certificate into the keystore you created in Step 1.
Import the certificate to the keystore using the keytool
command. The syntax is as follows, for a keystore named adapters.jks
:
$JAVA_HOME/bin/keytool -importcert -keystore $DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks -storepass keystore_password_used_in_libovdconfig.sh -alias alias_name -file full_path_to_LDAPCert_file -noprompt
Restart Oracle WebLogic Server.
To implement two-way SSL in a multi-LDAP identity store configuration, perform these steps:
Perform the procedure described in Section 7.5.2.
In the keystore that was created by Step 1 of Section 7.5.2, generate a new key pair, signed by a CA using the keytool -genkey
command.
The syntax is as follows:
$JAVA_HOME/bin/keytool -genkey -keystore path_location_of_adapters.jks -storepass keystore_password_used_in_libovdconfig.sh -alias alias_name -keyalg rsa -dname backend_user_DN_used_to connect_from_idstore
Export the certificate created in Step 2 to a file using the keytool -exportcert
command.
The syntax is as follows:
$JAVA_HOME/bin/keytool -exportcert
-keystore path_location_of_adapters.jks
-storepass keystore_password_used_in_libovdconfig.sh
-rfc -alias alias_name_used_in_Step2
-file cert.txt
Import the certificate into the LDAP directory's keystore using the appropriate import command.
Note:
For more information about theimpoort
command, see the relevant LDAP directory's Administration guide.