Single Sign-On is a useful feature when dealing with multiple applications which are served from different vendors and environments. Third-party identity providers offer platforms which manage the login process. My webMethods Server (MWS) supports integration with third-party identity providers such as Microsoft ADFS, OKTA, etc.
This step-by-step guide demonstrates how to implement OKTA as a third-party Identity Provider (IDP) in order to login into MWS. The implementation is separated in two parts – setting up a free OKTA developer account and MWS setup. It is developed on a Windows 10 VM but is not limited by the OS and can just as easily be done in a Linux or any other supported environment. All file paths assume that the installation is made on C:\SoftwareAG\... with instance name "default". If this is not the case, please replace the path and instance name with your data.
Prerequisites
In order to do this tutorial you will need an MWS installation with version 10.3 or later. The instance must be running on a machine on which you have full control as you will need to use the browser, file explorer and the command prompt.
Okta Developer Account Setup
- Create a free Okta Developer account on https://developer.okta.com/
- Start setting up an Example SAML Application in Okta by following steps 1 to 6 in the guide below: https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta
- Once you get to step 7, enter the MWS URL into the “Single sign on URL” and “Audience URI (SP Entity ID)” fields.
The MWS URL can be copied from the MWS by logging in as Administrator, browsing to Applications -> Administration -> My webMethods -> Cluster Settings -> Advanced or clustered configuration.
For example:
Single sign on URL: https://vmwin1064:8586/
Audience URI (SP Entity ID): https://vmwin1064:8586
NB: Place a forward slash “/” at the end of the Single sign on URL. Also note that the Audience URI field is case-sensitive and does not include forward slash “/” at the end.
- Continue the setup from step 8 as instructed in the Okta website.
- Once the application setup is finished, click on the “General” tab in the top left corner of your Example SAML Application and make note of the App Embed Link.
...
NB: The link is more than one line long. Make sure you select the whole link.
- Download Okta website SSL certificate
For the MWS configuration, you will also need the Okta SSL website certificate. If using Firefox simply click on the padlock next to the Okta URL, click on the right arrow next to “Connection”, then go to “More Information”. In the popup go to “View Certificate”, click on the details tab and then “Export…”. Name the file “oktapreviewcom.crt”
Setting up MWS
- Create an MWS User for the Okta SSO login
Login to MWS with your Administrator credentials and go to Applications -> Administration -> System-Wide -> User Management -> Users and create a new user with a User ID which matches the user assigned to your Okta Example SAML Application. This is typically an email address. For example user@company.com
- Setup MWS for HTTPS
Again logged in as Administrator go to Applications -> Administration -> My webMethods -> Cluster settings and select “Advanced or Clustered Configuration”. Enter port 8586 in the “MWS Front End Secure Port” and “HTTPS port” fields.
- Modify websso.properties file
Browse to C:\SoftwareAG\MWS\bin and execute the following command:
mws.bat -s default getconfig websso.properties
This will export the websso.properties file and place it in C:\SoftwareAG\MWS\server\default\config\
Open the websso.properties file in a text editor and complement the parameters with the following data:
SSO_KEYSTORE=config/security/localhost.p12
SSO_KEYSTORE_TYPE=PKCS12
SSO_KEYSTORE_PASSWORD=manage
SSO_SIGN_ALIAS=localhost
SSO_ENCRYPT_ALIAS=localhost
SSO_ENCRYPT_ALIAS_PASSWORD=manage
SSO_SIGN_ALIAS_PASSWORD=manage
SSO_IDP_METADATA_URL=
Add the Okta metadata URL to the SSO_IDP_METADATA_URL parameter. The Okta medata URL is the “Identity Provider metadata” URL from you Okta App.
The websso.properties file should now look like this:
- Import website SSL ceritificate
Copy the oktapreviewcom.crt file you downloaded on step 6 to C:\SoftwareAG\MWS\server\default\config\security and add the certificate to the sagdemoca.jks keystore file by opening a command prompt in the config folder and running the following command:
“C:\SoftwareAG\jvm\jvm\bin\keytool.exe -import -v -keystore sagdemoca.jks -file oktapreviewcom.crt -alias oktapreviewcom”
The keystore default password is manage
- Optional: Increase log level
Login to MWS as sysadmin and browse to
Folders > Administrative Folders > Administration Dashboard > Analysis > Logging Configuration
Set the logging level of the “org.opensaml” component to TRACE and click Apply to save your changes.
- Restart MWS and verify setup
Restart the MWS server.
When the restart is complete verify that SPMetdata.xml and IDPMetadata.xml have been created in C:\SoftwareAG\MWS\server\default\config. If not, check the MWS server log (_full_.log) for details.
Verify the SSL login by logging in the MWS through the HTTPS URL.
Try it out
Logout from the MWS and the Okta website.
Load the App Embed Link from step 5 in your browser. You should be presented with the Okta App Login page. Once you enter you Okta credentials you will be forwarded to the MWS Start Page where you will already be logged in. Try this from a browser running on the same machine where the MWS is installed first.
Troubleshooting
- Problems logging in to MWS
After setting up the MWS for HTTPS you might not be able to login via http://<MWS_host>:8585 – This is due to a cookie conflict and happens after you login to MWS via HTTPS. Simply use the HTTPS URL or clean your browser cookies. After logging in through HTTPS the problem might return.
- Error in validating SAML Response
The exact error is revealed in the MWS log file (_full_.log). Try increasing the log level if there isn’t sufficient information available (see step 11)
- org.opensaml.common.SAMLException: Response doesn't have any valid assertion which would pass subject validation
and also
org.opensaml.common.SAMLException: Local entity is not the intended audience of the assertion in at least one AudienceRestriction
Check the “Audience URI (SP Entity ID)” entry in the Okta app. The URL is case sensitive and should not include forward slash (/) at the end. Also try using small caps only.
- Error in validating SAML Response:SSOContext is null, cannot process SAMLResponse
Ensure that the Okta website SSL certificate that you saved from the Okta website in step 7 is listed in the sagdemoca.jks keystore. You can verify it by running keytool.exe from C:\SoftwareAG\MWS\server\default\config\security as follows: C:\SoftwareAG\jvm\jvm\bin\keytool.exe -list -keystore sagdemoca.jks
- Files SPMetdata.xml and IDPMetadata.xml are not being created in C:\SoftwareAG\MWS\server\default\config during MWS startup.
Check the URL in the websso.properties file (does it load in a browser window) and also the SLL certificate in sagdemoca.jks (see step 16).
Notes
Audience URI is small/large caps sensitive
Audience URI should not have forward slash at the end (i.e. https://example.com and not https://example.com/)
You can’t use the IP address of the MWS machine in the Okta app config.
Resources
Creating OKTA Developer account: https://developer.okta.com/
Settting up sample application in Okta:
https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta
SAML basic principles: https://www.okta.com/integrate/documentation/saml/
Security Assertion Markup Language (SAML) V2.0 Technical Overview: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
"10-3_Administering_My_Webmethods_Server.pdf" page 297 - Configuring Single Sign-On for Using a Third-Party Identity Provider