Configuring SAML SP with Okta.com

Update (2/18/2022) There is a new and updated guide to OKTA located here: Configuring OKTA

In this guide, we will configure the SAML SP Plugin for CraftCMS using Okta.com as the IDP. To follow along, you must have an Okta account. You must also have Flipbox Digital’s Saml SP plugin for CraftCMS installed on your site. Head over to the docs for installation instructions.

Here is a quick overview of what we are going to do:

1. Create your site’s metadata
2. Create the IDP’s/Okta’s metadata

1. Create Your Metadata

Metadata is an XML document that defines your provider’s SAML configuration. From the root of the SAML SP plugin, click the menu item labeled “My Provider”. To create your metadata, first click the generate key pair which will create a private and public key for you to decrypt and sign messages. You can also manage those keys manually if desired by creating one with OpenSSL or creating it on your computer, then uploading it into the KeyChain area in the SAML SP plugin.

When you generate the key pair it automatically associates it to your metadata. Verify the Provider Type is set to Service (SP) which is the role of your site plays. Click save to create and move onto the next step.

Craft - Create My Provider

2. Create the Identity Provider's Metadata (OKTA's Metadata)

Now we must generate Okta’s metadata by creating an app with in their admin console. Once logged-in to Okta, goto the “Applications” and click the “Add Application” button to create a new Okta application. Then click the “Create New App” and select “SAML 2.0” as the “Sign on method”. I will name my app “My CraftCMS IDP”.

Now we need our provider settings. Within the CraftCMS control panel, goto the to the SAML SP plugin, then to “My Provider”. We’ll configure the Okta app using the values displayed within “My Provider” which I will refer to as Craft.

Okta - Add Application

Okta - Create General Settings

Entity and Endpoints

The first configuration to add to Okta is “Single sign on URL” which can be copied from the “Assertion Consumer Service: ACS” value in Craft. Then, for the “Audience URI (SP Entity ID)” in Okta, copy the “Entity ID” in Craft. Back in Okta, leave “Default RelayState”, “Name ID”, and “Application username” to default, and expand the Advanced Settings.

Okta - Entity and Endpoints

Advanced Settings

Within Advanced Settings, we’ll leave everything as default but “Enable Single Logout”. Then add “Single Logout URL” and “SP Issuer” by copying “Single Logout Service: SLO” and “Entity ID” from Craft. In Craft, Click “Download Certificate” link which will download it to your computer. In Okta, select and Upload the downloaded .crt file for “Signature Certificate”.

Okta - Advanced Settings - SLO and Certificate Upload

User Attributes

Now we can add the Okta user attributes we want send to Craft. These attributes will sync with the user on login. CraftCMS requires an email so make sure it is mapped here. For now, we’ll use the default configuration on both sides and map the following in Okta:

Name

Value

firstName (unspecified)

user.firstName

lastName (unspecified)

user.lastName

email (unspecified)

user.email

The above works out-of-the-box with the SAML SP Plugin. More configuration options can be found in the documentation.

Okta - Attribute Statement

Group Attributes (Optional)

Within Okta, you can send the user’s Okta groups to Craft as well. In my Okta configuration, I added three groups. Okta provides an option to send all groups the user is a part of with matching logic. I have my groups all prefixed with the word Craft so I’ll use “Starts with” to match them if the user is assigned. By default, SAML SP will automatically check for an attribute named "groups" which can contain an array of group names the user is assigned to. By default, groups are configured to automatically be created in CraftCMS if they don’t exist. See configuration documentation for more on group configuration.

Name

Value

groups (unspecified)

(Starts with) Craft

Okta - Group List

Okta - Group Attribute Statement

Copy IDP Metadata

Finally, click through to finish the Okta app creation wizard. We are now presented with a “View Setup Instructions” button. Click that button to review this app’s configuration including the metadata at the bottom under “Optional”. Select the entire XML document and copy it to your clipboard.

Okta - Copy Metadata

Assignments

While in the Okta admin and the newly created app, click the “Assignments” tab and add users or groups to the app. Add your own user so you can test the configuration. I’m adding my Craft groups which contains my user.

Okta - Assign

Okta - Assign Groups

Save IDP Metadata

In Craft from the SAML SP control panel, goto the “Provider List” and click “+ Add Remote Provider”. Add a label that let's everyone know who the IDP is and what it's purpose is. For example, "Okta Production". Paste the metadata XML into the “Metadata XML” text field and save. Then, click on the "Configure" tab and map the attributes configured earlier in Okta to the corresponding CraftCMS Properties.

CraftCMS - Add IDP Button

CraftCMS - Paste the IDP's Metadata into the Metadata field

CraftCMS - Map Attributes from Okta to CraftCMS Properties

Configure `loginPath`

After saving Okta's Metadata as the IDP, return to that provider within CraftCMS and copy the Login Path from the "Configure" tab. That can take the place of the General Config's `loginPath` within your `config/general.php` file. When a user hits a page where `{% requireLogin %}` is present, the user while be redirected to the IDP (in this case Okta) to login there and redirected back to the intended page.

Test It Out!

Now you can test the configuration and login using federated authentication!

I hope you enjoyed the guide and are excited to dive more into the plugin and SAML.