Roles

These are the roles that are needed:

  • Admin

Links

OKTA

OKTA is an identity provider allowing you to build different kinds of authentication workflows. You can read more on https://okta.com

Create the OKTA app

In order to configure OKTA in iconik you need to be an administrator both in iconik and in your OKTA domain. Start by logging into OKTA and go into the Admin interface and switch to the Classic UI in the upper left corner. This is needed to configure SAML 2.0 as of the time of this writing.

OKTA Admin UI

In the Classic UI, select Add Application to start the application wizard.

OKTA Classic UI

Once in the Classic UI, you can select Create New App on the left sidedbar. An iconik app is on the way for OKTA, simpliyfing this configuration.

OKTA Add Application

In the Create New Application wizard, select Web as the Platform type and SAML 2.0 as the Sign on method.

OKTA Create New Application

In the next step of the wizard, you need to add placeholder values for Single sign on URL and Audience URI. These are needed to allow us to create the application in OKTA and extract the required fields in order to configure iconik. Once iconik is configured we will come back to OKTA and finalize the configuration.

OKTA Placeholder Values

Click Next and finalize the setup.

OKTA Finalize setup

This brings you to the Settings page in OKTA where you can select View Setup Instructions which takes you to a page with all the information needed to configure iconik. The relevant section is in the Optional section at the bottom of the page, titled Provide the following IDP metadata to your SP provider. Make a copy of this XML and save it to a file on your local hard drive.

OKTA Settings Page

OKTA View Setup Instructions

iconik configuration

As the next step, make sure you are logged into iconik as an administrator. Go to the Identity Providers page under the Admin menu and click New Identity Provider in the upper right hand corner.

Identity Provider list

This opens a form for adding a new Identity Provider to the system.

Identity Provider empty form

There are two options, either to fill in the information manually, or to use the XML saved in the previous step to automatically populate in the form. We are going to show the latter in this guide, so click Chose file in the first section of the form and select the file you saved earlier with the metadata from the OKTA IdP. This will fill out the form with all the required information.

Identity Provider filled form

Click Create at the bottom of the form to add the new integration to your organizational account. You can now open the settings page for the newly created Identity Provider.

Identity Provider settings

We will use settings from the information box on the left to configure the OKTA side of the integration, specifically the URLs for Entity ID and Assertion Consumer Service. You can copy both of these to your clipboard by clicking on the copy icon to the left of each setting. The Login URL can be used to trigger an OKTA login for example from a corporate portal or via a browser bookmark.

Finalizing the OKTA configuration

Now, go back to the OKTA admin interface for you iconik App and go to the General tab.

OKTA General Settings

Scroll down to the section labeled SAML Settings and click the Edit button.

OKTA Edit SAML Settings

Now, paste the url you copied from Assertion Consumer Service into the Single Sign on URL in OKTA and copy the value from the Entity Id into the Audience URI (SP Entity ID) field. You can leave Default RelayState blank.

Select EmailAddress as the Name ID format and Email as the Application username as iconik uses email addresses to identify users.

Attribute mapping

The final step is to set up which attributes should be sent from OKTA.

OKTA SAML Attributes

The only attributes which are supported currently in iconik are first_name, last_name and groups and these can be set up using OKTA's configuration language. On the left side of the attributes table are the names iconik expects while on the right side is the expression in OKTA's expression language. The recommended settings are:

Name Name Format Value
first_name Unspecified user.firstName
last_name Unspecified user.lastName

This allows iconik to populate the users' full name with the information available in OKTA. The user's email address does not need to be included here since it has already been provided via the NameID attribute above.

You can also propagate group memberhip via the groups SAML attribute. Groups in iconik are not created automatically. They must be created by an administrator, but if a group with the same name as a group which exists in OKTA and is propagated to iconik then the user will be added as a member of that group when they log in via SAML.

To propagate all group memberships, you can select the Matches regex filter type with the value .* to propagete all groups to iconik. If security or business reasons requires restricting this list then please refer to the OKTA documentation or contact support for assistance.

You can now save the OKTA app, assign it to the relevant user group and then log in to iconik via the OKTA dashboard for IdP initiated logins, or via the Login URL from the iconik Identity Provider settings page for SP initiated logins.

Learn more