Setup Trellis SSO Proxy using Okta 2019

Introduction
This document describes the procedure to enable a Trellis Proxy to work with Okta SSO. This document does not cover the creation of Okta login
accounts.

Prerequisites
Please have the following available before proceeding with the procedure:

1. Okta Account
2. Okta Admin account capable of adding new application
3. Trellis SSO Proxy installed in a Unix environment
4. Unix user with the read/write access privilege to the install directory of the Trellis Proxy.
5. Okta users are correlated with Trellis users using the Okta user IDs.
6. Important: Create self signed certificate for service provider, see SSO Keystore Generation

Change Log

Date Change Notes

10/7/2019 Initial version.

Step by Step Guide

Register new App to Okta

Login to Okta and go to Admin

Click on Create New App

Enter Application Details and hit "Create"

Enter Application Details and upload logo

Sample Single SigN on URL: https://tallgrassenergylp.trellisenergy.com/ptms/saml/SSO/alias/defaultAlias

Audience URI (SP Entity ID): https://tallgrassenergylp.trellisenergy.com/ptms/saml/metadata. This value is the entityID value of the
service provider metadata.
 Download the Identity Profvider (IDP) metadata.

Configure Trellis Proxy

Configure proxy (Trellis Identity Manager), default directory is /opt/tomcat/tomcat-proxy-sso (do not use tomcat-proxy-auth)
Backup the file: /opt/tomcat/tomcat-proxy-sso/conf/proxy/spMetadata.xml.
Edit the file: /opt/tomcat/tomcat-proxy-sso/conf/proxy/spMetadata.xml.
Update all the hostname and port (i.e in vi, s/trellis-prod.bstonetech.com/myhost.com/g). Make sure that the bottom part of the
XML are up to date. The AssertionConsumerService host and port need to match the "Reply URL" entered above.
Backup the file: /opt/tomcat/tomcat-proxy-sso/conf/proxy/proxy.properties
Edit the file: /opt/tomcat/tomcat-proxy-sso/conf/proxy/proxy.properties
Uncomment userNameStrategy and change the value to SAML_NAME_ID
Add the following lines after showLoginPage=true if not existing

#-- needed by AzureAD to return the email address format for name ID
nameID=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

#-- AzureAD SAML token expiration time: 90 days x 24 hours x 60 minutes x 60 seconds
maxAuthenticationAge=7776000

Copy the IDP entity ID into the idp value like below:
Additional configuration to use file based IDP metadata. For now, this need to be done every time a new WAR file is deployed. The
reason is that we have a common WAR file for Azure and Okta.
 Optional step if going through a reverse proxy or load balancer, edit :./webapps/ptms/WEB-INF/classes/security/samlSecurityContext.xml
:

Test Trellis access

Startup Trellis and Proxy
FAQs
Q: How to enable verbose logging of SAML classes.

A: Edit log4j.properties in /webapps/ptms/WEB-INF/classes/log4j.properties

# Logging of Spring Security extension

log4j.logger.org.springframework.security.saml=DEBUG

# Logging of SAML messages, set to FINEST to enable

log4j.logger.PROTOCOL_MESSAGE=DEBUG

# Logging of OpenSAML library

log4j.logger.org.opensaml=DEBUG

Q: What’s the easiest way to copy OktaMetadata.xml to the server?

A: Run the following commands:

vi /opt/tomcat/tomcat-proxy-sso-okta/conf/proxy/OktaMetadata.xml

:d20

:set paste

(paste from your clipboard)

(shift+zz)

Q: What’s the easiest way to configure proxy.properties?

A: Run the following commands:

sed -i 's/trellis-client\.bstonetech\.com/subdomain\.example\.com' /opt/tomcat/tomcat-proxy-sso-okta/conf/proxy/proxy.properties

Q: What’s the easiest way to configure spMetadata.xml?

A: Run the following commands:

sed -i 's/trellis-client\.bstonetech\.com/subdomain\.example\.com' /opt/tomcat/tomcat-proxy-sso-okta/conf/proxy/spMetadata.xml

Q: How do I create a service for `tomcat-proxy-sso-okta` like `tomcat-proxy-auth`?

A: Run the following commands:

cp /etc/rc.d/init.d/tomcat-proxy-sso /etc/rc.d/init.d/tomcat-proxy-sso-okta
sed -i 's/tomcat-proxy-sso/tomcat-proxy-sso-okta' /etc/rc.d/init.d/tomcat-proxy-sso-okta

Q: How do I fix “-bash: bin/startup.sh: Permission denied” when I start tomcat-proxy-sso-okta?

A: Run the following commands:

chown tomcat:tomcat /opt/tomcat/tomcat-proxy-sso-okta -R

chmod 764 /opt/tomcat/tomcat-proxy-sso-okta/bin/*.sh

Q: How do I fix “org.opensaml.common.SAMLException: Response doesn't have any valid assertion which would pass subject validation” in
/opt/tomcat/tomcat-proxy-sso-okta/logs/trellisAuth.log?

A: Verify in spMetadata.xml’s entyId matches the Okta’s Audience URI.

Useful Links
Google SP and SAML: https://support.google.com/a/answer/6262987?hl=en

Common Issues

1. Unknown User

Exception:
org.json.JSONException: JSONObject["code"] not a string.

at org.json.JSONObject.getString(JSONObject.java:810)
at com.bstonetech.authservlet.authentication.RemoteAuthenticationResult.<init>(RemoteAuthenticationResult.java:37)
at
com.bstonetech.authservlet.authentication.RemoteAuthenticationContentHandler.getAuthenticationResult(RemoteAuthenticationContentHandler.
java:44)
at com.bstonetech.authservlet.authentication.RemoteAuthenticationServlet.addLoginEvent(RemoteAuthenticationServlet.java:54)

Solution:
The user attempting to authenticate isn't in the Trellis system

2. Error message from trellisAuth.log

Exception:
org.opensaml.saml2.metadata.provider.MetadataProviderException: IDP doesn't contain any SingleLogout endpoints
at org.springframework.security.saml.util.SAMLUtil.getLogoutBinding(SAMLUtil.java:116)
at org.springframework.security.saml.websso.SingleLogoutProfileImpl.sendLogoutRequest(SingleLogoutProfileImpl.java:66)
at org.springframework.security.saml.SAMLLogoutFilter.processLogout(SAMLLogoutFilter.java:142)
at org.springframework.security.saml.SAMLLogoutFilter.doFilter(SAMLLogoutFilter.java:106)
at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:342)
at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:192)
at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:166)
at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:342)
at
org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManage
rIntegrationFilter.java:50)
at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:106)
at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:342)
at org.springframework.security.web.context.SecurityContextPersistenceFilter.doFilter(SecurityContextPersistenceFilter.java:87)
at org.springframework.security.web.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:342)

Solution:
Define the Single Logout URL like below. Value will look like this: https://tallgrassenergylp.trellisenergy.com/ptms/public/infopost/getInfoPostingH
ome.do. Make sure to copy the updated IDP metadata XML into the proxy IDP metadata file.