Summary

This document will guide you through the steps to install and enable the PhenixID Plugin for IBM WebSphere external authentication (TAI).

Read more about IBM WebSphere Trust Association Interceptors (TAI) here.

System Requirements

• PhenixID Authentication Server 2.8 or higher
• PhenixID TAI plugin binaries downloaded (please contact PhenixID to receive the binaries)
• PhenixID Authentication Services and IBM WebSphere respective web subdomains must share  domain (ie pas.example.org and ibm-webshere.example.org)

Instruction

Overview

Use case flow:

1. A user attempts to access the IBM WAS application. The PhenixID TAI plugin is called and looks for an active session cookie. If a cookie is not found step 2 is performed, otherwise step 5.
2. The PhenixID TAI plugin module redirects the user to PhenixID Authentication Services for authentication.
3. PhenixID Authentication Services authenticates the user and sets the required session cookies.
4. The user is redirected back to the IBM WAS application.
5. The PhenixID TAI Plugin uses a REST call to PhenixID Authentication Services to verify the received login session cookie. If the cookie is valid a WAS user principal is created and the user allowed to continue. If the session cookie is not valid, step 2 is performed.

Configure PhenixID Authentication Services

Modify authentication flows

1. After successful authentication, redirect to SessionToCookie authenticator. Please view this document for configuration guidelines.

Configure REST endpoint

1. Follow this guide to setup REST endpoint for user verification.
2. Take a note of the REST endpoint URL and tenant values. These will be used in later step.

Configure IBM WebSphere

Install plugin

1. Access the WebSphere Application Server backend (file system).
2. Unzip the binary zip file (containing plugin jars) in <WebSphere Application Server Root>/lib/ext/

Configure IBM WebSphere to use plugin

1. Login to the WebSphere Admin Console
2. Click on Global Security (under the Security menu)
3. From the page that opens, expand Authentication Mechanisms and click on LTPA
4. On the LTPA configuration page, click on the Trust Association link.
5. Select the “Enable trust association” check box.
6. Save the changes.
7. Return to the Trust Association page.
8. Click on Interceptors.
9. Click on New.
10. Enter “com.phenixidentity.tai.pas.plugin.PasTaiPlugin” in the Interceptor class name text entry field.
11. Save the changes.
12. Click on the Custom Properties link and add properties. All mandatory properties must be addedPROPERTIES
    

    Setting Key	Description and default value	Mandatory	Example
    PAS_DEBUG	Boolean value, TRUE|FALSE Should debug information be printed to the log. The default is TRUE,  debugging enabled.	No	FALSE
    PAS_XFWDFOR	Boolean value, TRUE|FALSE Should client ip information be fetched from the X-Forwarded-For header.Defaults to FALSE – client ip is fetched from REMOTE_ADDR.	No	TRUE
    PAS_USER_REGISTRY	String value. Name of the WAS User Registry to be used for matching the user. Defaults to “UserRegistry”.	No	MyUserRegistry
    PAS_SESSION_COOKIENAME	String value. The name of the cookie.Defaults to “access_token”	No	my_custom_value
    PAS_ENDPOINT_URL	String value. PAS REST endpoint URL.  Use value fetched from previous step.	Yes	https://demo.phenixid.net/api/authentication/verifyUser
    PAS_TENANT	String value. PAS tenant value to be sent to PAS REST endpoint. Use value fetched from previous step. Defaults to “tai-ibm”.	No	customer1
    TRUST_ALL_CERTS	Boolean value, TRUE|FALSE Should all PAS REST endpoint SSL certificates (for https) be trusted? Defaults to FALSE.	No	TRUE
    PAS_USERTYPE_HEADERNAME	String value. Header name containing the USERTYPE information. Used in cases where different user types are verified against different endpoints. Defaults to “USERTYPE”.	No	TYPEOFUSER
    PAS_USERTYPE	String value. A double semicolon separated list of <user_type>,<rest_endpoint>	No	citizen,https://pas1.example.org/auth/verif1;;employee,https://pas2.example.org/auth/verifX

     

13. Restart the WebSphere Application Server to activate the new authentication plugin.