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 Iconik Domain Owner and an administrator in your OKTA domain. Start by logging into OKTA and go into the Admin interface.
Under the Applications menu select Create App Integration and select SAML 2.0 to start the application wizard.
The Wizard will then ask for a name and an optional logo for your application. That is what will be displayed in the Okta application list for your end users. Enter iconik and upload a logo if you want to.
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 and then Finish to finalize the setup. You do not have to fill out the form in the last page.
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.
Copy the data in the field, and create a new XML document. Paste in the data to the document and save it to your hard drive. You might want to resize the text box with the XML to get all the text.
Optionally you can curlor wget the Metadata URL which also gives you the XML.
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. Press Next to get to the Configure SAML section.
Now, copy the information from Iconik into Okta like so:
| Field in Iconik | Field in Okta |
Assertion Consumer Service |
Single Sign on URL |
Entity Id |
Audience URI (SP Entity ID) |
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 propagate 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.
Multi-region OKTA apps
You may want to configure separate apps for the different Iconik data centers (US vs EU). Setting up apps for each region will allow you to sign in to a specific region.
To setup an Okta app for the US region, sign in to https://us.iconik.io and go through the flow above. The URLs that you receive from Iconik to put into Okta will show https://us.iconik.io/API/saml...
For the EU region, sign into https://eu.iconik.io and go through the flow above. The URLs you recieve from Iconik to put into Okta will show https://eu.iconik.io/API/saml...