This post details on how to configure Websphere 7.x version for SAML SSO to authenticate users in Maximo application
What is SAML ?
- Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context
- Most organizations already know the identity of users because they are logged in to their Active Directory domain or intranet, So they use this information to login into Maximo
- SAML SSO works by transferring the user’s identity from one place (the identity provider) to another (the service provider)
- When the user accesses the Maximo URL, the application identifies the user's origin, then redirects the user back to the Identity provider for authentication
- The user either has an existing active browser session with the identity provider or establishes one by logging into the identity provider
- The identity provider (AWS or Azure) builds the authentication response in the form of an XML-document containing the user’s username or email address, signs it using an X.509 certificate, and posts this information to the service provider
- The service provider (Maximo) retrieves the authentication response and validates it using the certification and metadata
- The identity of the user is established and the user is provided with Maximo access
1. Login to the operating system where WebSphere is
installed
2. Install
the default SAML ACS (Assertion Consumer Service) servlet supplied with
WebSphere
- If using Windows, open a command prompt
- Navigate to WAS application bin directory (/opt/IBM/WebSphere/AppServer/bin on Linux/Unix or C:\Program Files\IBM\WebSphere\AppServer\bin on Windows)
- We can install SAML ACS to a cluster or single-server. Please run the following command:
|
Operating System |
Command |
|
Windows |
wsadmin.bat -lang jython -f installSamlACS.py install clusterName (or) wsadmin.bat -lang jython -f installSamlACS.py install nodeName serverName |
|
Linux/Unix |
(or) ./wsadmin.sh -lang jython -f installSamlACS.py install nodeName serverName |
- If you are using a web server such as IBM HTTP Server in front of your application be sure that the newly installed EAR is targeted to the web server
- Using the left-hand menu go to Applications and then WebSphere enterprise applications
- Click the link for WebSphereSamlSP
- Under Modules click Manage Modules
- Confirm that both the cluster and the web server are assigned to the module
- Using the left hand side menu, go to Servers, then Server Types and click Web Servers
- Click the checkbox next to your web server and click Generate Plug-in from the toolbar menu
- Click the checkbox next to your web server and click Propagate Plug-in from the toolbar menu
- Restart the web server
- Using the left-hand menu, select Security then Security Domains
- Click New
- Provide a name and description for security domain
- Click OK
4. Confirm that Application Security is enabled
- From the list of Security Domains, click the new domain you created
- Check the value next to Application Security. If the value is Enabled then you can continue on to step 5
- Expand the Application Security section and select Customize for this domain
- Enable the Enable application security checkbox and click Apply
- From the list of Security Domains, click the new domain you created
- Expand the Trust Association section and select the Customize for this domain option
- Click to enable the Enable trust association checkbox and click Apply
- Click the Interceptors link under Trust Association
- Click New
- For the Interceptor class name enter com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
- Under Custom Properties enter the property name sso_1.sp.acsUrl with a value of your ACS URL
- Click New to add an additional property
- Enter the name sso_1.sp.EntityID and provide a value for the SP entity ID and click OK
6. Save settings and synchronize nodes
7. Export SAML SP metadata
- Navigate to the WAS application bin directory (/opt/IBM/WebSphere/AppServer/bin on Linux/Unix or C:\Program Files\IBM\WebSphere\AppServer\bin on Windows)
- Launch the wsadmin tool
|
Operating System |
Command |
|
Windows |
wsadmin.bat -lang jython |
|
Linux/Unix |
./wsadmin.sh -lang jython |
- Execute the following command
AdminTask.exportSAMLSpMetadata('-spMetadataFileName sp_metadata.xml -ssoId 1 -securityDomainName DOMAINNAME')
- DOMAINNAME --> should be the same name which is created on Step 3
- By default, metadatafile will be stored in this path "/opt/IBM/WebSphere/AppServer/profiles/ctgDmgr01"
- Target URL of the application
- IdP will provide its signing certificate inside the metadata file or request it separately and import it manually later
- Please validate the certificate in the signature KeyInfo element of the assertion from IdP provider
- Launch the wsadmin tool using step 7
- Execute the following commands
- AdminTask.importSAMLIdpMetadata('-idpMetadataFileName idp_metadata.xml -signingCertAlias MyCertAlias -securityDomainName DOMAINNAME')
- AdminConfig.save()
If
the idp_metadata.xml file is not in the same path as the wsadmin
tool, then you will need to specify the full path to the file.
The value for signingCertAlias can be any string; it will be used to identify the signing certificate in the WebSphere Trust Store so just choose a suitable name that is not already in the store (see Security > SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates for a list of keys already in the store)
DOMAINNAME - should be the same name which is created on Step 3
- Exit the wsadmin tool and return to the WebSphere Admin Console
- Using the left hand menu, select Security and then Security Domains
- Click the link to your security domain
- Expand the Trust Association section and click the Interceptors link
- Click com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
|
Property |
Value |
|
sso_1.sp.acsUrl |
value set in Step 5 - https://hostname/samlsps |
|
sso_1.sp.EntityID |
value set in Step 5 - https://hostname/ |
|
sso_1.sp.targetURL |
https://hostname/maximo/webclient/login/login.jsp |
|
sso_1.idp_1.certAlias |
name of the certificate alias you provided in point 9 |
|
sso_1.idp_1.entityID |
entity ID of the IdP which is provided in the IdP metadata
file and will be automatically populated |
|
sso_1.idp_1.singleSignOnUrl |
URL endpoint for IdP authentication (automatically populated
from metadata) |
sso_1.sp.filter – this is an optional property. We can
filter out servers that can be exempted from using SSO. Usually, we
enable SSO only for UI server, and filter out MIF/CRON/REPORT servers.
If
you do not see the sso_1.idp_1.certAlias property then a certificate was not provided
with the metadata file. We will need to obtain the certificate from the IdP and add it to WebSphere
manually by going to Security > SSL certificate and key management
> Key stores and certificates > CellDefaultTrustStore > Signer
certificates and clicking Add.
Once imported, you will need
to add a custom property to Trust Association Interceptor TAI - sso_1.idp_1.certAlias and assign it the value of the new certificate
alias you created
11. Finalize Security Domain setup
- Using the left-hand menu select Security and then Security Domains
- Expand User Realm, click the Customize for this domain radio button
- Click Apply at the bottom of the screen and save changes
- Go back to the Security Domain, expand User Realm (it should already be set to Customize) and click Configure...
- If you are not taken to the Trusted authentication realms - inbound page automatically then click the associated link in the lower right part of the screen (under Related Items)
- Click the Add External Realm... button in the toolbar
- Enter the value of the sso_1.idp_1.entityID from point 10 and click OK
- Click Apply and save changes and return to the security domain configuration screen by following steps
- Click the Custom Properties link at the bottom of the screen
- Add the following two properties:
|
Property |
Value |
|
com.ibm.websphere.security.DeferTAItoSSO |
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor |
|
com.ibm.websphere.security.InvokeTAIbeforeSSO |
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor |
- Click OK and save changes
12. Assign security domain to servers or clusters
- Assign server/cluster where WebSphereSamlSP.ear was deployed in point 2
- Proceed to the security domain configuration screen as described in point 11
- Under the heading Assigned Scopes expand the tree starting at Cell
- Locate the server(s) or cluster(s) where you would like to enable SSO and click each one to enable it. If you are not using clusters then your servers will appear under the Nodes section. If your servers are in clusters then you must look under the Clusters section
- Enable all appropriate servers click the OK button at the bottom of the page and save your changes
14. Test SSO using the login URL provided by your IdP
Debugging
- To debug issues with SAML, we need to enable trace logging on the server where the SAML ACS servlet has been installed
- By default, WebSphere provides no feedback in the standard logs for most SSO issues
- If you are troubleshooting SAML in a cluster where multiple servers are running it’s recommended you stop all but one server to simplify diagnosing your problem
- To enable trace logging for the server where the ACS servlet is installed, login to the WebSphere Admin Console and do the following
Using the left-hand menu select Servers then Server Types then WebSphere application servers
Locate the server where you installed the ACS servlet in point 2 of the Step-by-step guide and click it
Under Troubleshooting on the right side click Diagnostic trace service
Under Additional Properties click Change Log Detail Levels
Add the following log levels, separating each with a colon : com.ibm.ws.security.*=all: com.ibm.wsspi.wssecurity.*=all: com.ibm.ws.wssecurity.saml.*=all:
- Click OK and save your changes
- Restart the server where you have enabled trace logging
- Now test your SSO flow again and view the trace.log file in the log folder of your server for errors
- The messages will generally give some indication of where the problem lies but you may need to find a proper person to escalate to if you cannot determine the problem
