External security managers: TAM and SPNEGO

External security managers: TAM and SPNEGO

Overview
WebSEAL junctions
Encrypted junction configurations
Migration considerations
Enable user provisioning
Verify external authorization to TAM
Remove the Credential Vault adapter
Disable user provisioning
WebSphere TAIs
External authentication
Custom TAIs
External authorization
TAM Permissions
Portlets accessing back-end services through an external security manager
Configure single sign-on for HTTP requests using SPNEGO
Verify TAIs for authentication
Login and logout pages
Access control with ESMs

Overview

By default...

WAS controls authentication to Portal
Portal controls authorization to resources

Alternatively we can use external security managers (ESM), such as IBM Tivoli Access Manager (TAM), to execute authentication, or authentication and authorization. Only configure the ESM after completing all other setup tasks, including ensuring that the cluster is functional.
Available TAM services include...

WebSEAL Single Signon for authentication
User provisioning from WebSphere Portal self-registration
Protected Object Space and Access Control List Management
Global Sign-on lockbox credential vault integration

WebSEAL junctions

WebSEAL Junctions are http or https connections between a front-end WebSEAL server and a back-end web application server. WebSEAL performs authentication checks on all requests for resources, then passes those requests across the junction to the back-end server.
Virtual host junctions use a virtual host name to identify the junction. For example...
http://junction1.webseal.hostname.myco.com

A Trust Association Interceptor (TAI) on WAS accepts the identity of the user and authenticates the WebSEAL server.
For xmlaccess.sh to access portal through a WebSEAL junction, use TAM to define the configuration URL, /wps/config, within the junction as unprotected. Once the configuration URL is defined as unprotected, only portal enforces access control to this URL. Other resources, for example, wps/myportal, are still protected by WebSEAL.
For more info...

IBM Knowledge Center: External Security Managers
WebSEAL Administration Guide
HTTP Server library

The identity of the user is passed to the TAI in a header called iv-user, which is inserted by WebSEAL into the request sent from WebSEAL to the WAS and the portal servers. The junction creation option to set this up is -c iv-user. While WebSEAL can be configured to pass the user identity in other ways, the iv-user header is the only one that is supported by the TAI.
See also: Extended Tivoli Access Manager Plus (ETAI)

Encrypted junction configurations

The junctions between WebSEAL and WAS and portal can be configured to be encrypted or not. Encrypted junctions enhance security by making sure that no one can eavesdrop on information that is flowing between WebSEAL, WAS, and portal. However, encrypted junctions require additional administration to move the necessary signing certificates between the systems, and also have a performance cost. If we are not comfortable that the network between the firewalls is secure against unauthorized access and observation, use encrypted junctions between WebSEAL and WAS/portal. If we are comfortable that the network is secure against unauthorized access and observation, especially for traffic across an inner firewall, we can use unencrypted junctions between WebSEAL and WAS/portal.
Setting up the WebSEAL-WAS/portal junction over SSL requires configuration of WAS and the HTTP server to accept inbound SSL traffic, and route this traffic correctly to WAS and portal. This process includes importing the necessary signing certificates into at least the WebSEAL certificate keystore, and possibly also the HTTP server certificate keystore.
To use encrypted junctions between WebSEAL and WAS and portal, we can also choose to have WebSEAL identify and authenticate itself to WAS and the TAI using its own client-side certificate. In this case, it is possible to configure the TAI to not do any further validation of the WebSEAL server, relying on the mutual SSL connection to supply a trustable identity for the WebSEAL server.
If you choose not to use client-side certificates to identify the WebSEAL server, or if you choose not to use an SSL junction, we can identify the WebSEAL server to the TAI using a Basic Authentication (BA) header. In this case a password will be placed into the BA header, and also configured into the TAI. This represents a "shared secreto that only the TAI and the WebSEAL server know, which allows the TAI to truse that it really is the WebSEAL server that is asserting the user's identity, and the TAI can trust it. In this case, using an SSL junction will provide additional security by protecting this BA header from observation, but the TAI will still rely on the BA header for identifying the WebSEAL server.
To set up the junction to use the Basic Authentication header to identify the WebSEAL server, use the -b supply option on the junction creation command. This causes WebSEAL to build the BA header using the user's user ID (which is ignored by the TAI, in favor of the iv-user header) and the passworconfigured into WebSEAL from the webseald-instance.conf file, on the basicauth-dummy-passwd property. The password in the webseald-instance.conf file must match the password for the Ispecified on the com.ibm.websphere.security.webseal.loginid property of the TAI startup parameters in the WAS admin console.
For example, if we specify...
com.ibm.websphere.security.webseal.loginid=mistered

...on the TAI startup parameters, and the password for mistered is wilbur, then specify wilbur on the basicauth-dummy-passwd property in webseald-instance.conf on the WebSEAL server.

Migration considerations

Non-transparent URIs...
{host}/{WebSeal Junction}/{Portal uri's}

...allow use of a single junction to service requests for /wps* along with request such as /enhancedTheme or /{customapps}. With transparent junctions the WebSEAL recommended approach is to create a junction for each unique path to the backend Portal server.
To reduce the number of junctions in Portal v8 use virtual host junctions. Instead of using the first level of the URL following the hostname, WebSEAL uses the hostname in the URL to determine the backend server where the request will be directed. This eliminates the need to use the junction in the URL. An additional IP address typically has to be configured on the network interface of the server for the VHJ. Virtual host junctions perform better than tranparent junctions because the inspection of HTTP traffic is reduced to a bare minimum.

Enable user provisioning

When users are created in WebSphere Portal, they are not automatically imported into TAM. Enable automatic user provisioning to TAM changes this behavior. Once this feature is enabled, users are automatically imported into TAM whenever they are created in WebSphere Portal. When user provisioning to TAM, anyone with access to the public URL can become an active user in TAM as long as the self-registration feature remains enabled.
There are two ways to create users in WebSphere Portal:

Self-registration: Enabled by default.
Manage Users and Groups portlet: Administrators can use this portlet to create WebSphere Portal users.

To enable user provisioning within TAM, if this is a clustered environment, run the following tasks on each node in the cluster.

Validate that the AMJRTE properties exists:
./ConfigEngine.sh validate-pdadmin-connection -DWasPassword=foo -Dwp.ac.impl.PDAdminPwd=foo

Clustered environments:

Complete this step on all nodes.
WasPassword is the dmgr administrative password.

If the task does not run successfully, run run-svrssl-config to create the AMJRTE properties file, then run validate-pdadmin-connection again. If the task is not successful after a second attempt, do not perform any subsequent steps in this topic. In all likelihood, the portal cannot connect to the TAM server.

Start all servers.

Enable user provisioning:
cd WP_PROFILE/ConfigEngine
./ConfigEngine.sh enable-tam-userprov -DPortalAdminId=foo -DPortalAdminPwd=foo

Stop and restart servers, dmgrs, and node agents.

Related
Start and stop servers, dmgrs, and node agents

Verify external authorization to TAM

After configuring portal to use TAM for externalized authorization, verify that it works properly before continuing with any additional configuration tasks.
To verify that TAM is working properly:

Verify the topology matches the topology described in the protected object space.
For example, ensure the value of the wp.ac.impl.PDroot parameter exists in the TAM protected object space.

To verify that at least one user, typically the administrator, has the Administrator@VIRTUAL/EXTERNAL ACCESS CONTROL_1 role:

To verify the administrator and administrator group have the Administrator@VIRTUAL/EXTERNAL ACCESS CONTROL_1 role, on the pdadmin command line, run...
pdadmin> acl show WPS_Administrator-VIRTUAL_wps-EXTERNAL_ACCESS_CONTROL_1

Optionals to add the administrator to the Administrator@VIRTUAL/EXTERNAL ACCESS CONTROL_1 role if no entry is found:

pdadmin> acl modify WPS_Administrator-VIRTUAL_wps-EXTERNAL_ACCESS_CONTROL_1 set user wpsadmin T[WPS]m
pdadmin> acl modify WPS_Administrator-VIRTUAL_wps-EXTERNAL_ACCESS_CONTROL_1 set group wpsadmins T[WPS]m

...where wpsadmin is the administrator user ID and wpsadmins is the administrator group.

Perform the following steps from the Resource Permissions portlet:

Select a resource type.

Click the Assign Access icon for the specific resource.

Click the Edit Role icon for a role to externalize.

Click Add to explicitly assign at least one user or group to the chosen role for the resource.

Click Search for Users or User Groups or click the pull down for the Search by option where the default is set to All available to select specific users or user groups. Click OK.. An informational message box should display the message that members were successfully added to the role.

Optional: Explicitly assign additional roles. If you do not assign at least one user or group to each role type for the resource, use the external security manager interface to create this role type later.
For example, if you do not assign any users or groups to the Editor role type for the resource, then use the external security manager interface to create the Editor role type later.

Click the Externalize icon for the resource. These steps move every role defined for each resource you assigned to the TAM protected object space. One ACL is created for each externalized role.

Add users to the ACLthat are attached to the role types on that resource using either the TAM GUI or the pdadmin command line.
If you log on as an administrator to externalize resources to TAM...

Be a member of the wpsadmins group.
The wpsadmins group must appear in the VIRTUAL/EXTERNAL_ACCESS_CONTROL_1 ACL.

Remove the Credential Vault adapter

If you no longer require the use of the credential vault adapter that you created, we can remove it from the configuration.
To remove the credential vault adapter:

Use the Credential Vault portlet to remove any segments created in the TAM Vault.
See the Credential Vault portlet help for more information.
Do not remove DefaultAdminSegment.

Remove the Vault.AccessManager Credential Vault Adapter implementation properties from the Credential Vault Segment configuration; including class, config, manager, and read only.
Do not remove the systemcred.dn parameter.

Remove...
WP_PROFILE/PortalServer/config/config/accessmanagervault.properties
Clustered environments: Perform this step on all portal nodes.

Disable user provisioning

After enabling and using the user provisioning feature within IBM TAM, we can disable the feature.
To disable user provisioning within TAM:
Perform these steps on one portal node in a clustered environment.

Run the following task to disable user provisioning:

cd WP_PROFILE/ConfigEngine.
./ConfigEngine.sh disable-tam-userprov -DWasPassword=foo -Dwp.ac.impl.PDAdminPwd=foo

In a clustered environment WasPassword is the dmgr administrative password.

Stop and restart servers, dmgrs, and node agents.

WebSphere TAIs

TAM provide TAIs (TAIso used only as an authentication service.

External authentication

TAIs can be configured with the Portal configuration tasks. The TAM TAI requires an available TAM authorization server for successful single sign-on.
Whenever a request attempts to access a secured resource, WAS starts the TAI. The TAI validatethat the request comes from a legitimate third-party authentication proxy and returns the user's authenticated identity to WAS. The TAI returns either a DN or a short name. WAS performs a registry lookup to verify the distinguished name or convert the short name to a distinguished name before searching for group memberships for that user. If the registry lookup fails, WAS refuses to trust the user. If the registry lookup succeeds, WAS generates a Lightweight Third-Party Authentication (LTPA) token for the user. It stores it as a cookie for subsequent authentication during the user's session.
A TAI is not necessary if the third-party authentication proxy provides native WAS identity tokens, such as LTPA tokens. Currently, only TAM WebSEAL and TAM plug-in for Edge Server provide native WAS identity tokens. Consult the WebSEAL Administration Guide for more information about configuring TAM to provide LTPA tokens. The authentication proxy determines the challenge mechanism.WebSphere Portal relies on the authentication proxy to relay success or failure of the user identifier through the TAI or LTPA token. WAS sees all requests from the TAI as authenticated, but WAS and WebSphere Portal performs a look up on each user anyway. Depending on the TAI and system configuration, WAS and WebSphere Portal can be configured to look up the group also. Even if the authentication proxy has successfully authenticated, WAS and WebSphere Portal deny access if they cannot query the user in the registry.
For example, a user in an External Security Manager is not accessible from WebSphere Portal because it is configured to a different registry. Othat registry does not have the same registry configuration properties as the External Security Manager.

Custom TAIs

TAIs that allow other custom authentication services to interact with WAS can be written. If we use a different security configuration, provide and implement a TAI to communicate with the authentication proxy.
Related
WAS Library
Single sign on to a portal through IBM TAM WebSEAL
TAM TAI (TAI++)
Extended TAM TAI Plus (ETAI)

External authorization

WebSphere Portal always determines the permissione associated with each role, whether the role is externalized or not.
Roles are always associated with a specific resource. Resources can be moved back and forth from internal to external control with the Resource Permissions portlet. Explicit role assignments are preserved when moving in both directions. However, inherited role memberships are blocked for externalized resources. When you externalize access control for a resource, the resource is administered only through the external security manager interface. After externalizing the resource, role membership must be assigned and removed using the external security manager. The Resource Permissions portlet can no longer control user access to the resource; however, the Resource Permissions portlet can move the object back to internal control.
Private pages cannot be externalized.
When we use the Resource Permissions portlet to externalize or internalize access control for a resource, access control for all of its public child resources moves with it. When we use xmlaccess.sh (xmlaccess) to externalize or internalize access control for a resource, access control for public child resources does not change.
After you externalize access control for a resource, use the external security manager to assign users to roles on the resource.
After access control for a resource is externalized, we can use either the Resource Permissions portlet or xmlaccess.sh to create additional role types on the resource.
For example, suppose that you create only the Administrator and Manager role types on the Market News Page. Then you externalize access control for the Market News Page. Use the external security manager to assign users to the Administrator@Market News Page or Manager@Market News Page roles. If you decidto assign users to the Editor@Market News Page role, which is not yet externalized:

Use the Resource Permissions portlet to create the Editor role type for the Market News Page.

Use the external security manager to assign users to the Editor@Market News Page role by editing the ACL.

Remember that WebSphere Portal still determines the permissione associated with the externalized Editor role type.
If a user inherits access to a resource from a parent resource, the user loses the inherited access when the resource is externalized. If the user needs access to that resource, you must assign access through the external security manager.
The user, who externalizes the resource, automatically receives the Administrator role on the parent resource of the externalized resource tree (if using the Resource Permissions portlet) or the resource (if using xmlaccess.sh).
The decision to use an external security manager must be made with the understandinthat the external security manager software's ACL semantics override WebSphere Portal semantics. For example, if we use TAM to grant anonymous membership on a role for an externally controlled portlet, set the ACL for that portlet to include the TAM unauthenticated user group.
If we use TAM for authorization, also use it for authentication. Using TAM to perform only authorization is not supported.

TAM Permissions

In many installations, WebSEAL is behind Portal between the portlets and the back-end servers they access.

Portlets accessing back-end services through an external security manager

Portlets require some method of getting through the ESM to the back-end, and that the portlets can use the Portal credential vault. The portlets are themselves designed to reuse existing security tokens from the Portal security context.

Configure single sign-on for HTTP requests using SPNEGO

We can create single sign-on requests for HTTP servers using the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) available in IBM WAS. This allows users to log in and authenticate only once and receive automatic authentication from WAS.
To enable SPNEGO Web authentication, complete steps in Configure and enable SPNEGO web authentication using the administrative console on the WAS machine
See also:

WAS Information Center: Single sign-on for HTTP requests using SPNEGO web authentication
Re-enabling the SPNEGO TAI
Single sign-on for HTTP requests using SPNEGO TAI (deprecated)

Verify TAIs for authentication

After configuring portal to use an ESM for authentication, verify the TAIs (TAI) are working properly before continuing with any additional configuration tasks.
For IBM TAM, enter the URL in the Web browser address bar...
https://WebSEAL_hostname:WebSEAL_port/junction/wps/myportal

We can also authenticate through the ESMs. After you logging in, you should be directed to the secure and personalized myportal page. If we are directed to the login page or the public page, there is a problem with the TAI configuration. If we are using the TAM TAI (com.ibm.sec.authn.tai.TAMETai or com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus) that WebSphere Portal set up, ensure that the TAM authorization server is up and running.

Change the login and logout pages

By default, when unauthenticated users attempt to access the myportal page, they get redirected to the login page to provide a user name and password. When using a WebSEAL for authentication, you no longer need to use the portal login page. Instead, the login icon should point to the protected portal page.
To change the login and logout pages:
Locate the theme file containing the login and logout links.
In more recent themes, these links might be located in Default.jsp. In older themes, the links might be located in banner.jspf.

Create a backup copy of the theme file.

Open the theme file and locate the section for the login button.
Replace the login button anchor tag that is not commented out with the following JSP fragment:
<%-- comment this to enable screen login --%> 
            <%-- loginOnClick is provided so the client-side aggregation 
theme can add this link without creating a different copy of this file. 
--%>
            <portal-logic:if loggedIn="no">

             <c:if test="${empty loginOnClick}">
             <li class="wptheme-toolbar-last"><a 
href='<portal-navigation:url 
                  home="protected" screen="Home"/>' 
<%=bidiDirAttr%>><portal-fmt:text key="link.login" 
bundle="nls.engine"/></a></li>
             </c:if>
        </portal-logic:if>
        --%>
The previous example uses the 'portal-fmt:' prefix to designate JSP tags from the tag library in portal.tld. Your custom JSPs might use a different tag prefix.
Touch the Default.jsp file after editing any JSP files and before any restart. This updates the timestamp on the file to the current time and will signal a recompile of Default.jsp to incorporate the edit changes from other JSP files. Type: touch Default.jsp. An alternative is to edit (open and save) Default.jsp, which has the same effect as the touch command.

Optional: Redirect the browser to navigate to the logoff page of the ESM after the WebSphere Portal logoff command executes. Learn how to invalidate the single sign on session of the ESM by reviewing the documentation provided by the ESM relating to logoff pages.

TAM WebSEAL provides http://webseal/pkmslogout as a special URL to terminate the WebSEAL single sign on session

To enable WebSphere Portal to execute the ESM logoff URL after completing its logoff command:

Specify the following values in the WP_PROFILE/PortalServer/config/ConfigService.properties file:

redirect.logout=true
redirect.logout.ssl=false or true, depending on the environment
redirect.logout.url=protocol://host_name/logout_page

...where protocol is the protocol of the ESM machine: http or https, host_name is the fully qualified host name of the ESM machine, and logout_page is the ESM page that users will be directed to when they log out. Refer to the ESM Administrator's Guide for information about using logout forms.

On each cluster member, run the following task to update the property:
WP_PROFILE/ConfigEngine
./ConfigEngine.sh update-properties -DWasPassword=foo
Manage access control with ESMs

portal externalizes roles and uses access control to control role membership. From the perspective of the ESM, these externalized roles contain only one permission: membership in the role. WebSphere Portal always determines the permissions associated with each role.
It is not possible to combine the usage of externalizes roles and externalized role mappings with portal managed pages feature. Portal pages cannot be externalized when being edited within a project and externalized resources cannot be added to projects.
For example, if you externalize the Editor@Market News Page role, use the ESM to edit the access control for that role. WebSphere Portal still determines the permissione associated with the Editor role type. Roles are always associated with a specific resource, so the role Editor@Market News Page contains specific permissions on the Market News Page only. Use the Resource Permissions portlet or xmlaccess.sh to move resources back and forth from internal to external access control.
By default, externalized roles appear in the ESM as Role Type@Resource Type/Name/Object ID.
For example, Administrator@PORTLET_APPLICATION/Welcome/1_1_1G.
We can change this format to Resource Type/Name/Object ID@Role type. This format change groups the roles by resource name instead of by role type.
For example, PORTLET_APPLICATION/Welcome/1_0_1G@Administrator. This format change is visible only when the roles are externalized. This change does not affect the way roles are displayed in WebSphere Portal.
The Administrator@VIRTUAL/wps.EXTERNAL ACCESS CONTROL/1 role is never affected by this format change. This role always appears with the role type Administrator.
To manage access control with ESMs:

Use the Resource Permissions portlet to internalize any external roles.

Log on to the WAS admin console.

Modify the WP AccessControlDataManagementService Resource Environment Provider; change the accessControlDataManagement.reorderRoleNames parameter to true.
Add the accessControlDataManagement.reorderRoleNames parameter if it does not exist.

Save the changes and restart the WebSphere_Portal server.

Use the Resource Permissions portlet to externalize the resources you internalized in the first step.

Roles list with reorderRoleNames=false:
Administrator@WEB_MODULE/Tracing.war/1_0_3K
Administrator@PORTLET_APPLICATION/Welcome/1_0_1G
User@WEB_MODULE/Tracing.war/1_0_3K
Privileged User@WEB_MODULE/Tracing.war/1_0_3K
Privileged User@PORTLET_APPLICATION/Welcome/1_0_1G
Roles list with reorderRoleNames=true:
PORTLET_APPLICATION/Welcome/1_0_1G@Administrator
PORTLET_APPLICATION/Welcome/1_0_1G@Privileged User WEB_MODULE/Tracing.war/1_0_3K@Administrator
WEB_MODULE/Tracing.war/1_0_3K@Privileged User WEB_MODULE/Tracing.war/1_0_3K@User
Parent: Securing

Parent: Plan for external security managers