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.
In the Classic UI, select Add Application to start the application wizard.
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.
In the Create New Application wizard, select Web as the Platform type and SAML 2.0 as the Sign on method.
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.
Click Next and finalize the 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.
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.
This opens a form for adding a new Identity Provider to the system.
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.
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.
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.
Scroll down to the section labeled SAML Settings and click the Edit button.
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.
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.