The Google Workspace setup is separated into two parts. Firstly, the steps that need to be preformed on Google Workspace are shown, followed by the steps that need to be performed in the ISL Conference Proxy (ICP). Please refer to the relevant part:
Setup - Google Workspace
Step 1 (Adding custom SAML app)
Sign in to the Google Workspace admin portal using your administrator account, and navigate to "Menu" -> "Apps" -> "Web and mobile apps" -> "Add app" -> "Add custom SAML app".
Step 2
Enter the name of your application (e.g. ISL Conference Proxy), optionally add a description and an icon, and then click Continue.
Step 3
Download the metadata XML file and store it for later. The metadata XML file can also be downloaded at a later stage. Click Continue.
Step 4
Set the following fields:
- ACS URL (Assertion Consumer Service URL): https://isl.example.com/sso/saml/sp/metadata.xml
- Entity ID: https://isl.example.com/sso/saml/sp/acspost
- Start URL (optional): https://isl.example.com/users/isllight/start.html
Replace https://isl.example.com/ with your ISL Conference Proxy server address. Review the information and click Continue.
Note: When copying the ACS URL, Entity ID and Start URL, double-check for empty spaces in front and at the back of the string. If there are empty spaces left in the string, the SSO login will not work later in the process.
Important: The NameID field should be left default, as it will keep the Primary email as the unique NameID identifier.
Step 5
When a user authenticates, Google Workspace will issue a SAML token to ISL Conference Proxy, that contains unique information about the user. The unique User Identifier (NameID), which we have set up in the previous step specifies the claim, which will uniquely identify the user on the ISL Conference Proxy (e-mail). Unique User is a mandatory user claim.
Username (mandatory): Unique User Identifier (NameID in the previous step)
Primary email (optional): email
First name (optional): first-name
Last name (optional): last-name
Group membership (optional): groups
Store the SAML claim names (right-hand side column on the screenshot above) as you will need to include them in Step 7 of the ISL Conference Proxy Setup.
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.
Assign users to the application
Users must first be assigned to the application before being able to access it. Select User Access from the app menu and add users or user groups, who will have access to your ISL Conference Proxy application.
After you configure the application access, click Save.
Download Google Workspace metadata XML file
After basic SAML configuration and setup of user attributes/claims are finished, click on "Download metadata" option from the app menu. Store the XML file as it will be used in step 4 of ISL Conference Proxy SAML 2.0 setup.
Click Download metadata.
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 (Google Workspace). 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_sp.key -aes128 2048 openssl req -x509 -key sso_saml_sp.key -out sso_saml_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_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 "Configuration" -> "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
Upload the Google Metadata XML file 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 5
On the Security page configure the setting "SAML identity provider XML metadata file" with the file that you have stored in "Download Google Workspace metadata XML" part of this guide. The format should be "objects/filename.xml". 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 6 (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 7
Create an additional domain for Single Sign-On users. A new domain can be created under "User management" -> "Domains", process is further described in the topic titled Domains. In this example, we created a Domain "sso".
Step 8
Set SAML login setting rules under "Configuration" -> "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", "domain", "sso"] ,["key-from-attr", "realname","first-name", " ", "last-name"] ,["key", "user_profile::name", "0"] ,["key-from-attr", "email", "email"] ,["key", "user_profile::email", "0"] ]
Step 9
As the final step in ICP enable Single Sign-On on the same page 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
Enter your Google Workspace credentials and sign in. You will be redirected back to ICP if login succeeds.
Step 3
You are now logged in and can use all the functionalities of ICP normally. Note that the user is a part of the sso (\\sso\) domain.
Sign In - Application
Step 1
Login procedure for ISL Online applications differs with Single Sign-On as well. Username and password fields are removes, the only button left is the "Sign in" button.
Step 2
Enter your Google Workspace credentials and sign in. You will be redirected back to the application if login succeeds.
Step 3
Click on "Grant Access" and you will be logged in and redirected back to the application.
Step 4
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: