Multiple security domains
The WebSphere Security Domains (WSD) provide the flexibility to use different security configurations in WebSphere Application Server. The WSD is also referred to as multiple security domains, or simply, security domains. We can configure different security attributes, such as the UserRegistry, for different applications.
Multiple security domain support was introduced in WAS v7. We can create different security configurations and assign them to different applications in WebSphere Application Server processes. By creating multiple security domains, we can configure different security attributes for both administrative and user applications within a cell environment. We can configure different applications to use different security configurations by assigning the servers or clusters or service integration buses that host these applications to the security domains. Only users assigned to the administrator role can configure multiple security domains.
Why security domains are useful
WebSphere Security Domains provide two major benefits:
- WebSphere Application Server administrative applications can be configured with a different set of security configurations from those for user applications.
- They enable one set of applications to have a different set of security configurations from another set of applications.
(zos) For example, WebSphere Application Server administration can be configured to a user registry of RACF while the applications can be configured to a user registry of LDAP.
For example, WebSphere Application Server administration can be configured to a user registry of federated repository while the applications can be configured to a user registry of LDAP.
In previous versions of WAS, all administrative and user applications share most of the security attributes. All administrative and user applications in WebSphere Application Server use global security attributes by default. For example, a user registry defined in global security is used to authenticate a user for every application in the cell.
In this release of WAS, however, we can use multiple security attributes for user applications other than the global security attributes, create a security domain for those security attributes that must differ, and associate them with the servers and clusters that host those user applications. You also can associate a security domain with the cell. All of the user applications in the cell use this security domain if they do not have a domain previously associated with them. However, global security attributes are still required for administrative applications such as the console, naming resources and MBeans.
If we have used server level security in previous releases of WAS, you should now use multiple security domains since they are more flexible and easier to configure.
Server level security is deprecated in this release. Read Relationship between global security and security domains for more information.
Relationship between global security and security domains
Global Security applies to all administrative functions and the default security configuration for user applications. Security domains can be used to define a customized configuration for user applications.
We must have a global security configuration defined before we can create security domains. The global security configuration is used by all of the administrative applications such as the console, naming resources, and Mbeans. If no security domains are configured, all of the applications use information from the global security configuration. User applications such as Enterprise JavaBeans (EJBs), servlets and administrative applications use the same security configuration.
When creating a security domain and associate it with a scope, only the user applications in that scope use the security attributes defined in the security domain. The administrative applications as well as the naming operations in that scope use the global security configuration. Define the security attributes at the domain level that need to be different from those at the global level. If the information is common, the security domain does not need to have the information duplicated in it. Any attributes that are missing in the domain are obtained from the global configuration. The global security configuration data is stored in security.xml, which is located in the $WAS_HOME/profiles/$ProfileName/cells/$CellName directory.
The following figure provides an example of a security multiple domain where the cell, a server and a cluster are associated with different security domains. As shown in the figure, the user applications in server S1.1 as well as the cluster use security attributes defined in Domain2 and Domain3 respectively (since these scopes are associated with these domains). Server S2.2 is not associated with a domain. As a result, the user application in S2.2 uses the domain that is associated with the cell (Domain1) by default . Security attributes that are missing from the domain level are obtained from the global configuration.
Figure 1. Scopes that can be associated to a security domain
The following figure shows the various high-level security attributes that can be defined at the global security configuration and those that can be overridden at the domain level.
Figure 2. Security attributes that can be configured at the security domain
Contents of a security domain
A security domain is represented by two configuration files. One configuration file contains the list of attributes configured in the security domain. The other configuration file contains the scopes that use the security domain. The security domain information is stored in the $WAS_HOME/profiles/$ProfileName/config/waspolicies/default/securitydomains/$SecurityDomainName directory. For every security domain configured, a $SecurityDomainName directory is created with two files in it: the security-domain.xml file contains the list of security attributes configured for the security domain, and the security-domain-map.xml file contains the scopes that use the security domain.
The location and contents of the main security domain related files can be seen here:
$WAS_HOME/profiles/$ProfileName/config/waspolicies/default/securitydomains/$SecurityDomainName directory security-domain.xml Can contain one or more security attributes such as the user registry, login configuration, authorization, trust association interceptor information, and so on. security-domain-map.xml Contains the list of application server resources that use the security attributes. For example, a cluster name in this file indicates that all of the user applications in the cluster use the security attributes.
You should not modify these files manually. Use console tasks or scripting commands to modify the files instead. For a complete list of administrative tasks and scripting commands, see the links in "Related tasks" at the end of this document.
Create security domains
Use the console tasks or scripting commands to create security domains. In the console, access security domains by clicking Security > Security domains. Help is available for each console panel.
For a complete list of console tasks and scripting commands, see the links in "Related tasks" at the end of this document.
When creating a security domain supply a unique name for the domain, the security attributes to configure for the security domain, and the scopes that need to use the security domain. Once configured, the servers that use the security domain must be restarted. The user applications in those scopes use the attributes defined in the security domain. Any attributes that are not configured at the domain level are obtained from the global security configuration. Administrative applications and naming operations in the scopes always use the security attributes from the global security configuration. We must actively manage these attributes.
Any new security domain attributes must be compatible with those global security attributes that are inherited by the user applications assigned to the domain.
Other than for JAAS and custom properties, once global attributes are customized for a domain they are no longer used by user applications.
The security domains panel in the console enables you to assign resources and to select the appropriate security attributes for the domain. The panel displays the key security attributes at the global configuration; we can make the decision to override them at the domain level if necessary. Once we have configured and saved the attributes at the domain level, the summary value on the panel displays the customized value for the domain (tagged with the word "customized" in black text).
A scope (a server, cluster, service integration bus or a cell) can be associated with only one domain. For example, we cannot define two domains that both have the cell-wide scope. Multiple scopes, however, can be defined in the same security domain. For example, a domain can be scoped to Server1 and to Server2 only within the cell.
The assigned scopes section on the security domain panel displays two views: one view that enables us to select and assign scopes to the domain, and another view that enables us to see a list of the currently assigned scopes. For convenience, we also have the flexibility to copy all of the security attributes from an existing security domain or the global configuration into a new security domain, and then modify only those attributes that must be different. We must still associate the scopes to these copied domains.
Configure attributes for security domains
Security attributes that can be configured at the domain level in WebSphere Application Server v8.5 are:
- Application security
- Java 2 security
- User realm (registry)
- Trust association
- Simple and Protected GSS-API Negotiation (SPNEGO) web authentication
- RMI/IIOP security (CSIv2)
- JAAS logins (Application, System and J2C Authentication Data)
- Java Authentication SPI
- Authentication mechanism attributes
- Authorization provider
- Federated repositories
- (zos) z/OS properties
- Custom properties
The security domains panels in the console display all of these security attributes.
Some of the other well-known attributes that we cannot override at the domain level are Kerberos, Audit, Web Single Sign-on (SSO) and Tivoli Access Manager (TAM). The Secure Socket Layer (SSL) attribute already supports different scopes, but it is not part of the domain configuration. For all of the attributes that are not supported at the domain level, user applications in a domain share their configuration from the global level.
Any new security domain attributes must be compatible with those global security attributes that are inherited by the user applications assigned to the domain. We must actively manage these attributes. For example, if you customize only a JAAS configuration at the domain level you must make sure that it works with the user registry configured at the global level (if the user registry is not customized at the domain level).
Other than for JAAS and custom properties, once global attributes are customized for a domain they are no longer used by user applications.
The Tivoli Access Manager client runtime is used to provide authentication (used by TrustAssociationInterceptor and PDLoginModule) and authorization (used for JACC) by contacting TAM servers. There is only one Tivoli Access Manager runtime shared by all servers in a cell. Read the Tivoli Access Manager JACC provider configuration topic for more information.
We cannot have a different Tivoli Access Manager configuration at the security domain level to override the configuration at the cell level. However, we can to some degree specify Trust Association Interceptor (TAI) and JACC configuration at the security domain level. For example, we can use a different TAI or a different authorization provider. Since TAM server connectivity can only be defined at the global level, we can have a variety of TAIs defined and configured at the security domain level. Some of these TAIs might not use the TAM user repository, while others do. The TAIs that do need to connect to TAM will also connect to the globally-defined TAM server. Similarly, for authorization, we can have a variety of external authorization providers configured at the domain level. However, if any of these external authorization providers require connection to TAM they end up talking to the singular globally-configured TAM server.
Associate scopes to security domains
In WebSphere Application Server v8.5, we can associate a security domain at the cell level, the server level, the cluster level and the service integration bus level.
For more information about the service integration bus and bus security in multiple security domains for WebSphere Application Server v8.5, see Messaging security and multiple security domains.
When a security domain is associated with a server that is not part of a cluster, all user applications in that server use the attributes from the security domain. Any missing security attributes are obtained from the global security configuration. If the server is part of a cluster, we can associate the security domain with the cluster but not with the individual members in that cluster. The security behavior then remains consistent across all of the cluster members.
If a server is to be part of a cluster, create a cluster first and associate the security domain to it. We might have associated a domain to a server before it was a member of a cluster. If so, even though the domain is associated with the server directly, the security runtime code does not look at the domain. When a server is a cluster member, the security runtime disregards any security domains associated directly to the server. Remove the server scope from the security domain and associate the cluster scope to it instead.
A security domain can also be associated to the cell. This is usually done when to associate all user applications in WebSphere Application Server to a security domain. In this scenario, all of the administrative applications and the naming operations use the global security configuration while all of the user applications use the domain level configuration. To split the security configuration information for administrative and user applications, this is all needed.
If we have a mixed-version environment, or plan to have one in future, and to associate security domains at the cell level, read Security domains in a mixed-version environment for more information.
If we are on a base profile server that has its own security domain defined, which is then federated to a deployment manager, associate the server scope to the security domain and not the cell scope. When you federate that node, the security domain information is propagated to the deployment manager. If the cell scope is associated to it, the network deployment configuration uses this security configuration, which might impact existing applications. During federation, the cell scope is changed to the server scope that is being federated. If the server scope is associated with the security domain, only that server uses the security domain after the federation. Other applications in other servers and clusters are not impacted. However, if this base profile server is registered to the Administrative Agent process we can associate the cell scope to the security domain if we want all of the servers from the base profile to use the same security domain for all of their user applications. Read about Federating a node with security domains for more information.
We can have a security domain associated at the cell level and also other security domains associated to various clusters or individual servers (those that are not part of any clusters). In this case, the security runtime first checks if any security domains are associated with the server or a cluster. If there is a security domain associated with the server or a cluster, the security attributes defined in it are used for all of the applications in that server or cluster. Any security attributes missing from this server or cluster domain are obtained from the global security configuration, and not from the domain configuration associated with the cell.
If the server or cluster does not have its own domain defined, the security runtime code uses the security attributes from the domain associated with the cell (if one is defined). Any security attributes missing from the cell domain are inherited from the global security configuration.
Relationship between old server level security and the new security domains
In previous releases of WAS, you could associate a small set of security attributes at a server level. These attributes were used by all of the applications at the server level. The previous way of configuring the security attributes was deprecated in WebSphere Application Server 7.0, and will be removed in a future release.
You should now use the new security domains support starting in WebSphere Application Server 7.0, as these security domains are more easily managed and much more flexible. For example, in previous versions of WAS, you must manually associate the same security configuration to all of the cluster members by configuring the same security attributes for every server in a cluster.
The migration tool migrates the existing server level security configuration information to the new security domain configuration when the script compatibility mode is false (-scriptCompatibility="false"). A new security domain is created for every server security configuration if it is not part of a cluster. If it is part of a cluster, a security domain is associated with the cluster instead of with all of the servers in that cluster. In both cases, all of the security attributes that were configured at the server level in previous releases are migrated to the new security domain configuration, and the appropriate scope is assigned to the security domains.
If the script compatibility mode is set to true, the server level security configuration is not migrated to the new security domains configuration. The old server security configuration is migrated without any changes. The security runtime detects that the old security configuration exists and uses that information, even if a security domain is associated either directly or indirectly to the server. If the script compatibility mode is set to true, remove the security configuration from the server level and then create a security domain with the same set of security attributes.
How domain level security attributes are used by security runtime and applications
This section describes how the individual attributes at the domain level are used by the security runtime and how that impacts the user application security. Since all of these security attributes are also defined at the global level, more information about these attributes can be obtained elsewhere. For the purposes of this section, the emphasis is on domain level behavior.
- Application Security:
Select Enable application security to enable or disable security for user applications. When this selection is disabled, all of the EJBs and web applications in the security domain are no longer protected. Access is granted to these resources without user authentication. When you enable this selection, the J2EE security is enforced for all of the EJBs and web applications in the security domain. The J2EE security is only enforced when Global Security is enabled in the global security configuration, (that is, we cannot enable application security without first enabling Global Security at the global level).
- Java 2 Security:
Select Use Java 2 security to enable or disable Java 2 security at the domain level or to assign or add properties related to Java 2 security. This choice enables or disables Java 2 security at the process (JVM) level so that all applications (both administrative and user) can enable or disable Java 2 security.
- User Realm (User Registry):
This section enables you to configure the user registry for the security domain. We can separately configure any registry used at the domain level. Read about Configure attributes for security domains for more information.
When configuring a registry at the domain level we can choose to define our own realm name for the registry. The realm name distinguishes one user registry from another. The realm name is used in multiple places - in the Java client login panel to prompt the user, in the authentication cache, and when using native authorization.
At the global configuration level, the system creates the realm for the user registry. In previous releases of WAS, only one user registry is configured in the system. When we have multiple security domains we can configure multiple registries in the system. For the realms to be unique in these domains, configure our own realm name for a security domain. You also can choose the system to create a unique realm name if it is certain to be unique. In the latter case, the realm name is based on the registry that is being used.
For LDAP registries, the host:port of the LDAP server is the system-generated realm name. For localOS, the name of the localOS machine is the realm name. For custom user registries, the realm is the one returned by the getRealm ( ) method of the custom registry implementation.
If the system generated realm names are unique enough, we can choose the option for the system to generate the realm name. If not, choose a unique realm name for each security domain where we have the user registry configured. If the underlying user repository is the same, use the same realm name in different domains. From a security runtime perspective, same realm names have the same set of users and groups information. For example, when users and groups information is required from a realm, the first user repository that matches the realm is used. If a localOS registry that is not centralized is configured for any domain, and that domain is associated with servers or clusters in nodes not on the same system as the deployment manager, the realm name has to be provided. This realm name has to be the same as it would be if it were generated on the node. This realm name can be obtained by calling the getRealm() method on the SecurityAdmin MBean on that node. Typically, the realm name for localOS registries is the hostname of the machine. In this case, you should not let the system generate the realm name but rather get the realm name used by the processes in the node.
If we select the system to generate the realm for the localOS registry at the time of the user registry configuration, it chooses the localOS registry used by the deployment manager. If the realm configured does not match the realm used by the servers then there are authorization issues. Also note that in this case, the domain using this local registry can only be associated with servers and clusters that belong to nodes on the same machine.
In WAS v7, the federated repositories user registry can only be configured at the global level and have only one instance per cell, but any domain can use it by configuring it as the active registry. In WebSphere Application Server Version 8.0, we can configure a unique instance of a federated repository at the domain level in a multiple security domain environment.
When a security domain is copied from the global level, the users and groups defined at the global level are also copied to the security domain. This is also true when copying from an existing domain. A newly-created security domain that uses the file-based VMM repository requires that the user populate the repository with users and groups.
Also new in this release of WAS, a new checkbox on the Realm configurations settings console page, Use global schema for model, sets the global schema option for the data model in a multiple security domain environment. Global schema refers to the schema of the admin domain.
When more than one user registry is in a process, the naming lookup that uses "UserRegistry" as the lookup name returns the user registry used by user applications. The user registry used by administrative applications is bound by the lookup name, "AdminUserRegistry".
As described in Cross realm communication, when an application in one realm communicates with an application in another realm using LTPA tokens, the realms have to be trusted. The trust relationship can be established using the Trusted authentication realms - inbound link in the user registry panel or using the addTrustedRealms command. We can establish trust between different realms. A user logged into one realm can access resources in another realm. If no trust is established between the two realms the LTPA token validation fails.
The realm name used in the web.xml file is not related to the user registry realm.
- Trust Association:
When you configure the trust association interceptor (TAI) at a domain level, the interceptors configured at the global level are copied to the domain level for convenience. We can modify the interceptor list at the domain level to fit the needs. Only configure those interceptors that are to be used at the domain level.
Tivoli Access Manager's trust association interceptors can only be configured at the global level. The domain configuration can also use them, but cannot have a different version of the trust association interceptor. Only one instance of Tivoli Access Manager's trust association interceptors can exist in the cell.
- SPNEGO web authentication:
The SPNEGO web authentication, which enables you to configure SPNEGO for web resource authentication, can be configured at the domain level.
In WAS v6.1, a TAI that uses the SPNEGO to securely negotiate and authenticate HTTP requests for secured resources was introduced. In WebSphere Application Server 7.0, this function was deprecated. SPNEGO web authentication has taken its place to provide dynamic reload of the SPNEGO filters and to enable fallback to the application login method.
- RMI/IIOP Security (CSIv2):
The RMI/IIOP security attribute refers to the CSIv2 (Common Secure Interoperability version 2) protocol properties. When you configure these attributes at the domain level, the RMI/IIOP security configuration at the global level is copied for convenience.
We can change the attributes that need to be different at the domain level. The Transport layer settings for CSIv2 inbound communications should be the same for both the global and the domain levels. If they are different, the domain level attributes are applied to all of the application in the process.
When a process communicates with another process with a different realm, the LTPA authentication and the propagation tokens are not propagated to the downstream server unless that server is listed in the outbound trusted realms list. This can be done using the Trusted authentication realms - outbound link on the CSIv2 outbound communication panel, or using the addTrustedRealms command task. Read about Cross realm communication for more information.
- JAAS (Java Authentication and Authorization Service):
The JAAS application logins, the JAAS system logins, and the JAAS J2C authentication data aliases can all be configured at the domain level. By default, all of the applications in the system have access to the JAAS logins configured at the global level. The security runtime first checks for the JAAS logins at the domain level. If it does not find them, it then checks for them in the global security configuration. Configure any of these JAAS logins at a domain only when specify a login used exclusively by the applications in the security domain.
For JAAS and custom properties only, once global attributes are customized for a domain they can still be used by user applications.
- Java Authentication SPI
(JASPI)
Configuration settings for a Java Authentication SPI (JASPI) authentication provider and associated authentication modules to be applied at the domain level.
Select Providers to create or to edit a JASPI authentication provider.
The JASPI authentication provider can be enabled with providers configured at the domain level. By default, all of the applications in the system have access to the JASPI authentication providers configured at the global level. The security runtime first checks for the JASPI authentication providers at the domain level. If it does not find them, it then checks for them in the global security configuration. Configure JASPI authentication providers at a domain only when the provider is to be used exclusively by the applications in that security domain.
- Authentication Mechanism Attributes:
Various cache settings that must be applied at the domain level.
- Authentication cache settings - use to specify the authentication cache settings. The configuration specified on this panel is applied
only to this domain.
- LTPA Timeout - We can configure a different LTPA timeout value at the domain level. The default timeout value is 120 minutes, which is set at the global level. If the LTPA timeout is set at the domain level, any token created in the security domain when accessing
user applications is created with this expiration time.
- Use realm-qualified user names - When this selection is enabled, user names returned by methods such as getUserPrincipal( ) are qualified with the security realm (user registry) used by applications in the security domain.
- Authentication cache settings - use to specify the authentication cache settings. The configuration specified on this panel is applied
only to this domain.
- Authorization Provider:
We can configure an external third party JACC (Java Authorization Contract for Containers) provider at the domain level. Tivoli Access Manager's JACC provider can only be configured at the global level. Security domains can still use it if they do not override the authorization provider with another JACC provider.
The JACC attributes, for example the Policy object, are based at the JVM level. This implies that there can be only be one JACC policy object in a JVM process. However, when we have multiple JACC providers configured, the deployment manager process has to handle all these providers in the same JVM because it has to propagate the authorization policy of applications to the respective provider based on the application name.
If the JACC provider can handle propagating the authorization policy to multiple providers, we can configure it at the global level. In this case, when an application is installed, this JACC provider is called in the deployment manager process and it is the responsibility of this JACC provider to propagate the information to the corresponding JACC provider based on the application name passed in the contextID.
Another way to achieve this is to set the custom property, com.ibm.websphere.security.allowMultipleJaccProviders=true, at the global security level. When this property is set, WebSphere Application Server propagates the authorization policy information to the JACC provider associated with the domain that corresponds to the target server where the application is installed. This property is only used at the deployment manager process since the managed servers do not host multiple JACC providers.
(zos) We can additionally configure the SAF authorization options at the security domain level, which are the following:
- The unauthenticated user id
- The SAF profile mapper
- Whether to enable SAF delegation
- Whether to use the APPL profile to restrict access to WebSphere Application Server
- Whether to suppress authorization failed messages
- The SMF audit record strategy
- The SAF profile prefix
(zos) CBIND checks are considered administrative operations, and therefore the global level value of the SAF profile prefix specified, is used when determining the name of the CBIND resource to check. For example: CB.BIND.<cluster_name or SAF_profile_prefix>.
(zos) For more information about the SAF authorization options, read about z/OS System Authorization Facility authorization.
- The unauthenticated user id
- Custom properties:
Set custom properties at the domain level that are either new or different from those at the global level. By default, all of the custom properties at the global security configuration can be accessed by all of the applications in the cell. The security runtime code first checks for the custom property at the domain level. If it does not find it, it then attempts to obtain the custom property from the global security configuration.
For JAAS and custom properties only, once global attributes are customized for a domain they can still be used by user applications.
Client and application security programming model when using security domains
A Java client or an application acting as a client that accesses an EJB typically does a naming lookup first. The naming resource, which is used by both administrative and the user applications, is considered an administrative resource. It is protected by the global security configuration information. In a multiple domain setup where the global security is using one realm (the user registry) and a domain is using a different realm, the Java client must authenticate to two different realms. The first authentication is required for the realm in the global security configuration for the naming operation to succeed, and the second authentication is required to access the EJB, which uses a different realm.
The CosNamingRead role protects all naming read operations. This role is usually assigned the Everyone special subject. This implies that any user, valid or not, can look up the name space. When a multiple domain is defined, if the CosNamingRead role has the Everyone special subject the security runtime code in the client side does not prompt you to log in. It uses the UNAUTHENTICATED subject to access the naming operation instead. Once the naming lookup operation is completed, when the client attempts to access the EJB it is prompted with a login panel that indicates the realm currently used by that EJB application (that is, the realm used in the domain). The client then presents the appropriate user credentials for that realm, which can then access the EJB. This logic applies to all variations of login source, including properties and stdin, not just when the login source is set to prompt.
If the Everyone special subject is removed from the CosNamingRead role, you are prompted twice. If the login source is properties, we can uncomment the com.ibm.CORBA.loginRealm property in the $WAS_HOME/profiles/$ProfileName/properties/sas.client.props file and add the appropriate realms using "|" as the separator. We must also enter the corresponding users and passwords in the com.ibm.CORBA.loginUserid and com.ibm.CORBA.loginPassword properties respectively. When using the programmatic logon in the Java client code you must authenticate twice with different user credentials; once prior to do a naming lookup for the EJB (the user should be in the global realm), and later prior to calling any method in the EJB (the user should be in the EJB domain's realm).
(zos) The CosNamingRead role defined in the z/OS security server is not referenced for determining if naming read operations are protected in a multi-security domain environment, even when SAF authorization is enabled. Instead, the settings in the admin-authz.xml file are used. Alternatively, we can use the custom property com.ibm.security.multiDomain.setNamingReadUnprotected to control if naming read operations are protected. This property will override any assignments made to the CosNamingRead role, regardless of which authorization provider is used.
In general, when a Java client needs to authenticate to multiple and different realms it has to provide the credential information for all of those realms. If the login source is prompt or stdin it is prompted to login multiple times, once for each realm. If the login source is set to properties, the appropriate properties in the sas.client.props file (or any related file) are used for authenticating to different realms.
In certain scenarios, a client might make multiple calls to the same realm. For example, the Java client can access a resource using realm1 followed by access to a resource using realm2, and then come back to access a resource in realm1 again. In this case, the client is prompted three times; first for realm1, secondly for realm2 and finally for realm1 again.
By default, the subject used to login at a realm is not cached by the client side code. If we have this scenario, and we want the client to cache the subject based on the realm, set the com.ibm.CSI.isRealmSubjectLookupEnabled property to true in the sas.client.props file. If the com.ibm.CSI.isRealmSubjectLookupEnabled property is set, the client code caches the subject based on the realm name. The next time the Java client needs to authenticate to this realm, the cache is located to obtain the subject and the client is not prompted. Also, when the com.ibm.CSI.isRealmSubjectLookupEnabled property is set, the same subject that was logged in the first time is used for subsequent logins. If the subject information needs to change then this property should not be set.
If the client is doing a programmatic login it can pass the realm along with the user and password that it needs to authenticate. In this case, when the com.ibm.CORBA.validateBasicAuth property is set to true (the default value) in the sas.client.props file, the registry that matches the realm name is used for login. That realm must be supported in the process where the authentication takes place.
When using the WSLogin JAAS configurations, we also must set the use_realm_callback option in the wsjaas_client.config file in $WAS_HOME/profiles/$ProfileName/properties for the realm name to be passed to the call back handler. To specify a different provider URL for the name server, set the use_appcontext_callback option and pass in the provider URL properties in a hash map to WSLogin.
If we do not know the realm name, use <default> as the realm name. The authentication is performed against the application realm. If the naming read operation does not have the Everyone special subject assigned, provide the realm used by the administrative applications (the registry used in the global security configuration), as well as the appropriate user and password information in that registry for the lookup operation to succeed.
After the lookup operation succeeds, perform another programmatic login by providing the application realm (or <default>) and the user and password information for the appropriate user in the registry used by the application. This is similar to the case where the login source is prompt. We must authenticate twice, once for the registry used by the global security configuration (for the naming lookup operation) and again for the registry used by the application to access the EJB.
If com.ibm.CORBA.validateBasicAuth is set to false in the $WAS_HOME/profiles/$ProfileName/properties/sas.client.props file then the programmatic login can use <default> as the realm name for both the lookup and the EJB operations. The actual authentication occurs only when the resource is accessed on the server side, in which case the realm is calculated based on the resource that is accessed.
The new security domain support starting in WebSphere Application Version 7.0 does not change the current application security programming model. However, it provides more flexibility and capabilities such as the following:
- User applications can still find the user registry object using the naming lookup for "UserRegistry". For the registry object used by administrative applications, the naming lookup for "AdminUserRegistry"
can be used.
- The application usage of the JAAS login configuration does not change in a multiple domain setup. However, if an application must refer to the JAAS configuration specified at the domain level, the administrator and the deployer of that application must make sure
that this domain is configured with the JAAS configurations that are required by the application.
- If an application needs to communicate with other applications using different realms, trust relationship should be established for both inbound and outbound communications when using the LTPA tokens.
Read about Cross realm communication for more information.
- When using programmatic login in the applications, to login to the realm used by the application, use <default> as the realm name or provide the realm name that the application is using. If we need to login to the global realm, provide the global realm name. If we provide any other realm, only a basic authentication subject is created. When the request actually flows to the server hosting that realm, the actual authentication of the user occurs if that server hosts the realm. If the server does not host the realm, the login fails.
Application deployment in multiple domains configurations
When deploying an application in a multiple domain setup, all of the modules in the application should be installed in the servers or clusters that belong to the same security domain. If not, depending on the security attributes configured in these security domains, inconsistent behavior can result. For example, if the domains contain different user registries, the users and groups information can be different, which can cause inconsistent behavior when accessing the modules. Another example is when the JAAS data is different between the security domains. The JAAS configurations is not accessible from all of the modules in the application. The security runtime code and the command tasks rely on one domain being associated with an application when dealing with attributes such as user registry, JAAS login configurations, J2C authentication data, and authorization.
In most cases, application deployment fails when an application is deployed across different domains. However, since this was possible in earlier releases of WAS when only a few attributes were supported at the server level, the deployment tool first checks for attributes configured at the domains. If the attributes in the domain are the same as those supported in previous releases, the console requests confirmation to ensure to deploy application modules across multiple security domains. Unless there is an absolute requirement to deploy the applications across different domains, stop the deployment and select the servers and clusters in the same security domain.
Cross realm communication
When applications communicate using the RMI/IIOP protocol and LTPA is the authentication mechanism, the LTPA token is passed between the servers involved. The LTPA token contains the realm-qualified uniqueId, (also called the accessId), of the user who is logging into the front-end application. When this token is received by the downstream server it attempts to decrypt the token. If the LTPA keys are shared between the two servers, decryption succeeds and the accessId of the user is obtained from the token. The realm in the accessId is checked with the current realm used by the application. If the realms match, the LTPA token validation succeeds and it proceeds with the authorization. If the realms do not match, the token validation fails since the user from the foreign realm cannot be validated in the current realm of the application. If applications are not supposed to communicate with each other when using RMI/IIOP and the LTPA authentication mechanism, we do not to have to do anything further.
If we do want the cross realm communication to succeed when using RMI/IIOP and LTPA tokens, first establish trust between the realms involved, both for inbound and outbound communications.
For the server originating the request, its realm must have the realms that it can trust to send the token to. This is referred to as outboundTrustedRealms. For the server receiving the request, its realm needs to trust the realms that it can receive LTPA tokens from. This is referred to as inboundTrustedRealms.
Outbound trusted realms can be established using the addTrustedRealms command with the -communicationType option set to outbound. It can also be established in the console by clicking Trusted authentication realms - outbound on the CSIv2 outbound communications panel.
Inbound trusted realms can be established using the same addTrustedRealms command task with the -communicationType option set to inbound. It can also be established using the console.
The figure later in this section shows the communication between applications that use different user realms (registries) using RMI/IIOP. In this example, application app1 (for example, a servlet) is configured to use the realm1 user registry. The app2 application (for example, an EJB) is configured to use the realm2 user registry. The user (user1) initially logs into the servlet in app1, which then attempts to access an EJB in app2. The following must be set:
- In Domain1, realm1 should trust realm2 for the outbound communication.
- In Domain2, realm2 should trust realm1 for the inbound communication.
- The accessId for user1 should be configured in the authorization table for app2.
When the LTPA token containing the accessId of user1 is received by app2, it decrypts the token. Both of the servers share the same LTPA keys. The LTPA token then ensures that the foreign realm is a trusted realm, and performs the authorization based on the accessId of user1. If security attribute propagation is not disabled, then the group information of user1 is also propagated to app2. The groups can be used for the authorization check, provided that the authorization table contains the group information. We can associate a special subject, AllAuthenticatedInTrustedRealms, to the roles instead of adding individual users and groups to the authorization table.
If the applications in the previous example are deployed in different cells, you must do the following:
- Share the LTPA keys between the cells.
- Update the authorization table for app2 with foreign users and groups accessIds using the wsadmin utility. The console does not have access to the realms outside of the scope of the cell.
Figure 3. Cross realm communication in a multiple realm environment
Once trust has been established between the realms, when the server receives the LTPA token and the token is decrypted, it checks to see if the foreign realm is in its inbound trusted realms list. If it is trusted, the authentication succeeds. However, since it is a foreign realm, it does not go search the user registry to gather information about the user. Whatever information is in the LTPA token is used to authorize the user.
The only information in the LTPA token is the unique id of the user. This unique id of the user should exist in the authorization table for this application. If it does, authorization succeeds. However, if attribute propagation is enabled, additional authorization attributes (groups that this user belongs to) for the user are sent from the originating server to the receiving server. These additional attributes are used to make the access decisions. If the groups information exists in the propagation tokens it is used when making the authorization decision.
As previously mentioned, the information about the users and or the groups from the trusted realms should exist in the authorization table of the receiving application. Specifically, the accessId of the users and or groups should exist in the binding file of the application. This must be the case when the application is deployed. In the console, when an application is deployed in a domain we can add the accessIds of the users and groups from any of its trusted realms to the authorization table.
You also have an option to associate a special subject, AllAuthenticatedInTrustedRealms, to the roles instead of adding individual users and groups. This is similar to the AllAuthenticated special subject currently supported. The difference is that the AllAuthenticated special subject refers to users in the same realm as the application while the AllAuthenticatedInTrustedRealms special subject applies to all of the users in the trusted realms and in the realm of the application.
We can associate the accessId using the $AdminApp install script. Because the accessId takes a unique format, use the command task listRegistryUsers with displayAccessIds set to true. If an invalid name or format is entered in this field, the authorization fails.
User and group information from the trusted realms is obtained by the deployment manager since it has access to all of the user registry configurations in all domains. However, in certain situations it is not possible to obtain the users and group information.
For example, if a server hosted on an external node is using localOS as the registry for its domain, the deployment manager cannot obtain the users and groups information unless it is running in the same operating system setup. The external operating system should be contacted to obtain this information. This can be done by directly invoking the registry in the server associated with that domain. The servers associated with the domain have to be started for this to work. You also must set the property, com.ibm.websphere.allowRegistryLookupOnProcess, to true in the top-level security custom properties. When this property is set, the deployment manager code searches one of the servers that is associated with the security domain and obtains the users and groups information directly from it. This is possible by calling an MBean in one of the servers.
If the MBean in any of the servers that are using that domain cannot be accessed, the console displays a panel where we can enter the user and accessId information manually for each user and group. It is important that the correct accessId format be entered in this field. The accessId format for the user is user:realmName/userUniqueId. The realmName is the name of the realm where the user resides, and the userUniqueId is the uniqueId that represents the user, depending on the registry used.
For example, for LDAP, the uniqueUserId is the Distinguished Name (DN), for the Windows localOS registry and is the SID of the user. For Unix platforms, it is the UID. For custom registries, it depends on the implementation.
Similarly, for groups, the accessId format is group:realmName/groupUniqueId. As previously mentioned, use the listRegistryUsers and listRegistryGroups command with the -displayAccessIds option set to true so that we can obtain the correct format for the domain or realm that you are interested in.
Once users and groups from the trusted realms or the AllAuthenticatedInTrustedRealms special subject is added to the authorization table of the application, it is ready to accept requests from other applications that are using any of its trusted realms. The LTPA token validation on the receiving server first checks to verify the realm is trusted. The authorization engine then checks to see if the external user and/or the groups or the AllAuthenticatedInTrustedRealms special subject are given access to the roles needed to access the resource. If true, access is granted.
Cross realm communication is only applicable when using the WebSphere built-in authorization. If we are using other authorization engines including SAF for z/OS, any cross realm authorization can be achieved by implementing custom login modules that map external users to users in its own repository.
Federating a node with security domains
When a security domain is configured in the base version and is federated to a cell, the security domain configured at the base version is also configured for that server in the cell. The same domain security configuration can be used by the server before and after the federation. If a base server is to be federated to a cell, the resource assigned to the security domain should be the server scope instead of the cell scope.
If the base server is expected to be registered with an Administrative Agent process, use the cell scope as the resource if the intention is to have all of the servers in the base profile use this security domain.
If during federation the security domain at the base already exists at the cell level, the addNode command fails. We can use the -excludesecuritydomains option not to include the security domain during federation.
When the federated node is removed from a cell, the resources in that node should be removed from the security domains. If security domains have clusters associated with them that span nodes, the nodes are not removed. We can always remove resources from the security domains or any domains that are not used by commands or the console.
Security domains in a mixed-version environment
Create security domains once all of the nodes have been migrated to the latest version. This is especially true if there is a need to associate the cell with a domain. However, to create security domains in a mixed- version environment, be aware of the following:
- If a cell-wide domain is created in a mixed version setup, a domain called PassThroughToGlobalSecurity is created automatically.
All mixed clusters are assigned to this domain at the time of the creation of the cell-wide domain. This PassThroughToGlobalSecurity domain is special in the sense that attributes cannot be added to it, only resources can be assigned to it.
All resources assigned to the PassThroughToGlobalSecurity domain use the global security configuration information. Whenever a node in the mixed version setup is migrated to the latest version, the servers and clusters in these nodes are added to this domain. Applications in all of the servers and clusters in these nodes do not use the cell-wide domain; they instead use the global security configuration before and after migration.
If any of these servers need to use the cell-wide domain, remove these resources from this PassThroughToGlobalSecurity domain. New servers and clusters created in the migrated node use the cell-wide domain, not the PassThroughToGlobalSecurity domain. As a result, we have a mix of servers and clusters, some of them using global security configuration and some using the cell-wide domain.
- Once a cell-wide domain is created, adding any old version cluster
members to a WAS v8.5 cluster is restricted
since this action makes it a mixed cluster. This restriction also holds true when a WAS v8.5 cluster is associated
with a domain. and a previous version cluster member is added to this cluster. This restriction is needed to avoid associating a security domain to a mixed cluster.
- If possible, you should create a cell-wide domain after all of the nodes have been migrated. In this case, the cell-wide domain is applicable to the entire cell and not just to parts of it. This also eliminates the need to create the PassThroughToGlobalSecurity domain and the mixed cluster scenario with security domains.
Modify security domains
Use the console tasks or scripting commands to modify security domains. For a complete list of administrative tasks and scripting commands, see the links in "Related tasks" at the end of this document.
Once a security domain is created and associated to a set of scopes, the servers associated with this new domain must be restarted. After the restart, the applications in the scopes associated with the new domain use the security attributes defined in the domain.
Changes to any of the domain attributes requires the restart of all of the scopes assigned to it. If new scopes are added they also need to be restarted. Any modifications to the domain configuration, either to the security attributes or to the scopes, has impacts on those applications that are using the domain configuration.
Before we make modifications to an existing domain, consider the following potential impacts. For example, if a user registry configured at a domain is removed, and the servers restarted, the user registry from the cell-wide domain (if one is defined), or the global security configuration is then used. This can impact application authentication and authorization. Users and groups associated with an application might no longer be valid in the new registry. Another example to consider is when JAAS configurations are removed from a domain. Applications that rely on this are no longer be able to use the JAAS configurations. Whenever a security configuration is changed it might impact the applications, so all security configuration changes should be made with the utmost care.
(zos) Toleration PTFs required for mixed-release environments
Toleration PTFs are required for mixed-release environments in which previous versions of WAS for z/OS IIOP clients inter-operate with a WAS v8.5 for z/OS application server that hosts multiple security domains.
The pre-v8.5 IIOP client requires an update to its IIOP locate processing code to perform IIOP locates across the security domains of a v8.5 application server.
The toleration PTFs for all affected service releases are listed later in this section. The pre-v8.5 IIOP client must be at or later than the given service level to successfully inter-operate with a v8.5 application server containing multiple security domains.
WebSphere Application Server for z/OS 5.1: W510246
WebSphere Application Server for z/OS v6.0: 602.29
WebSphere Application Server for z/OS v6.1: 610.17
This requirement applies only to WebSphere for z/OS IIOP clients that invoke requests against a WebSphere for z/OS application server with multiple security domains configured and enabled.
Related concepts
Related tasks