Enterprise SSO – Okta – Beta

Product SSO Configuration Guide (OpenID Connect with Okta)

Note – this feature is in beta so due care needs to be taken when using this feature and please report any issues/feedback to support@when2work.com 

Table of Contents

1. Introduction

2. Prerequisites

3. Setting up SSO with Okta

Step 1: Registering the Application in Okta

1. Log in to the Okta Admin Console.
2. Navigate to Applications and click on “Add Application”.
3. Select “Create New App” and choose the application type based on your requirements.
4. Configure the general settings for the application, providing a name for your application, such as WhenToWork.
5. Save the application registration and note the **Client ID**.

Step 2: Configuring Redirect URLs

1. In the application’s configuration page, go to the “General” tab.
2. Edit General Settings.
3. Under the “Login redirect URIs” section, enter the Redirect URI(s) that Okta should send SSO responses to.
   – Add http://whentowork.com/cgi-bin/w2w.dll/login
4. Save the changes.

Step 3: Obtaining Client ID and Client Secret

1. In the application’s configuration page, go to the “General” tab.
2. Use “Generate new secret” to create a new client secret, providing a description and expiration.
3. Note down the **Value** of the created client secret.

Step 4: Assign the Home Page URL that Okta will use to launch the WhenToWork service provider application

1. Navigate to the application’s configuration page.
2. Edit General Settings.
3. Locate the setting for Initiate login URI.
4. Enter `http://whentowork.com//cgi-bin/w2w.dll/login?codeflow=okta&companyid=[your company id]&prompt=select_account`
   – The “prompt” param can be any value supported by Okta’s OAuth2 code flow, e.g. none, consent, login, or consent and login.

Step 5: Set application properties

• – Navigate to the application’s configuration page.
• – Authorization Code: Yes/checked
• – Refresh Token: Yes/checked

4. Configuring WhenToWork with Okta SSO

Step 1: Accessing WhenToWork’s Configuration Console

1. Log in to WhenToWork using your admin credentials.
2. Navigate to the SSO Configuration settings section: SETTINGS > Pro > Enterprise SSO / Configure

Step 2: Enabling SSO

1. Click on Enable Okta. The Okta configuration page will open.

Step 3: Configuring OpenID Connect Settings

1. Select the desired **Mode** for SSO login. If you want to transition from WhenToWork login to Okta gradually, choose “Optional” to allow alternate login methods. Later, when your SSO implementation has been verified and is ready to deploy, you can change this setting to “Required”. Click [here] for more information.

   >>>>>>>> MORE INFO >>>>>>>>>>>
   *Optional*
   Other authentication access, including w2w user/pw login, is available. Note that only one type of IAM access can be enabled. Thus, for example, if Azure is currently enabled, access via Okta is not possible, even is Azure is set to Optional.

   Use this when transitioning from user/pw to external auth to avoid disruption during the IAM Configuration phase.

   *Required*
   When selected, access to all other forms of authentication is blocked. 

   Manager/Submanager access is always “Optional”, which prevents managers from accidentally being locked out of the system as a result of an improper SSO configuration. Thus, WhenToWork managers and submanagers can access the application using either IAM credentials, or any supported IDP, such as Google or Facebook, or using their WhenToWork native login id and password.
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

2. Enter the **OAuthBaseURI** of the SSO app. This value can refer to either the common auth server or a tenant auth server.
   – Example: `https://<Okta domain>/oauth2/v1`
   – Example: `https://<Okta domain>/oauth2/<custom server id>/v1`
3. Enter the **MetadataURI** that is used to query the Identity Provider’s endpoints. A typical MetadataURI ends with “/.well-known/openid-configuration”.
   – Example: `https://<Okta domain>/oauth2/<custom server id>/.well-known/oauth-authorization-server`
4. Provide the **Client ID** of the SSO app. These values are provided by Okta when you register your application.
5. Enter the **ClientSecret** of the SSO app. Keep this value private and secure. You can find this value in the Azure AD “App Registrations” section, under “Certificates & secrets”.
6. In the field labeled **External Id Claim**, specify the name of the claim in the OpenID authentication token that provides Okta’s immutable unique user ID. The default value for this field is “sub”.
7. Save the SSO configuration changes.

Step 4: Configuring Authorization Settings

1. If needed, use the field labeled **Custom Scope** to enter additional space-delimited scope values to control access to WhenToWork from Okta.
2. Use **Test Expressions** to customize access controls to WhenToWork. For detailed instructions on using test expressions, refer to the WhenToWork Help documentation. Test Expressions provide a flexible means of validating and authorizing ID and access tokens. For example, test expressions can prevent access to WhenToWork if a designated scope is not present in the received access token. Click [here] for more information.

   >>>>>>>> MORE INFO  >>>>>>>>>>>
   Test Expression Guidelines:
   One boolean/logical expression per line.
   All function names and variable names are case-insensitive. Quoted literals are case-sensitive when used with logical operators such as . String compare functions such as stringinstring() and match() are case-insensitive, except when using regex syntax.
   Supports parentheses and parenthesis nesting.
   Match() function supports regular expressions.
   Expression can address claims in both the id token and the access token.
   Processing stops when any expression fails.
   Only the main manager can “Run” expressions, which provides visibility of token payload claims.

   For example, OAuth2 recommends that ID tokens’  (audience) claim be tested to contain the value of the associated client id/application id. This can be accomplished using an expression such as the following:

   IDTOKEN.aud = ‘0123-xxxxxxxxxxxxxxx-4567’

   If defined, all expressions must succeed for all users, including managers, accessing WhenToWork via IAM (Okta/Azure) signin credentials. Expressions can reference claim values in either the Id Token or the Access Token. For example, to test whether the email values match between Id and Access Tokens using Okta, the expression could be written as follows:

   IDTOKEN.email = ACCESSTOKEN.sub

   To verify that the received access token contains the scope, use the following:

   match(ACCESSTOKEN.scp,/”w2w”/i)

   → note, the match() function supports regular expressions. 

   Expressions can include parentheses, example:

   (ACCESSTOKEN.appname = ‘SSO-V1’) or (ACCESSTOKEN.appname = ‘SSO-V2’)

   …which could also be written as 

   among(ACCESSTOKEN.appname,’SSO-V1|SSO-V2′)
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

3. Provide an **Apps Query URL** that returns app-related information, such as app user assignments and app users list. Ensure that the Okta app which opens WhenToWork has been granted access to call the Okta API. You can configure this in the Okta Admin Console under the application’s API access settings.
   – Navigate to the Okta Admin Console → Applications → [application name] → API > Authorization Servers”
   – Add the necessary scopes and permissions for the Okta API.
4. Optionally add a value for API Key  to access apps-related info, e.g. app users list. If not defined, at the time of login, WhenToWork will attempt to aquire an access token which authorizes access to the Okta domain’s user list/directory.
5. Save the SSO configuration changes.

5. Testing SSO

Step 1: Initiating SSO

1. Using an admin account in Okta, designate or create a test user account.
2. Assign the WhenToWork application to your test user in Okta.
   – Navigate to the Okta Admin Console → Applications → [application name] → Assignments
   – Assign the test user account.
3. Open the test user’s portal and click on the WhenToWork launch icon in My Apps.
4. You may be redirected to the Okta login page.
   – Enter your Okta credentials and sign in.
5. Upon successful authentication, you should be redirected back to the WhenToWork application, which will, however, fail with an error because the newly created test user account in Okta does not have a corresponding user in WhenToWork. This will be addressed in the next step.

Step 2: Prepare an employee user account for testing SSO access

1. After logging in to WhenToWork manager account using your standard WhenToWork userid and password, navigate to EMPLOYEES → Okta Employee Provisioning
2. You should now see a list that includes your test user from Okta.
   – If an error occurs, it probably means that your WhenToWork application in Okta does not have the required permissions to read the users list from your Okta directory. In this case, check the application’s API access settings in the Okta Admin Console.
   – In the default-selected “New” list, you should see a list of users from the Okta directory which includes your newly created test user account.
3. In the associated test user row, click on the cell “Ignore” under the column labeled “Emp Action”.
   – This will open a dialog which allows you to create a new user or link an existing user to the external test user account.
   – Once this dialog closes, the selected action is pending until you click Save.
   – At this point, you can once again launch the WhenToWork app from the Okta test user’s apps list, and this time the login should succeed.

Step 2: Verifying SSO

1. Ensure that the user profile and attributes, including immutable ID, name and email address, are correctly synchronized from Okta to WhenToWork.
2. Verify that the user’s access and permissions are applied correctly within the product
   – After a login attempt, open the Configuration console and Run Test Expressions for the given test account. Exercise authorization controls for employees using both positive and negative testing.

6. Troubleshooting