6 Configuring Existing WebLogic Domains
Using WLST Online to Update an Existing WebLogic Domain
Because WLST online interacts with an active WebLogic domain, all online changes to a domain are controlled by the change management process, which loosely resembles a database transaction.
For more information on making and managing configuration changes, see Configuration Change Management Process in Understanding Domain Configuration for Oracle WebLogic Server.
Table 6-1 describes the steps for using WLST online to update an existing WebLogic domain.
Table 6-1 Steps for Updating an Existing WebLogic Domain (Online)
To... | Use this command... | See this section in WLST Command Reference for WebLogic Server: |
---|---|---|
Access the edit MBean hierarchy |
This command places WLST at the root of the edit MBean hierarchy, which is the editable |
|
Obtain a lock on the current configuration To indicate that configuration changes are in process, an exclamation point (!) appears at the end of the WLST command prompt. |
|
|
Modify the WebLogic domain |
Browsing and online editing commands |
|
(Optional) Validate your edits |
|
|
Save your changes |
|
|
Distribute your changes to the working configuration MBeans on all servers in the WebLogic domain |
|
|
Release your lock on the configuration |
|
|
(Optional) Determine if a change you made to an MBean attribute requires you to re-start servers You can use the showChanges command to determine the changes you made to the configuration. |
|
The WLST online script in Example 6-1 connects WLST to an Administration Server, initiates an edit session that creates a Managed Server, saves and activates the change, initiates another edit session, creates a startup class, and targets it to the newly created server.
Example 6-1 Creating a Managed Server
connect("username","password") edit() startEdit() svr = cmo.createServer("managedServer") svr.setListenPort(8001) svr.setListenAddress("address") save() activate(block="true") startEdit() sc = cmo.createStartupClass("my-startupClass") sc.setClassName("com.bea.foo.bar") sc.setArguments("foo bar") # get the server mbean to target it tBean = getMBean("Servers/managedServer") if tBean != None: print "Found our target" sc.addTarget(tBean) save() activate(block="true") disconnect() exit()
The interactive edit session in Example 6-2 changes an Administration Server running in development mode to production mode, and then to secured production mode. Note that your domain must be in production mode to enable secured production mode.
Example 6-2 Changing to Production Mode or Secured Production Mode
wls:/offline> connect('username','password') wls:/mydomain/serverConfig> edit() wls:/mydomain/edit> startEdit() Starting an edit session ... Started edit session, please be sure to save and activate your changes once you are done. wls:/mydomain/edit !> cmo.setProductionModeEnabled(true) # Optionally enable secured production mode wls:/mydomain/edit !> cd('SecurityConfiguration/mydomain/SecureMode/mydomain') cmo.setSecureModeEnabled(true) wls:/mydomain/edit !> activate() Activating all your changes, this may take a while ... The edit lock associated with this edit session is released once the activation is completed. The following non-dynamic attribute(s) have been changed on MBeans that require server re-start: MBean Changed : com.bea:Name=AdminServer,Type=WebServerLog,Server=AdminServer, WebServer=AdminServer Attributes changed : RotateLogOnStartup MBean Changed : com.bea:Name=AdminServer,Type=WebServerLog,Server=AdminServer, WebServer=AdminServer Attributes changed : RotateLogOnStartup MBean Changed : com.bea:Name=Domain1,Type=Log Attributes changed : RotateLogOnStartup Activation completed wls:/mydomain/edit> exit()
Note:
When using WLST to change the Administration Server from development to production mode, the Java -Xverify
option (if used) is not changed from none
to all
and must be changed manually to all
to ensure that all classes are verified. In addition, it does not prevent an existing boot.properties
file from being used when starting the servers.
Tracking Configuration Changes
For all changes that are initiated by WLST, you can use the showChanges
command, which displays all the changes that you made to the current configuration from the start of the WLST edit session, including any MBean operations that were implicitly performed by the server. See Example 6-3.
Example 6-3 Displaying Changes
connect("username","password") wls:/mydomain/serverConfig> edit() wls:/mydomain/edit> startEdit() Starting an edit session ... Started edit session, please be sure to save and activate your changes once you are done. wls:/mydomain/edit !> cmo.createServer('managed2') [MBeanServerInvocationHandler]mydomain:Name=managed2,Type=Server wls:/mydomain/edit !> cd('Servers/managed2') wls:/mydomain/edit/Servers/managed2 !> cmo.setListenPort(7702) wls:/mydomain/edit/Servers/managed2 !> cmo.setListenAddress("localhost") wls:/mydomain/edit/Servers/managed2 !> showChanges() Changes that are in memory and saved to disc but not yet activated are: All changes that are made but not yet activated are: MBean Changed : com.bea:Name=Len,Type=Domain Operation Invoked : create Attribute Modified : Servers Attributes Old Value : null Attributes New Value : managed2 Server Restart Required : false MBean Changed : com.bea:Name=managed2,Type=Server Operation Invoked : modify Attribute Modified : ListenPort Attributes Old Value : null Attributes New Value : 7702 Server Restart Required : false wls:/mydomain/edit/Servers/managed2 !> save() Saving all your changes ... Saved all your changes successfully. wls:/mydomain/edit !> activate() Activating all your changes, this may take a while ... The edit lock associated with this edit session is released once the activation is completed. Activation completed wls:/mydomain/edit/Servers/managed2>
The WLST online script in Example 6-4 connects WLST to a running server instance as an administrator, gets the activation task, and prints the user and the status of the task. It also prints all the changes that took place.
The getActivationTask
function provides information about the activation request and returns the latest ActivationTaskMBean
which reflects the state of changes that a user is currently making or made recently in the current WLST session. You invoke the methods that this interface provides to get information about the latest activation task in progress or just completed. For detailed information, see ActivationTaskMBean in the MBean Reference for Oracle WebLogic Server.
Example 6-4 Checking the Activation Task
at = getActivationTask() changes = at.getChanges() newstate = at.getState() print "The user for this Task is "+at.getUser()+ "and the state is:" print newstate print "The changes are:" print changes
Undoing or Canceling Changes
WLST offers two commands to undo or cancel changes:
-
The
undo
command reverts all unsaved or unactivated edits.You specify whether to revert all unactivated edits (including those that have been saved to disk), or all edits made since the last
save
operation. See undo in WebLogic Scripting Tool Command Reference. -
The
cancelEdit
command releases the edit lock and discards all unsaved changes. See cancelEdit in WLST Command Reference for WebLogic Server.
Additional Operations and Attributes for Change Management
The standard change-management commands described in the previous section are convenience commands for invoking operations in the ConfigurationManagerMBean
. In addition to these operations, the ConfigurationManagerMBean
contains attributes and operations that describe edit sessions. For detailed information, see ConfigurationManagerMBean in the MBean Reference for Oracle WebLogic
Server.
To access this MBean, use the WLST getConfigManager
command. See getConfigManager in WLST Command Reference for WebLogic
Server.
The WLST online script in Example 6-5 connects WLST to a server instance as an administrator, checks if the current editor making changes is not the administrator, then cancels the configuration edits. The script also purges all the completed activation tasks. You can use this script to make a fresh start to edit changes, but you should verify that the changes made by other editors are not needed.
Example 6-5 Using the Configuration Manager
connect('adminusername','adminpassword') user = cmgr.getCurrentEditor() if user != "weblogic": cmgr.undo() cmgr.cancelEdit() cmgr.purgeCompletedActivationTasks()
Using WLST Offline to Update an Existing WebLogic Domain
You can update an existing WebLogic domain using WLST offline.
Note:
Oracle recommends that you do not use WLST offline to manage the configuration of an active WebLogic domain. Offline edits are ignored by running servers and can be overwritten by JMX clients such as WLST online or the WebLogic Server Administration Console.
The commands in the following table are used to read an existing domain, update the domain as needed, and close the domain in offline mode. During this process, if a connection factory is targeted to a subdeployment, after running the updateDomain
command and restarting the domain, default-targeting-enabled
is set to true
for the connection factory.
To update an existing WebLogic domain using WLST offline, perform the steps described in Table 6-2.
Table 6-2 Steps for Updating an Existing WebLogic Domain (Offline)
To... | Use this command... | See ... |
---|---|---|
Open an existing WebLogic domain for update |
|
readDomain in WLST Command Reference for WebLogic Server |
Extend the current WebLogic domain (optional) |
|
selectTemplate and loadTemplates in WLST Command Reference for WebLogic Server |
Modify the WebLogic domain (optional) |
Browsing and editing commands |
Browsing Information About the Configuration Hierarchy (Offline) |
Save the WebLogic domain |
|
updateDomain in WLST Command Reference for WebLogic Server |
Close the WebLogic domain |
|
closeDomain in WLST Command Reference for WebLogic Server |
Managing Security Data (WLST Online)
You can manage security data, such as authentication providers, using WLST online.
In the WebLogic Security Service, an Authentication provider is the software component that proves the identity of users or system processes. An Authentication provider also remembers, transports, and makes that identity information available to various components of a system when needed.
A security realm can use different types of Authentication providers to manage different sets of users and groups. (See Authentication Providers in Developing Security Providers for Oracle WebLogic Server. You can use WLST to invoke operations on the following types of Authentication providers:
-
The default WebLogic Server Authentication provider,
AuthenticatorMBean
. By default, all security realms use this Authentication provider to manage users and groups. -
Custom Authentication providers that extend
weblogic.security.spi.AuthenticationProvider
and extend the optional Authentication SSPI MBeans. See SSPI MBean Quick Reference in Developing Security Providers for Oracle WebLogic Server
For information about additional tasks that the AuthenticationProvider
MBeans support, see AuthenticationProviderMBean in the MBean Reference for Oracle WebLogic
Server.
Note:
It is possible to use WLST offline to edit certain types of security data, such as authentication providers. However, we recommend that you use WLST online whenever possible and only use WLST offline to edit security data if required by constraints in your environment .
The following sections describe basic tasks for managing users and groups using WLST.
Determining If You Need to Access the Edit Hierarchy
If you are using WLST to change the configuration of a security MBean, you must access the edit hierarchy and start an edit session. For example, if you change the value of the LockoutThreshold
attribute in UserLockoutManagerMBean
, you must be in the edit hierarchy.
If you invoke security provider operations to add, modify, or remove data in a security provider data store, WLST does not allow you to be in the edit hierarchy. Instead, invoke these commands from the serverConfig
or domainConfig
hierarchy. For example, you cannot invoke the createUser
operation in an AuthenticatorMBean
MBean from the edit hierarchy. WLST enforces this restriction to prevent the possibility of incompatible changes. For example, an edit session could contain an unactivated change that removes a security feature and will invalidate modifications to the provider's data.
Creating a User
To create a user, invoke the UserEditorMBean.createUser
method, which is extended by the security realm's AuthenticationProvider
MBean. See the createUser method of the UserEditorMBean
in the MBean Reference for Oracle WebLogic
Server.
The method requires three input parameters. The password must be at least eight characters, with one special character or numeric character.
username password user-description
WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig
or domainConfig
hierarchy.
The following WLST online script invokes createUser
on the default authentication provider.
Example 6-6 Creating a User
from weblogic.management.security.authentication import UserEditorMBean
print "Creating a user ..."
atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthentication
Provider("DefaultAuthenticator")
atnr.createUser('new_user','adminpassword','new_admin')
print "Created user successfully"
Adding a User to a Group
To add a user to a group, invoke the GroupEditorMBean.addMemberToGroup
method, which is extended by the security realm's AuthenticationProvider
MBean. See the addMemberToGroup method in the MBean Reference for Oracle WebLogic
Server.
The method requires two input parameters:
groupname username
WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig
or domainConfig
hierarchy.
The following WLST online script invokes addMemberToGroup
on the default Authentication Provider. For information on how to run this script, see Invoking WLST.
Example 6-7 Adding a User to a Group
from weblogic.management.security.authentication import GroupEditorMBean print "Adding a user ..." atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator") atnr.addMemberToGroup('Administrators','my_user') print "Done adding a user"
Verifying Whether a User Is a Member of a Group
To verify whether a user is a member of a group, invoke the GroupEditorMBean.isMember
method, which is extended by the security realm's AuthenticationProvider
MBean. See the isMember method in the MBean Reference for Oracle WebLogic
Server.
The method requires three input parameters:
groupname username boolean
where boolean
specifies whether the command searches within child groups. If you specify true
, the command returns true
if the member belongs to the group that you specify or to any of the groups contained within that group.
WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig
or domainConfig
hierarchy.
The following WLST online script invokes isMember
on the default Authentication Provider. For information on how to run this script, see Invoking WLST.
Example 6-8 Verifying Whether a User is a Member of a Group
from weblogic.management.security.authentication import GroupEditorMBean user = "my_user" print "Checking if "+user+ " is a Member of a group ... " atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator") if atnr.isMember('Administrators',user,true) == 0: print user+ " is not member of Administrators" else: print user+ " is a member of Administrators"
Listing Groups to Which a User Belongs
To see a list of groups that contain a user or a group, invoke the MemberGroupListerMBean.listMemberGroups
method, which is extended by the security realm's AuthenticationProvider
MBean. See the listMemberGroups method of the MemberGroupListerMBean in the MBean Reference for Oracle WebLogic
Server.
The method requires one input parameter:
memberUserOrGroupName
where memberUserOrGroupName
specifies the name of an existing user or a group.
WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig
or domainConfig
hierarchy.
The following WLST online script invokes listMemberGroups
on the default Authentication provider. For information on how to run this script, see Invoking WLST.
Example 6-9 Listing Groups to Which a User Belongs
from weblogic.management.security.authentication import MemberGroupListerMBean print "Listing the member groups ..." atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider ("DefaultAuthenticator") x = atnr.listMemberGroups('my_user') print x
The method returns a cursor value (for example, Cursor_16), which refers to a list of names. The NameLister.haveCurrent
, getCurrentName
, and advance
operations iterate through the returned list and retrieve the name to which the current cursor position refers. See NameListerMBean in the MBean Reference for Oracle WebLogic
Server.
Listing Users and Groups in a Security Realm
To see a list of user or group names, you invoke a series of methods, all of which are available through the AuthenticationProvider
interface:
-
The
GroupReaderMBean.listGroups
andUserReaderMBean.listUsers
methods take two input parameters: a pattern of user or group names to search for, and the maximum number of names that you want to retrieve.Because a security realm can contain thousands (or more) of user and group names that match the pattern, the methods return a cursor, which refers to a list of names.
See the listGroups operation in the GroupReaderMBean and the listUsers operation in the UserReaderMBean in the MBean Reference for Oracle WebLogic Server.
-
The
NameLister
.haveCurrent
,getCurrentName
, andadvance
operations iterate through the returned list and retrieve the name to which the current cursor position refers. See NameListerMBean in the MBean Reference for Oracle WebLogic Server. -
The
NameLister
.close
operation releases any server-side resources that are held on behalf of the list.
WLST cannot invoke these commands from the edit hierarchy, but it can invoke them from the serverConfig
or domainConfig
hierarchy.
The WLST online script in Example 6-10 lists all the users in a realm and the groups to which they belong. For information on how to run this script, see Invoking WLST.
Example 6-10 Listing Users and Groups
from weblogic.management.security.authentication import UserReaderMBean from weblogic.management.security.authentication import GroupReaderMBean realm=cmo.getSecurityConfiguration().getDefaultRealm() atns = realm.getAuthenticationProviders() for i in atns: if isinstance(i,UserReaderMBean): userReader = i cursor = i.listUsers("*",0) print 'Users in realm '+realm.getName()+' are: ' while userReader.haveCurrent(cursor): print userReader.getCurrentName(cursor) userReader.advance(cursor) userReader.close(cursor) for i in atns: if isinstance(i,GroupReaderMBean): groupReader = i cursor = i.listGroups("*",0) print 'Groups in realm are: ' while groupReader.haveCurrent(cursor): print groupReader.getCurrentName(cursor) groupReader.advance(cursor) groupReader.close(cursor)
Changing a Password
To change a user's password, invoke the UserPasswordEditorMBean.changeUserPassword
method, which is extended by the security realm's AuthenticationProvider
MBean. See the changeUserPassword method in the MBean Reference for Oracle WebLogic
Server.
WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig
or domainConfig
hierarchy.
The following WLST online script invokes changeUserPassword
on the default Authentication Provider. For information on how to run this script, see Invoking WLST.
Example 6-11 Changing a Password
from weblogic.management.security.authentication import UserPasswordEditorMBean print "Changing password ..." atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator") atnr.changeUserPassword('my_user','my_password','new_password') print "Changed password successfully"
Protecting User Accounts in a Security Realm
The UserLockoutManagerMBean
provides a set of attributes to protect user accounts from intruders. By default, these attributes are set for maximum protection. You can decrease the level of protection for user accounts. For example, you can set whether or not lockout is enabled, increase the time period in which invalid login attempts are made before locking the user account, or change the amount of time a user account is locked.
The UserLockoutManagerRuntimeMBean
provides a set of attributes for collecting lockout statistics, and operations for managing user lockouts. For example, you can get the number of users currently locked out, get the number of invalid login attempts since the server was started, or clear the lockout on a user account.
For more information about lockout configuration, see the UserLockoutManagerMBean interface in the MBean Reference for Oracle WebLogic Server. For information about collecting lockout statistics and performing lockout operations, see the UserLockoutManagerRuntimeMBean interface in the MBean Reference for Oracle WebLogic Server
Note that because these tasks edit MBean attributes, WLST must connect to the Administration Server, navigate to the edit hierarchy, and start an edit session.
The following tasks provide examples for invoking
UserLockoutManagerRuntimeMBean
methods:
Set Consecutive Invalid Login Attempts
The following WLST online script sets the number of consecutive invalid login attempts before a user account is locked out. For information on how to run this script, see Invoking WLST.
Example 6-12 Setting Consecutive Invalid Login Attempts
from weblogic.management.security.authentication import UserLockoutManagerMBean edit() startEdit() #You have two choices for getting a user lockout manager to configure # 1 - to configure the default realm's UserLockoutManager: ulm=cmo.getSecurityConfiguration().getDefaultRealm().getUserLockoutManager() # 2 - to configure another realm's UserLockoutManager: #ulm=cmo.getSecurityConfiguration().lookupRealm("anotherRealm").getUserLockoutManager() ulm.setLockoutThreshold(3) save() activate()
Unlock a User Account
The following WLST online script unlocks a user account. For information on how to run this script, see Invoking WLST.
Example 6-13 Unlocking a User Account
from weblogic.management.runtime import UserLockoutManagerRuntimeMBean serverRuntime() ulm=cmo.getServerSecurityRuntime().getDefaultRealmRuntime().getUserLockoutManagerRuntime() #note1 : You can only manage user lockouts for the default realm starting from #when the server was booted (versus other non-active realms). #note2 : If the default realm's user lockout manager's LockoutEnabled attribute #is false, then the user lockout manager's runtime MBean will be null. #That is, you can only manage user lockouts in the default realm if its user #lockout manager is enabled. if ulm != None: ulm.clearLockout("myuser")
Configuring Additional LDAP Authentication Providers
In some cases, such as when installing some Oracle Fusion Middleware products, you must add an additional external LDAP authentication providers to the WebLogic Server security providers. This can be done either by using the WebLogic Server Administration Console (see Configure Authentication and Identity Assertion Providers) or by using WLST.
Example 6-14 shows how to use WLST to add an Oracle Internet Directory (OID) authentication provider. To add other types of LDAP authentication providers, substitute the appropriate class type in the createAuthenticationProvider
command, as shown in Table 6-3.
Note:
For important information about switching LDAP authentication providers if the corresponding LDAP server will contain the user or users who start the domain, see Requirements for Using an LDAP Authentication Provider in Administering Security for Oracle WebLogic Server.
Example 6-14 Adding an Authentication Provider
connect ('adminUser','adminPassword','t3://'+adminServerHost+':'+adminServerPort) edit() startEdit() cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm') # In the following command, substitute the appropriate class type cmo.createAuthenticationProvider(LDAPProviderName, 'weblogic.security.providers.authentication.OracleInternetDirectoryAuthenticator') cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm/AuthenticationProviders /'+LDAPProviderName) cmo.setControlFlag('SUFFICIENT') cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm/ AuthenticationProviders/'+LDAPProviderName) cmo.setHost(LDAPHost) cmo.setPort(LDAPPort) cmo.setPrincipal(LDAPAdmin) set("Credential",LDAPAdminPassword) cmo.setGroupBaseDN(LDAPGroupBase) cmo.setUserBaseDN(LDAPUserBase) cmo.setUserNameAttribute(usernameattribute) cmo.setUserObjectClass('inetOrgPerson') cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm/AuthenticationProviders /DefaultAuthenticator') cmo.setControlFlag('SUFFICIENT') cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm') set('AuthenticationProviders',jarray.array([ObjectName('Security:Name=myrealm' +LDAPProviderName), ObjectName('Security:Name=myrealmDefaultAuthenticator'), ObjectName('Security:Name=myrealmDefaultIdentityAsserter')], ObjectName)) activate()
Table 6-3 lists the class types to specify for each type of Authentication Provider
Table 6-3 Class Types for External LDAP Authentication Providers
Provider | Class Type |
---|---|
Oracle Internet Directory |
weblogic.security.providers.authentication.OracleInternetDirectoryAuthenticator |
Oracle Virtual Directory |
weblogic.security.providers.authentication.OracleVirtualDirectoryAuthenticator |
Microsoft AD |
weblogic.security.providers.authentication.ActiveDirectoryAuthenticator |
OpenLDAP |
weblogic.security.providers.authentication.OpenLDAPAuthenticator |
eDirectory |
weblogic.security.providers.authentication.NovellAuthenticator |
SunOne LDAP |
weblogic.security.providers.authentication.IPlanetAuthenticator |
Deploying Applications
The process for deploying applications varies depending on whether you use WLST offline or WLST online.
The following topics describe the process:
Using WLST Online to Deploy Applications
When WLST is connected to a domain's Administration Server, use the deploy
command to deploy applications. (See deploy in WLST Command Reference for WebLogic
Server.)
The command in Example 6-15 deploys a sample application from the WebLogic Server ExamplesServer domain.
Example 6-15 Deploying Applications
# Deploying Applications deploy("examplesWebApp","C:/Oracle/Middleware/wlserver/samples/server/examples/build/examplesWebApp")
Note:
Please note the following when using WLST online to deploy applications:
-
Deployment operations must be performed through the Administration Server. Your WLST client must connect to the Administration Server to invoke deployment commands.
-
You do not need to be in an edit session to deploy applications.
For more information about using WLST for deploying applications, see Deployment Tools in Deploying Applications to Oracle WebLogic Server.
Using WLST Offline to Deploy Applications
Table 6-4 describes the steps for using WLST offline to deploy applications in an existing domain.
Table 6-4 Steps for Deploying Applications (Offline)
To... | Use this command... | See ... |
---|---|---|
Use the Template Builder to create an application template. |
not applicable |
Creating an Extension Template Using the Domain Template Builder in Creating Domain Templates Using the Domain Template Builder |
Open an existing WebLogic domain or template |
|
readDomain and readTemplate in WLST Command Reference for WebLogic ServerWebLogic Scripting Tool Command Reference |
Add an extension template to the WebLogic domain |
|
selectTemplate and loadTemplates in WLST Command Reference for WebLogic Server |
Save the WebLogic domain |
|
updateDomain in WLST Command Reference for WebLogic Server |
Close the WebLogic domain |
|
closeDomain in WLST Command Reference for WebLogic Server |
For an example of using the addTemplate
command, see the following sample WLST script, where WL_HOME
refers to the top-level installation directory for WebLogic Server:
WL_HOME
\common\templates\scripts\wlst\clusterMedRecDomain.py