SAML Authentication

iconik supports authentication via SAML2.0 and this allows you to connect to external authentication such as OKTA, OneLogin, Microsoft ADFS or Google G-Suite.

Overview

With iconik's SAML 2.0 integration you can tie authentication and authorization of your users to an external data source, such as an Active Directory or other enterprise directory service. This guide will explain how to set up SAML 2.0 integration with OKTA, Microsoft ADFS and Google G-Suite. If you need assistance configuring authentication with another source then please contact support.

Terminology

This section introduces some SAML terms and what they mean in iconik.

Identity Provider (IdP) : An entity which authenticates the user and provides claims about the users identity and attributes.

Service Provider (SP) : An entity which provides a service to the user (iconik) in this case.

Principal : The iconik user

Claim : An attribute of the user's identity, such as a first or last name, an email address or group membership.

User provisioning

iconik supports Just-In-Time provisioning of users where the user is created in iconik on first login. You can also create users manually ahead of time and connect them to a specific IdP on the user settings page. Once configured the user will be presented with an option to log in via the IdP on the iconik login page.

Group management

If your IdP has the option to send group membership as SAML claims iconik is able to consume these and provision group membership automatically. A user who logs in will become a member of User Groups in iconik when the iconik User Group name matches group names sent from the IdP. Users will also be removed from groups in iconik if they are removed from the corresponding groups on the IdP side upon the next login to iconik.

You can mix IdP managed groups and iconik-managed User Groups freely as long as the iconik-managed User Group doesn't match a group name that is defined in the IdP - if it matches it becomes managed by the IdP. This allows the application administrator to control certain aspects of application access if they choose to.

Primary Group

iconik uses a user's primary group to provision certain settings. With automatic user provisioning via SAML you have the ability to control which group gets assigned as a user's primary group. On the group settings page, each group has a configuration option called "SAML Primary Group Priority". When a user logs in, iconik will pick the group the user is a member of with the highest priority value and set this as the user's priary group. New users will also be created with the user type selected on this group. This allows you to configure different default user types and permissions depending on the groups the user is a member of in your IdP.

Login options

SAML definies two distinct methods for triggering the login flow, SP- and IdP-initiated login. iconik supports both these methods out-of-the-box and which one to use depends on which Identity Provider you use and what login method your users are used to.

IdP-initiated login

IdP-initiated login means that the login starts with the Identity Provider. This is often done through some kind of application portal where the user can see all the applications they have access to. The user then selects the application and is then redirected to the application with proof of their identity.

OKTA, OneLogin and Azure AD have application portals where users can trigger IdP-initiated login flows while other IdPs may not have this. It's also possible that your users haven't been used to logging into the IdP to find their application and then an SP-initiated login flow may be more appropriate.

SP-initiated login

SP-initiated login means that the login starts with the application. The user is redirected to the IdP and is then redirected back to the application with proof of their identity once the IdP has verified the user's credentials.

For SP-initiated login you can select a few different options:

You can manually created users and associate them with an IdP. This association can be done on the user settings page where you can select the IdP under "Authentication Settings"
You can give your users the Login URL which you can find on in information box the IdP Settings page. This Login URL is specific for your IdP and will redirect users to your login page.
It is also possible to associate an entire email domain to an IdP. With this option, any email address in your domain will be redirected to your IdP even if the user doesn't yet exist in iconik. This is only possible with business domains and we do not allow generic domains such as hotmail.com or gmail.com to be used with this option. The benefit of this last option is that users who don't yet exist in iconik will still be able to enter their email address and will have an account created transparently. This option can only be set up by iconik support so please send an email to support@iconik.io from the email address of an administrator user in your iconik domain with details on which email domain should be configured, and which IdP (if you have multiple).

Security considerations

One benefit with setting up SAML integration is that iconik only has access to the email, name and group membership of the user. The user's password or other authentication token is only handled by the user's browser and the IdP.

No firewall needs to be opened to transfer the authentication information from the IdP to iconik. All information is transfered through the user's browser so as long as the user can access both the IdP and iconik they can log in. This means that the endpoint used by the IdP can reside on your internal network without the need to expose it to the Internet.

Configuration

SAML requires setup both on the IdP side and the SP side of an integration. Your IdP likely provides its own documentation on how to configure the SAML 2.0 integration but but we provide walk-throughs for the most common Identity Providers.

New iconik configuration

Click on ADMIN in the top navigation.
Choose Settings from the left navigation bar.
Choose Identity Providers from the menu that appears.
Click + NEW IDENTITY PROVIDER.
Choose the Identity Provider from the list. If yours isn't available choose GENERIC.
Fill in the parameters as provided by the provider.
1. Alternatively upload a IDP metadata XML
Click

Roles