The Okta setup is separated into two parts. Firstly the steps that need to be performed on ISL Conference Proxy (ICP) are shown, followed by the steps that need to be performed on Okta and at the end the steps that need to be performed on ISL Conference Proxy (ICP) are shown again. Please refer to the relevant part:
- Create a new domain on ISL Conference Proxy
- Setup - Okta
- Setup - ISL Conference Proxy
- Sign In - Web
- Sign In - Application
Create a new domain on ISL Conference Proxy
Step 1
Login to your ISL Conference Proxy configuration page.
Step 2
Create an additional domain for Single Sign-On users. A new domain can be created under "User management" -> "Domains" -> "Create domain".
Step 3
In this example, we have created a domain "external".
Setup - Okta
Step 1 (Create new app integration)
Sign in to the Okta Admin portal using your Okta administrator account and navigate to the "Menu" -> "Applications" -> "Create App Integration" and select SAML 2.0.
Step 2
Enter the name of the application (e.g. ISLConferenceProxy) and click Next.
Step 3
Set the following fields:
Single sign-on URL (ACS): https://isl.example.com/sso/saml/sp/domain/<domain>/acspost
Audience URI (SP Entitiy ID): https://isl.example.com/sso/saml/sp/domain/<domain>/metadata.xml
Note: Leave the "Use this for Recipient URL and Destination URL" default (checked) unless you have a specific configuration.
Step 4
Set the following fields:
Primary email (optional): email
First name (optional): first-name
Last name (optional): last-name
Group membership (optional): groups
Note: In larger organizations the number of groups a user is a member of may exceed the ISL Conference Proxy limit, that is 100 groups per user. If your user's group membership count exceeds this limit, we recommend restricting the groups emitted in claims only to the relevant groups for the application.
Store the SAML claim names (left-hand side column on the screenshot above) as you will need to include them in the next part of this manual.
Step 5
Look over the final inputs and click Finish.
Assign users to the application
Users must first be assigned to the application before being able to access it. Go to the Assignments tab and select Assign to select what People or Groups will have access to your ISL Online Cloud application.
After you configure the application assignments, click Done.
Get Okta metadata XML URL
Navigate to the Sign On tab and scroll to Sign on methods. Copy and store the metadata URL as it will be used in Step 4 of the ISL Conference Proxy Setup.
Setup - ISL Conference Proxy
Step 1
Generate Service Provider (ICP) key-pair (public certificate file and private key). These keys will be used when the Service Provider (ICP) communicates with the Identity Provider (Okta). The simplest way of generating the key-pair is using the OpenSSL tool and issuing the commands below. In the first and the second command replace the domain with your domain that you have created on ISL Conference Proxy and in the second command replace the isl.example.com with your ISL Conference Proxy server address.
openssl genrsa -out sso_saml_domain_sp.key -aes128 2048 openssl req -x509 -key sso_saml_domain_sp.key -out sso_saml_domain_sp.cert -days 3650 -subj "/CN=isl.example.com"
Important: ISL Conference Proxy supports the traditional PEM format (Non PKCS 8). If you are generating a key with OpenSSL 3.x.y, which generates the PKCS 8 by default, use the -traditional flag.
openssl genrsa -traditional -out sso_saml_domain_sp.key -aes128 2048
Step 2
Upload the key-pair (from Step 1) to ISL Conference Proxy Private File storage. You can access Private File storage by opening “ISL Conference Proxy web administration" -> "Configuration" -> "Advanced" -> "File storage" -> "Private”.
Step 3
Configure the ISL Conference Proxy to use the uploaded files in Step 2 for SAML communication. Settings are found under "User management" -> "your_domain" -> "Security". To access files placed in Private storage you have to append "objects/" before the filename.
Important: For the "SAML service provider PEM key file passphrase" enter the passphrase that you entered when generating the key-pair in Step 1.
Step 4
On the same page configure the setting "SAML identity provider XML metadata URL" with the URL that you have stored in Get Okta metadata XML URL part of this guide and select "Save" at the bottom of the page.
Important: Replacing the Identity Provider metadata XML file on your ISL Conference Proxy requires restart of the module apps. Navigate to “ISL Conference Proxy web administration" -> "Activity monitor" -> "Servers", select each server, and click "Restart module apps" one by one.
Step 5 (optional)
Enable additional logs in the Core Login module for easier debugging. Under "Configuration" -> "Logs" set the following settings to log anything with a severity greater than 6 (info):
- Log subsystem [Core Login] Application web login severity report level
- Log subsystem [Core Login] Login dialog severity report level
- Log subsystem [Core Login] Single sign-on: SAML severity report level
Step 6
Set SAML login setting rules under "User management" -> "your_domain" -> "Security". These settings specify how claims obtained via SAML are mapped to ISL Conference Proxy user profile settings. An example configuration looks like this:
[ ["key-from-attr", "realname","first-name", " ", "last-name"] ,["key", "user_profile::name", "0"] ,["key-from-attr", "email", "email"] ,["key", "user_profile::email", "0"] ]
Step 7
On the same page enable the setting "Organization login enabled", set the "Organization name" and "Organization description". You can set custom name and description, make sure that name and description are unique in order to avoid confusion for users upon logging in.
Step 8
Navigate to "Configuration" -> "Security", find settings "Login layout" and "Organization login layout" and set them to settings that will suit your use case. In our case we've set the settings to "Username & Password, Organization" and "Description vertical chooser".
Important: If you are going to set "Login layout" setting to "Organization", users on domains that don't have Single Sign-On enabled, will not be able to log in to their account on ISL Conference Proxy.
Step 9
Enable Single Sign-On under "User management" -> "your_domain" -> "Security" to force the logins to be redirected to the Identity Provider and thus enable the Single Sign-On functionality. Restart module apps in ISL Conference Proxy when prompted.
Sign In - Web
Step 1
Click "Login" on the ISL Conference Proxy web page.
Step 2
Select "Sign in to an organization".
Step 3
Select the organization that you have set up to proceed with the login. If the setup was successful you will be redirected to the Single Sign-On page.
Note: Redirection behavior can be different depending on your browser.
Step 4
Enter your Okta credentials and sign in. You will be redirected back to ICP if login succeeds.
Step 5
You are now logged in and can use all the functionalities of ICP normally. Note that the user is a part of the external (\\external\) domain we created during the setup.
Sign In - Application
Step 1
Login procedure for ISL Online applications differs with Single Sign-On as well. Select "Sign in to an organization" button.
Step 2
Select the organization that you have set up to proceed with the login.
Step 3
Select "Sign in" button in order to proceed to the Okta login. If the setup was successful you will be redirected to the Single Sign-On page.
Step 4
Enter your Okta credentials and sign in. You will be redirected back to the application if login succeeds.
Note: If the token received from Okta is still active in your default browser you won't have to enter your credentials again.
Step 5
Click on "Grant Access" and you will be logged in and redirected back to the application.
Step 6
You are now logged in and can use the application normally.
Note: If you have enabled additional logs in the Core Login module for easier debugging, navigate to configuration page of your ISL Conference Proxy -> "Configuration" -> "Logs" and set the following settings back to default value: