This chapter includes the following sections:
Use the listSecurityStoreInfo WLST command to determine several attributes of the security store. For information about this command, see listSecurityStoreInfo in WLST Command Reference for Infrastructure Security.
To avoid unexpected authorization failures and to manage policies effectively, note the following points:
Before deleting a user, revoke all permissions, application roles, and enterprise groups that have been granted to the user. If you fail to remove all security data referencing a deleted user, then these artifacts are left dangling and, potentially, be inadvertently inherited if another user with the same name is created at a later time.
Similar considerations apply to when a user name is changed: all policies (grants, permissions, groups) referring to old data must be updated so that authorization works as expected with the changed data.
When applied, policies use case-sensitivity in names. The best way to avoid possible authorization errors due to case in user or group names is to use the spelling of those names exactly as specified in the identity store. Oracle recommends that:
When provisioning a policy, spell the names of users and groups used in the policy exactly as they are spelled in the identity store.
When entering a user name at runtime, enter a name that matches exactly the case of a name in the identity store.
Resource type, resource, or entitlement names can contain printable characters only and they cannot start or end with a white space.
Authorization failures are not shown in the console by default. To have authorization failures (such as JpsAuth.checkPermission failures) displayed in the console, set the jps.auth.debug system variable to true.
The following sections explain how to manage policies with Fusion Middleware Control, WLST, and OES. Typical operations include:
Fusion Middleware Control allows you to manage system and application policies in a WebLogic Server domain as explained in the following sections:
Follow the instructions in this section to manage application policies withFusion Middleware Control.
Task 1, Opening the Application Policies Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Application Policies. The Application Policies page is displayed. The Policy Store Provider area is read-only and displays the provider currently used in the domain.
Task 2, Searching Application Policies
In the Search area, choose an application stripe, enter a string to match (a principal name, principal group, or application role), and click the search button. The results of the search are displayed in the table at the bottom of the page.
Task 3, Creating an Application Policy
Choose an application stripe, and click Create. The Create Application Grant page is displayed. In this page, add principals and permissions to the grant, as appropriate:
To add permissions, in the Permissions area click Add to display the Add Permission dialog.
In the Search area of that dialog, first choose Permissions or Resource Types. If you chose Permissions, then identify permissions matching a class or resource name, and determine the Permission Class and Resource Name. If you chose Resource Types, then identify the resource types matching a type name, and determine a type. Then click OK to return to the Create Application Grant page. The permission you chose is displayed in the table in the Permissions area.
To add principals, click Add in the Grantee area to display the Add Principal dialog.
In the Search area of that dialog, choose a Type, enter strings to match principal names and display names, and click the search button. The result of the query is displayed in the Searched Principals table. Then choose one or more rows from that table, and click OK to return to the Create Application Grant page. The principals you chose are displayed in the table in the Grantee area
Click OK to return to the Application Policies page. The new policy is displayed in the table at the bottom of the page.
Task 4, Creating an Application Policy Like Another One
Follow the instructions in this section to manage application roles withFusion Middleware Control.
Task 1, Opening the Application Roles Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Application Roles. The Application Roles page is displayed. The Policy Store Provider area is read-only and displays the provider currently used in the domain.
Task 2, Searching Application Roles
In the Search area, choose an application stripe, enter a string to match, and click the search button. The results of the search are displayed in the table at the bottom of the page.
Task 3, Creating an Application Role
Click Create to display the Create Application Role page.
You need not enter data in this page all at one time. For example, you could create a role by entering the role name and display name, save your data, and later on specify the members in it. Similarly, you could specify the role mapping at a later time.
In the area General:
In the Role Name text field enter the name of the role.
In the Display Name text field, optionally, enter the name to display for the role.
In the Description text field, optionally, enter a description of the role.
In the Members area, specify the users, groups, or other application roles into which the role is mapped.
Task 4, Adding Application Roles to a Role
Choose a role and click Add. The Add Principal dialog is displayed.
Choose a Type (application role, group, or user), enter a string to match principal names, and click the search button. The result of the search is displayed in the Searched Principals table. Choose one or more principals from that table.
Choose one or more principals to which you want to add the role.
Click OK to return to the Create Application Role page. The new application role is displayed in the Members table.
Task 5, Creating an Application Role Like Another One
To understand how permissions are inherited in the role hierarchy, see Permission Inheritance and the Role Hierarchy.
Follow the instructions in this section to manage system policies with Fusion Middleware Control.
Task 1, Opening the System Policies Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to System Policies. The System Policies page is displayed. The Policy Store Provider area is read-only and displays the provider currently used in the domain.
Task 2, Searching System Policies
In the Search area, choose a type, enter a string to match, and click the search button. The results of the search are displayed in the table at the bottom of the page.
Task 3, Creating a System Policy
An online WLST command is a command that requires a connection to a running server. Unless otherwise stated, commands listed in this section are online commands and operate on the security store, regardless of its type. There are a few commands that are offline which do not require a running server to operate.
Read-only commands can be performed only by users in the following WebLogic Server groups: Monitor, Operator, Configurator, or Admin. Read/write commands can be performed only by users in the following WebLogic Server groups: Admin or Configurator. All commands are available with the installation of Oracle WebLogic Server.
You can run WSLT commands in interactive or in script mode. In interactive mode, you enter the command at a command-line prompt. In script mode, you write the commands in a text file and run the script, much like the directives in a shell script.
All class names specified in commands must be fully qualified path names.
OPSS provides the following commands to administer application policies:
migrateSecurityStore. see Migrating the Security Store with migrateSecurityStore
The reassociateSecurityStore WLST command migrates the security store from a source to a target store and resets service configurations in the jps-config.xml and jps-config-jse.xml files to the target repository. This command is supported in only the interactive mode.
The source store can be a file, LDAP, or DB security store. The target store can be a new store or an existing store in some other domain (see optional join argument below). When the target is a store in some other domain, you specify whether to append the source data to the target store (see optional migrate argument below).
The version of the source store must be equal to or greater than the version of the target store. If the version of the source is later than the version of the target, then the command runs a compatibility check between the source and the target security data. If the check fails on some artifacts, then the command allows skipping the migration of incompatible artifacts by setting the skip argument to true. If this argument is not true and incompatible artifacts are detected, then the command terminates.
The command resets the bootstrap credentials (see admin and password arguments below). For an alternate way to reset bootstrap credentials, see the modifyBootStrapCredential and addBootStrapCredential commands.
Command Syntax
The command syntax varies according to the type of the target store. When the target is an LDAP store, use the following syntax (arguments are displayed in separate lines for clarity only):
reassociateSecurityStore(domain="domainName",
servertype="OID",
ldapurl="hostAndPort",
jpsroot="cnSpecification",
admin="cnSpecification",
password="passWord",
[join="trueOrfalse"] [,keyFilePath="dirLoc", keyFilePassword="password"]]
[migrate="trueOrfalse"]
[skip="trueOrfalse"])
When the target is a DB security store, use the following syntax (arguments are displayed in separate lines for clarity only):
reassociateSecurityStore(domain="domainName",
servertype="DB_ORACLE",
datasourcename="datasourceName",
jpsroot="jpsRoot",
jdbcurl="jdbcURL",
jdbcdriver="jdbcDriverClass",
dbUser="dbUserName",
dbPassword="dbPassword",
[admin="adminAccnt", password="passWord",]
[,join="trueOrfalse"
[,keyFilePath="dirLoc", keyFilePassword="password"] [,migrate="trueOrfalse" [,skip="trueOrfalse"]]])
[odbcdsn="odbcDsnSting"]
[migrate="trueOrfalse"]
[skip="trueOrfalse"])
The main points regarding the use of the join, migrate, and skip arguments are next summarized:
The migrate argument is relevant only when join is true. Otherwise it is ignored. Therefore, if migration is desired, then set both join and migrate to true.
The keyFilePath and keyFilePassword arguments are required when join and migrate are both true.
When the join and migrate arguments are both true, then if skip is true, then the migration of incompatible artifacts with the target store is skipped. If skip is false, then the command terminates when it finds any incompatible artifacts. Skipping is supported for generic credentials only.
The argument descriptions are:
domain: specifies the name of the domain where the target store is located.
admin in case of an LDAP target, specifies the administrator's user name on the target server. Use the format: cn=usrName.
In case of a DB security store, it is required only when the database has a data source protected with user and password. In this case, this argument specifies the user name that was set to protect the data source when the data source was created. That user and password must be present in the bootstrap credential store. If specified, then password must also be specified.
password specifies the password associated with the user specified in admin. It is required in case of an LDAP target.
In case of a DB security store, it is required only when the database has a protected data source. In this case, it specifies the password associated with the user specified in admin. If specified, then admin must also be specified.
ldapurl specifies the URI of the LDAP server. Use the format ldap//host:port, if you are using the default port, or ldaps://host:port, if you are using an anonymous Secure Sockets Layer (SSL) or one-way SSL. The secure port must be configured to handle the desired SSL connection mode, and must be distinct from the default (nonsecure) port.
servertype specifies the kind of the target store. Valid types are OID, DB_ORACLE.
jpsroot specifies the root node in the target LDAP repository under which all data is migrated. The format is cn=nodeName.
join specifies whether the target store is a store in some other domain. Optional. Set to true to share a target store in some other domain. Set to false otherwise. If unspecified, it defaults to false. The use of this argument allows multiple WebLogic Server domains to point to the same security store, but note that:
Joining to a security store is supported only when you create a new domain.
Merging two distinct security stores in two domains is not supported.
If join is true, then you must export the OPSS encryption keys from one domain and import them into the other domain.
Note:
To export and import encryption keys use the following procedure. For an alternate procedure, see keyFilePath argument.
Assume that Domain1 has a security store and Domain2 has reassociated to Domain1's security store with join set to true. Then:
Use the exportEncryptionKey WLST command to extract the key from Domain1 into the ewallet.p12 file. The value of the keyFilePassword argument passed must be used later when you import that key into the second domain.
Use the importEncryptionKey WLST command to import the extracted ewallet.p12 file into Domain2. The value of the keyFilePassword argument must be identical to the one used when the ewallet.p12 file was generated.
Restart Domain2's server.
For information about the export and import commands, see exportEncrytionKey and importEncryptionKey in WLST Command Reference for Infrastructure Security.
migrate is meaningful only if join is true, otherwise ignored. Specifies whether the data in the source store should be appended to the joined store. Set to true to append source data to the target store. Set to false to join to the target store without any appending source data. Optional. If unspecified, then it defaults to false.
skip is meaningful only if both join and migrate are true, otherwise it is ignored. Specifies whether to skip the migration of incompatible artifacts. Set to true to skip appending incompatible artifacts to the target store and not to terminate the command. Set to false to terminate the command upon encountering an incompatible artifact in the source store. Optional. If unspecified, it defaults to false.
datasourcename specifies the Java Naming and Directory Interface (JNDI) name of the Java Database Connectivity (JDBC) data source. The value should be identical to the value of the JNDI name data source entered when the data source was created.
keyFilePath specifies the directory where the ewallet.p12 file for the target domain is located. The content of this file is encrypted and secured by the value passed to keyFilePassword. It is required only if join is true.
If join is true, then the encryption keys must be exported from one domain and imported in the other. These tasks are carried out automatically when you use the keyFilePath and keyFilePassword arguments.
Assume that Domain1 has a security store and Domain2 reassociates to Domain1 security store with join set to true and key file arguments. Then first run the reassociateSecurityStore WLST command with the appropriate argument values, and then restart Domain2's server. For an alternate procedure to export and import encryption keys, see Note in the description of join argument.
keyFilePassword specifies the password to secure the ewallet.p12 file. Required only if join is true.
jdbcurl specifies the JDBC URL used by a Java SE application to connect to the database. Applies only to Java SE applications. Required. Must be used with the jdbcdriver, dbUser, and dbPassword. arguments.
jdbcdriver specifies the class of the JDBC driver used to connect to the database. Required. Must be used with the jdbcurl argument.
dbUser specifies the database user (in the credential store) to add to the bootstrap credentials. Required. Must be used with the jdbcurl argument.
dbPassword specifies the password of the user specified by dbUser. Required. Must be used with the jdbcurl argument.
odbcdsn specifies the Open Database Connectivity (ODBC) data source name used by the C Credential Store Framework API. Applies only to C programs.
Reassociation Examples
The following example illustrates how to reassociate to a DB security store:
reassociateSecurityStore(domain="targetDomain", servertype="DB_ORACLE", jpsroot="cn=jpsroot", datasourcename="jdbc/opssds", jdbcurl="jdbc:oracle:thin:@myhost.oracle.com:5555:testdb", dbUser="test_opss", dbPassword="mypass", jdbcdriver="oracle.jdbc.xa.client.OracleXADataSource")
To share the security store in otherDomain without migrating the contents of the source security store:
reassociateSecurityStore(domain="otherDomain", servertype="DB_ORACLE", jpsroot="cn=jpsroot", datasourcename="jdbc/opssds", jdbcurl="jdbc:oracle:thin:@myhost.oracle.com:5555:testdb",dbUser="test_opss", dbPassword="mypass", jdbcdriver="oracle.jdbc.xa.client.OracleXADataSource", join="true", keyFilePath="/tmp/myFileDirectory", keyFilePassword="password")
To share the security store in otherDomain and to migrate the contents of the source security store to the target DB security store skipping over incompatible artifacts:
reassociateSecurityStore(domain="otherDomain", servertype="DB_ORACLE", jpsroot="cn=jpsroot", datasourcename="jdbc/opssds", jdbcurl="jdbc:oracle:thin:@myhost.oracle.com:5555:testdb",dbUser="test_opss", dbPassword="mypass", jdbcdriver="oracle.jdbc.xa.client.OracleXADataSource", join="true", migrate="true", skip="true", keyFilePath="/tmp/myFileDirectory", keyFilePassword="password")
This topic applies to LDAP and DB security stores only. In case of a file store, the cache is updated after a few seconds.
OPSS optimizes the authorization process by caching security artifacts. When a security artifact is modified, the change becomes effective at different times depending on where the tool used to modified the artifact and the application are running:
If both the application and the tool are running on the same host and in the same domain, then the change becomes effective immediately.
Otherwise, if the application and the tool are running on different hosts or in different domains, then the change becomes effective after the store cache is refreshed. The frequency of the cache refresh is determined by the value of the oracle.security.jps.ldap.policystore.refresh.interval property. The default value is 10 minutes.
Within a domain, any changes introduced with WLST or Fusion Middleware Control are first accounted on the Administration Server only. Those changes are pushed to all Managed Servers in the domain only when the server is restarted.
The following use case illustrates the authorization behavior in scenarios when (from a different domain or host) OES is used to modify security data, and the property oracle.security.jps.ldap.policystore.refresh.interval is set to 10 minutes.
This case assumes that:
A user is member of an enterprise role.
That enterprise role is included as a member of an application role.
The application role is granted a permission that governs some application functionality.
Consider a scenario where:
A user logs in to the application.
The user accesses the functionality secured by the application role.
From another host (or domain), the enterprise role is removed from the application role.
Then consider the following actions and outcomes:
The user logs out from the application, and immediately logs back in. The user can still access the functionality secured by the application role, because the policy cache has not yet been refreshed with the change introduced in step 3.
The user logs out from the application, and logs back in after 10 minutes. The user is not able to access the functionality secured by the application role, because the policy cache has been refreshed with the change introduced in step 3.
The user does not log out and remains able to access the functionality secured by the application role for 10 minutes, because the policy cache has not yet been refreshed with the change introduced in step 3.
The user does not log out, waits more than 10 minutes, and then attempts to access the functionality secured by the application role: the access is denied, because the policy cache has been refreshed with the change introduced in step 3.
Several commands require that you specify the principal name and class for a role involved in the operation, such as the following which adds a principal to the myAppRole role in the myApp application stripe:
grantAppRole.py -appStripe myApp
-appRoleName myAppRole
-principalClass myPrincipalClass
-principalName myPrincipal
When the principal refers to the authenticated role or the anonymous role, the principal names and principal classes are fixed and must be one of the following name-class pairs:
Authenticated role
authenticated-role
oracle.security.jps.internal.core.principals.JpsAuthenticatedRoleImpl
Anonymous role
anonymous-role
oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl
The following WLST commands require principal name and class specification:
grantAppRole
revokeAppRole
grantPermission
revokePermission
listPermissions
Several commands require that you specify an application stripe. If the application does not have a version, then the application stripe defaults to the application name. Otherwise, if the application has a version, then the application name and the application stripe are not identical.
For example, the name of the myApp application with version 1 is myApp(v1.0), but the application stripe name is myApp#v1.0. More generally, an application with name appName(vers) gets assigned the application stripe appName#vers. Pass a string with this last pattern as the application stripe name:
>listAppRoles myApp#v1.0
The following WLST commands require stripe specification:
createAppRole
deleteAppRole
grantAppRole
revokeAppRole
listAppRoles
listAppRoleMembers
grantPermission
revokePermission
listPermissions
deleteAppPolicies