SimpleSAMLphp and Okta

At Spatial Networks we have implemented a single sign-on (SSO) solution using the provider Okta. To that end, access to all internal applications should be through Okta and not the individual applications.

This post will cover how to set up and test SimpleSAMLphp and SSO provider Okta. There have been many different walkthroughs and examples of how to use each but I always had issues getting those solutions to work with my setup. After a LOT of painstaking trial and error (and starting over 2–3 times) I finally have a full understanding of what is needed, and I figured others might find this information useful.

Some general information and assumptions:

1. SimpleSAMLphp has to be accessible as a webroot, and not just as the root endpoint. So /simplesaml has to be accessible instead of just /.
2. Any application which needs SAML interactions will also need to live under a sub endpoint (not the root). For example, if the application ‘foo’ is what needs SSO, then the url /foo needs to be where the foo application is hosted.

As this journey evolved from a simple idea of “implement Okta SAML SSO” into an existing web application into a full-fledged deep dive into the configurations not only of the web application but also of SimpleSAMLphp, the level of frustration also kept evolving from mildly irrational to full-blown rage and back again.

Create an Okta Application

Before we can test SimpleSAMLphp we first need to create an Okta application. To set up the application, follow the setup guide: Okta Saml Application Setup page.

There are a few things to customize when setting up the Okta application:

In step #6: Use SimpleSAMLphp Example instead of “Example SAML application”

Use the following URLs:

Single Sign on URL: http://localhost:9000/simplesaml/module.php/saml/sp/saml2-acs.php/example-okta-com

Audience URI (SP Entity ID): http://localhost:9000/simplesaml/module.php/saml/sp/metadata.php/example-okta-com

For ‘Relay State’ leave that URL empty.

Make sure to note the URL of the Identity Provider metadata. An example url is: https://<OKTA_DOMAIN>.okta.com/app/exk1a7yyyyyxxxxxx/sso/saml/metadata

Setup and Verify SimpleSAMLphp

For this example, we will be running SimpleSAMLphp as a Docker container. Luckily, there is already an existing image `unicon/simplesamlphp` which has already done the hard work of installing and configuring SimpleSAMLphp and apache.

First let's make sure the configuration works:

docker run -p 9000:80 unicon/simplesamlphp

Now navigate to the url http://localhost:9000 and you should see the Apache testing page

If that page successfully renders, let’s move on to /simplesaml (http://localhost:9000/simplesaml)

If everything is rendering correctly, then we have a working installation for SimpleSAMLphp. Time to add Okta.

Customizing SimpleSAMLphp and Okta Configuration Files

Up to this point, the public Docker image has been sufficient, but going forward we will have to build a custom Docker image to account for the new updates. For this, we will utilize the Github repository https://github.com/jwitrick/okta-mediawiki

git clone https://github.com/jwitrick/okta-mediawiki.git
cd okta-mediawiki/okta-simplesamlphp

Edit the configuration file simplesamlphp/config/config.php

• Search for enable.saml20-idp and change the value to true
• Search for auth.adminpassword and change the value to a secure password
• Search for secretsalt and change the value to something random

Building a Docker Image

The repository comes with a Dockerfile which will build a custom Docker image.

The contents of the provided Dockerfile are:

from unicon/simplesamlphp
COPY simplesamlphp/saml-autoconfig.php /var/simplesamlphp/
COPY simplesamlphp/config/config.php /var/simplesamlphp/config/
COPY simplesamlphp/config/authsources.php /var/simplesamlphp/config/
COPY simplesamlphp/metadata/saml20-idp-remote.php /var/simplesamlphp/metadata/

To build the image using the newly created Dockerfile

docker build -t okta-simplesamlphp .

Running the new image:

If you have not already stopped the running simpleSAMLphp docker container, please do so.

There are 2 ways we can run the newly created Docker image:

1. Manually using just Docker:

docker run -p 9000:80 -e SIMPLESAML_PATH=/simplesaml/ -e BASE_URL=http://localhost:9000 -e OKTA_METADATA_URL=<URL_FROM_OKTA> okta-simplesamlphp

2. Using Docker-compose:

Edit the file stack.yml and replace:

OKTA_METADATA_URL: 'https://<REPLACE_WITH_YOUR_SPECIFIC_SAML>/sso/saml/metadata'

With the proper URL from Okta.

Then run:

docker-compose -f stack.yml up

For information on installing docker-compose please see the installation guide.

At this point, we can test the SimpleSAML interactions with Okta.

Testing SimpleSAML and Okta

In a web browser navigate to:

http://localhost:9000/simplesaml/module.php/core/frontpage_auth.php

Click on the link Test configured authentication sources

On the Test authentication sources page, you will see a list of all configured authentication sources.

As you can see above the authentication source previously configured (example-okta-com) is listed as an authentication source. If everything is set up correctly, when you click on example-okta-com it should take you to the Okta SSO login page.

Conclusions

In this wiki we walked through how to set up and configure SimpleSAMLphp and Okta. During my initial testing and configuration, I ran into frustration after frustration with the proper values and settings, but like most things, once it works I was able to scale down all my missteps into the simple steps listed above.

Hopefully this has been a useful walkthrough, and will make your life easier. Stay tuned for how to utilize these steps to connect an external application (MediaWiki) to Okta.

There is a public Docker image available on DockerHub (jwitrick/okta-simplesamlphp) which is built from the below instructions and is available to be used directly.