Enterprise SSO – Azure – Pro Plan

Configuring WhenToWork (W2W) SSO feature

using OpenID Connect with Microsoft Azure as the IAM provider:

Product SSO Configuration Guide (OpenID Connect with Microsoft Azure)

Table of Contents

1. Introduction

2. Prerequisites

3. Setting up SSO with Microsoft Azure

Step 1: Registering the Application in Azure AD

1. Log in to the Microsoft Azure portal.
2. Navigate to Azure Active Directory and select the appropriate directory.
3. In the left navigation pane, go to “App registrations” or “Enterprise applications.”
4. Click on “New registration” or “New application registration,” and provide a name for your application, such as WhenToWork.
5. Configure the supported account types and select “Web” as the application type.
6. Save the application registration and note the **Application (client) ID**.

Step 2: Configuring Redirect URLs

1. In the application’s configuration page, go to the “Authentication” or “Sign-on” section at Home → [directory name] → App registrations → [application name] → Authentication
2. Enter the Redirect URI(s) that Azure should send SSO responses to.
   – Add http://whentowork.com/cgi-bin/w2w.dll/login
3. For token types to be issued by the auth endpoint, enable checkboxes for both “Access tokens” and “ID tokens”.
4. Save the changes.

Step 3: Obtaining Client ID and Client Secret

1. In the application’s configuration page, go to the “Certificates & secrets” or “Client secrets” section.
2. 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 Azure will use to launch the WhenToWork service provider application 

1. Navigate to Home → [directory name] → App registrations → [application name] → Branding & properties
2. Locate the setting Home page URL
3. Enter `http://whentowork.com//cgi-bin/w2w.dll/login?codeflow=azure&companyid=[your company id]&prompt=select_account`
   – The prompt param can be any value supported by Azure’s OAuth2 code flow, e.g. login, none, consent, and select_account.

4. Configuring WhenToWork with Azure 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 Azure. The Azure 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 Azure 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://login.microsoftonline.com/<YOUR_TENANT_ID>/oauth2/v2.0`
   – Example: `https://login.microsoftonline.com/common/oauth2/v2.0`
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://login.microsoftonline.com/<YOUR_TENANT_ID>/v2.0/.well-known/openid-configuration
4. Provide the **Application ID** of the SSO app if it is required for specific methods of authorization. You can find this value in the Azure AD “App Registrations” section.
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 Azure’s immutable unique user ID. The default value for this field is “oid”.
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 Azure.
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’ “aud” (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 “w2w”, 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 Azure app which opens WhenToWork has been granted access to call the Graph API. You can configure this under “API Permissions” in the “App Registrations” section of Azure AD.
   – Navigate to Home → [directory name] → App registrations → [application name] → API permissions
   – Add the following permissions for Microsoft Graph and grant admin consent as is appropriate.
4. Optionally, provide the **App Name** with the name of your Azure AD app used to access WhenToWork. This authorization method requires all users to have permission to query the appRoleAssignments resource type using the Microsoft Graph API.
5. Save the SSO configuration changes.

5. Testing SSO

Step 1: Initiating SSO

1. Using an admin account in Azure AD, designate or create a test user account.
2. Assign the WhenToWork application to your test user in Azure.
   – Navigate to Home → [directory name] → Enterprise Applications → All applications → <WhenToWork app name> → Users and Groups
   – Assign the test user account
3. Open the test users portal and click on the WhenToWork launch icon in the app list.
4. You should be redirected to the Microsoft Azure login page.
5. Enter your Azure AD credentials and log in.
6. 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 Azure 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. 1After logging in to WhenToWork manager account using your standard WhenToWork userid and password, navigate to EMPLOYEES → Azure Employee Provisioning
2. You should now see a list which includes your test user from Azure AD.
   – If an occurs, it probably means that your WhenToWork application in Azure AD does not have the required permissions to read the users list from your Azure directory. In this case, check “API permissions” under “App registrations”.
   – In the default-selected “New” list, you should see a list of users from the Azure 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 Azure test user’s app list, and this time the login should succeed.

Step 3: Verifying SSO

1. Ensure that the user profile and attributes, including immutable id, name and email address, are correctly synchronized from Azure AD 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

Error Code Detail

extauth-reg-failed:

• End user error text: 
  Authorization by <IDP> succeeded but registration with WhenToWork failed.

• Error Detail:
  This is an unlikely catch-all error code which can be raised during the registration of identity service providers such as Google, Facebook or Microsoft.

  This error could occur if WhenToWork’s software encounters an unplanned error condition from the IDP, such as the IDP’s endpoint is not responding or is responding with unexpected content. The this error code occur if the target IDP has changed their public facing API in a way which is no longer compatible with WhenToWork’s implementation.

• What to do:
  If the problem persists, feel free to email WhenToWork’s tech support staff with a description of the problem.

extauth-login-retry:

• End user error text: 
  Authorization by <IDP> succeeded but login failed unexpectedly. Please try again.

• Error Detail:
  This error probably indicates that the WhenToWork database of not available for some reason such as an ISP outage, http response timeout, or other hardware or access failure.

• What to do:
  Try logging in as a manager using standard WhenToWork userid and password. If that fails then WhenToWork technical support is probably already aware of the problem and in work on the solution. Check again periodically to see if the system is back on line.

extauth-token-expired:

• End user error text: 
  Authorization by <IDP> has expired. Login again or try clearing cookies and force a hard refresh of your internet browser. If the problem persists, contact your local system administrator.

• Error Detail:
  The exp claim provided by the id or access token provided by the IDP has expired. Token expiration time is typically one hour, but the IDP’s browser-based software is responsible for keeping tokens current, such that this issue should be uncommon.

• What to do:
  If your browser supports multiple user profiles/identities. Make sure that the desired identity is the one that’s active/selected. Retry your login.

  Clear your browser’s data cache (Ctrl-Shift-Delete, in some browsers), and retry the login.

  If available, try to login using your browser’s “new incognito/private window” option.

  Try to login using a different browser.

  Contact your local system administrator.

  If the problem persists, contact WhenToWork tech support.

extauth-tokenreq-error

• End user error text: 
  Authorization by <IDP> failed unexpectedly. Try logging in again and if the problem persists, contact your local system administrator.

• Error Detail:
  This issue can only occur during WhenToWork’s processing of the OAuth2 code flow for IAM’s such as Okta and Azure. The error indicates that IAM user authentication succeeded, but failed to receive an access token for the endpoint found at <OAuthBaseURI>/token. This could be due to a system outage at that endpoint. It could also be caused an incorrect Application Id/Client Id or an incorrect or expired Client Secret in your WhenToWork SSO settings.

• What to do:
  After a while, retry your login.

  Contact your local system administrator.

  If the problem persists, contact WhenToWork tech support.

extauth-nonce-error

• End user error text: 
  Authorization by <IDP> included an unexpected verification value. If the problem persists, contact your local system administrator.

• Error Detail:
  This error indicates that WhenToWork has intercepted an attempted replay attack.

• What to do:
  Contact WhenToWork tech support.

extauth-token-error:

• End user error text: 
  Login via IDP: Authorization by <IDP> failed. Please try again or use WhenToWork login id and password.

  Login via IAM: Authorization by <IDP/IAM> failed. Please try again, or if the problem persists, contact your local system administrator.

• Error Detail:
  This is an unlikely catch-all error code which indicates a non-specific or unexpected condition occurred while validating an id or access token.

• What to do:
  If the problem persists, feel free to email WhenToWork’s tech support staff with a description of the problem.

extauth-update-error

• End user error text: 
  Authorization by <IDP> succeeded but update of authentication data failed unexpectedly. Please try again.

• Error Detail:
  Indicates that the attempt to record the antecedent error failed. This could happen if WhenToWork’s main server is experiencing an outage.

• What to do:
  If the problem persists, feel free to email WhenToWork’s tech support staff with a description of the problem.

case “extauth-disabled-error”:

• End user error text: 
  Authorization by <IDP> is either not configured or disabled. Check WhenToWork SSO settings.

• Error Detail:
  This is an IAM-only error wherein a user is attempting to login using and IAM type (e.g. Okta/Azure) which is currently disabled.

• What to do:
  Contact your local system administrator.

extauth-invalidtype-error:

extauth-requiredtype-error:

extauth-requiredtype-okta:

extauth-requiredtype-azure:

• End user error text: 
  Your WhenToWork account requires authorization using <IDP>.

• Error Detail:
  A user is attempting to login using a different IAM than the one which is currently enabled and “Required”. 

  This error is most likely to be the result of changing from one type of IAM configuration to another, e.g. changing from Azure to Okta.

  Although these error codes mean essentially the same thing, the unique error codes may be useful to WhenToWork technical staff in diagnosing an unexpected root cause.

• What to do:
  Contact your local system administrator.

  If the problem persists, feel free to email WhenToWork’s tech support staff with a description of the problem.

extauth-unknowntype-error:

• End user error text: 
  SSO type <IDP> is unknown. Please check with your manager or system administrator.

• Error Detail:
  This error can only occur as a result of an invalid value for the IAM code flow launch url param “codeflow=”. Supported values for the codeflow param are “azure” and “okta”.
  – For Azure, see “Initiate login URI”.
  – For Okta, see “Home Page URL”.

• What to do:
  Contact your local system administrator.

extauth-unknowncompany-error:

• End user error text: 
  Company id <company id> is unknown. Please check with your manager or system administrator.

• Error Detail:
  This error can only occur as a result of an invalid value for the IAM code flow launch url param “companyid=”.
  – For Azure, see “Initiate login URI”.
  – For Okta, see “Home Page URL”.
  In this case, the specified company id does not exist.

• What to do:
  Contact your local system administrator.

extauth-noconfig-error:

• End user error text:
  Configuration for company id <company id> is not found. Please check with your manager or system administrator.

• Error Detail:
  This error can only occur as a result of an invalid value for the IAM code flow launch url param “companyid=”.
  – For Azure, see “Initiate login URI”.
  – For Okta, see “Home Page URL”.
  In this case, the specified company id does not have any IAM configuration data at WhenToWork SETTINGS → Pro → Enterprise SSO / Configure

• What to do:
  Contact your local system administrator.

extauth-usernotfound-error:

• End user error text: 
  <IDP> user not found. Please check with your manager or <IDP> system administrator.

• Error Detail:
  User attempted to login to WhenToWork with and external IDP/IAM id or email address that is not linked/provisioned in WhenToWork.

  This error can only occur for IAM access attempts. Conversely, standard IDP access wherein no user link is found will automatically guide the user to set up a persistent link to the IDP.

• What to do:
  Contact your manager.

extauth-appaccesstoken-error:

• End user error text: 
  An unexpected <IDP> app access token error occurred. Please contact your <IDP> administrator.

• Error Detail:
  This error is specific to Azure AD, and indicates that AppResourceName is defined through configuration, but the user who is attempting to login does not have permissions to query the app list.

• What to do:
  Contact your manager or local system administrator.