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:
- SimpleSAMLphp has to be accessible as a webroot, and not just as the root endpoint. So
/simplesaml
has to be accessible instead of just/
. - 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/simplesamlphpCOPY 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:
- 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.