This chapter describes how to use the OPSS identity store service. The identity store service enables querying for user and role (group) information.
This chapter includes the following sections:
See Also:
"About the Identity Directory Service" in Developer's Guide for Identity Governance Framework.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. For details about this feature, known as identity virtualization, see Section 8.3, "Configuring the Identity Store Service".
Figure 8-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 is supported in the following platform:
Oracle WebLogic Server
The identity store service is available in a stand-alone Java SE environment.
For more information, see Section 8.3.6, "Defining Configuration in Java SE Environments".
Before using the identity store service, you must 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"/>
Note:
When the virtualize flag is set to true, do not setuser.login.attr
and username.attr
properties.For details, see Section 9.7.2, "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 want to overwrite existing values.
Table 8-1 shows the global parameters and their default values, if applicable.
Table 8-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. |
See Also:
Section F.2.5, "Generic OID Properties"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 configuring 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 8-2 which displays a fragment of the jps-config.xml
file with a single LDAP service instance.
virtualize
PropertyIn 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 8-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.
To configure service for multiple LDAP 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:
Create a py
script file to connect to the administration server in the domain of interest. You must 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:
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 8.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 8-2 shows a sample jps-config.xml
file configured for single-LDAP queries in the Oracle WebLogic Server environment:
Example 8-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 8-3 shows a sample jps-config.xml
file configured for multi-LDAP queries in the Oracle WebLogic Server environment:
Example 8-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 that is, 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 8.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 I, "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 must 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 must 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 must override an additional LDAP provider instance, simply add another similar entry to the file.
Topics in this section include:
See the example in Section 25.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 8-4 shows a sample jps-config.xml
file configured to run multi-LDAP queries for third-party application servers:
Example 8-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 that is, 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 8.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 8-4.
For further information, see Section 25.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 8-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 8-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. Both the Identity Directory API and the User and Role API can operate in a multi-LDAP identity store configuration (virtualize = true
, which is the default setting). This section explains how to SSL-enable the connection from the identity store to the LDAP servers in virtualized environment.
This section contains the following topics:
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 9.2.2.
When using multi-LDAP SSL with the Keystore Service, the store certificates are stored centrally across the domain. In the following scenarios, you configure SSL communication from the identity store to the LDAP servers using Keystore Service WLST commands. For more information about the Keystore Service and WLST commands, see Chapter 12.
For more information about configuring SSL with a JKS-based key store, see Section 8.5.3.
This section contains the following procedures:
Configuring One-way SSL in a Multi-LDAP Scenario with Keystore Service
Configuring Two-way SSL in a Multi-LDAP Scenario with Keystore Service
To enable one-way SSL communication in a multi-LDAP identity store configuration:
Export the store certificate from the LDAP directory using the appropriate export command.
Use the importKeyStoreCertificate
command to import the store certificate from the external LDAP server into the shared domain-wide truststore. For example:
svc.importKeyStoreCertificate(appStripe='system', name='trust', password='', alias='alias', keypassword='', type='TrustedCertificate',filepath='absolute _file_path')
where appStripe='system'name='trust'
is the domain truststore.
Restart Oracle WebLogic Server.
To enable two-way SSL communication in a multi-LDAP identity store configuration:
Export the store certificate from the LDAP directory using the appropriate export command.
Use the importKeyStoreCertificate
command to import the certificate from external LDAP server into the shared domain wide truststore. For example:
svc.importKeyStoreCertificate(appStripe='system', name='trust', password='', alias='alias', keypassword='', type='TrustedCertificate',filepath='absolute _file_path')
where appStripe='system'name='trust'
is the domain truststore.
Create the virtualized keystore in the Keystore Service using createKeyStore
command with appStripe='libovd', name='adapters'
. For example:
svc.createKeyStore(appStripe='libovd',name='adapters',password='',permission=true)
Run the generateKeyPair
command to generate a new key pair signed by a CA. For example:
svc.generateKeyPair(appStripe='libovd',name='adapters',password='',dn='cn=directory manager', keysize='1024',alias='alias',keypassword='')
Export this certificate to a file using the exportKeyStoreCertificate
command. For example:
svc.exportKeyStoreCertificate(appStripe='libovd',name='adapters',password='',alias='key1', type='Certificate', filepath='/tmp/cert.txt')
Import the certificate generated in previous step to the backend LDAP server.
Change "property name="enabled" value="true""
to be "KSSKeyManager
" in the provider.os_xml file under DOMAIN_HOME/config/fmwconfig/ovd/default directory.
Restart Oracle WebLogic Server.
The following procedure explains how to switch an SSL configuration in an LibOVD adapter using JKS to an SSL configuration using KSS.
To switch to a KSS LibOVD:
Import the backend LDAP certificates from existing LibOVD JKS store to the domain truststore using the command importKeyStore
, as illustrated in the following sample:
importKeyStore(appStripe='system', name='trust', password='welcome1', aliases='alias_names_from_JKS', keypasswords='',type='JKS', permission=true, filepath='DOMAIN_HOME/config/fmwconfig/ovd/<context_ name>/keystores/adapters.jks')
Open the file DOMAIN_HOME/config/fmwconfig/ovd/<context_name>/provider.os_xml
and make the following changes so that to enable KSS:
Look for "provider name="KSSTrustManager" and change "enabled" to "true".
Look for ”provider name="FileKeyManager" and change "enabled" to "false".
Look for ”provider name="FileTrustManager" and change "enabled" to "false".
If previously you were using 2-way SSL, then perform the following steps:
Create the LibOVD keystore in KSS using createKeyStore
command, as illustrated in the following sample:
createKeyStore(appStripe='libovd',name='adapters',password='myPass',permission=true)
Import the previously generated key pair from adapters.jks
to the LibOVD keystore using the command importKeyStore
, as illustrated in the following sample:
importKeyStore(appStripe='libovd', name='adapters', password='myPassw', aliases='alias_names_from_JKS', keypasswords='',type='JKS', permission=true, filepath='DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks')
Change "enabled" value to "true" for "KSSKeyManager" in Open the file DOMAIN_HOME/config/fmwconfig/ovd/<context_name>/provider.os_xml
, look for KSSKeyManager, and replace "enabled" for "true".
Restart the WebLogic Server.
When using multi-LDAP SSL with a JKS-based key store, the store certificates are maintained in multiple locations. For example, in the WebLogic Server truststore when the WLS authenticator is configured and in the adapters.jks file.
Use Table 8-2 to determine the correct procedure to use to configure SSL when using a JKS-based key store.
Table 8-2 SSL With JKS-Based Key Store
Virtualize Flag | Using the User and Role API | Using the Identity Directory Service API |
---|---|---|
|
Specify truststore using JSSE parameters, as explained in Section 9.2.2. For example: -Djavax.net.ssl.trustStore=trust_store_path_name |
Use the adapters.jks file as shown in Section 8.5.3.1 and Section 8.5.3.2. |
|
Use the adapters.jks file as shown in Section 8.5.3.1 and Section 8.5.3.2. |
Use the adapters.jks file as shown in Section 8.5.3.1 and Section 8.5.3.2. |
To enable one-way SSL communication in a multi-LDAP identity store configuration:
Note:
ORACLE_HOME must be set to oracle_common directory before running libovdconfig.sh script.Create a keystore to contain the LDAP server certificate(s) for use by the service. You will must 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.
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 enable two-way SSL in a multi-LDAP identity store configuration:
Perform the procedure described in Section 8.5.3.1.
In the keystore that was created by Step 1 of Section 8.5.3.1, generate a new key pair, signed by a CA.
Export this certificate to a file.
Import the certificate into the server's keystore.