Press "Enter" to skip to content
< Back

Enterprise SSO – Beta

To become a Beta tester please email support@when2work.com with your account number and details about your provider.

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

Signin with Okta/Azure (IAM – Identity and Access Management solutions/providers)

Authentication & Authorization=permission to access app and/or specific information/resources

Uses OAuth2 code flow to acquire Identity and Access tokens

Configuration can be done by the main manager on their SETTINGS → Pro  page by clicking  Enterprise SSO “Configure”

Mode:

Required   Other auth access is blocked

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 implementation.

Manager/Submanager access is always “Optional”, which prevents accidental lockout

Authorization Capabilities:

External IAM permissions control availability of the launch icon in the Okta/Azure portal; however, the portal is not the only way to launch W2W.

All that is needed is the url which, in some cases, is exposed in the portal app. A prototype url is provided in the respective IAM configuration screen which can be pasted into any supported web browser or embedded in any web page. 

As such, W2W provides access controls to insure that users not only have a valid identity, but also possess explicit authority to use the application.

W2W managers and submanagers can access the application using either IAM credentials, or any supported IDP, such as Google or Facebook, or using their W2W native login id and password.

IAM configuration can also specify additional space-delimited custom scopes which will be added to basic scopes in access token requests. IAM custom auth servers may use their own rule-based logic and permissions to control which scopes are returned with access tokens.

Test Expressions (Optional):

Test Expressions provide a flexible means of validating and authorizing ID and access tokens. For example, OAuth2 recommends that ID tokens’ “aud” (audience) claim be tested to contains the value of the associated client id/application id. This can be accomplished using an expression such as the following:

IDTOKEN.aud = ‘9b6xxxxxxxxxxxxxxxx651’

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′)

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.

Note – Only the main manager can “Run” expressions, which provides visibility of token payload claims.

Configuration for Azure   

  

Employee Provisioning:

WhenToWork managers are responsible for Employee Provisioning, which must be able to access IAM directory information for all employees in the company account. This is accomplished in two steps. 
– The first step is to obtain an OAuth2 bearer token from Azure which contains the authorization to access data stored in Azure. In this step, the client must authenticate itself to the Azure directory service using either a shared client secret or a private/public key pair which Azure implements using the certificate model. WhenToWork’s SSO implementation supports either methodology, according to your company’s preference.
– The second step is to request the data from Azure using that bearer token to authorize the request.
 

WhenToWork SSO Configuration:

Using the Enterprise SSO Configuration popup, locate the Client Credentials setting and select among the three options. 
– Client Secret: 
Use this option if you intend to use a client secret to authenticate WhenToWork to your SSO service provider. Use caution to keep this value private.
– Upload PRIVATE KEY from Cert: 
Use this option if you intend to authenticate WhenToWork with your SSO service provider using a certificate, and you already have a certificate or .pfx file containing your private key.
– Generate PKCS#1 PRIVATE KEY for Cert:
Use this option if you intend to authenticate WhenToWork with your SSO service provider using a certificate, and you do not already have an externally-generated private key.
 
Details for usage of each option are shown with each selection.
 
Define the Apps Query Url using the form: 
https://graph.microsoft.com/v1.0 
 

Azure Permissions:

WhenToWork’s server must have permission to query employee data from Azure AD. That permission must be granted to the WhenToWork SSO app hosted in the Azure AD portal.
  
Log in to the Azure AD portal with a user that has administrative privileges and navigate to the following configuration page:
App registrations -> (WhenToWork app name) -> API Permissions 
 
Navigate to: App registrations -> WhenToWork -> API Permissions
– Add a permission
– Select “Microsoft Graph”
– Select “Application permissions”
– Select User.Read.All
– Click on Add permissions
– Grant admin consent for WhenToWork
 
Click on “Grant admin consent for WhenToWork”, and confirm.
 

Custom Token Configuration:

If you want to apply additional controls on user access based information that is not already present in OpenID or Access tokens, you may consider using Azure’s “Token configuration” page:
App registrations -> (WhenToWork app name) -> Token configuration
 
From here you can add optional claims as needed, and then add “Test expressions” in WhenToWork’s SSO configuration page to control access as per your organizational requirements.
 

Okta

If Api Key and Apps Query Url are defined in configuration, and Custom Scope is not defined/blank, WhenToWork will query the Okta app’s user directory to determine whether a given user is assigned to the Okta app identified by the configured Client Id. The Apps Query Url should have the form:

https://<Okta domain>/api/v1/apps/<Okta app client id>

If Custom Scope is defined, then WhenToWork will exclusively use Test Expressions to authorize access to the WhenToWork application. Note that, the Apps Query Url is always required as it is needed for manager Employee Provisioning.

Manager authorizations:

W2W managers are responsible for Employee Provisioning, which must be able to access IAM directory information for all employees in the company account. As such, authorization of manager accounts is more elaborate than regular employees.

In broad strokes, there are two paths for accomplishing this additional access. Okta-based companies can either use a private API Key generated in Okta, which authorizes access to their application APIs, or let WhenToWork request an access token with special scopes, okta.apps.read and okta.users.read, which are sufficient to authorize the necessary queries.

If the Api Key is not defined on the config page, then, immediately after login, w2w will silently request a access token from the organizational auth server using scopes: okta.apps.read and okta.users.read. That token will then be used as a bearer token to query the external Okta directory in Employee Provisioning. If that bearer token expires during the course of a session, the WhenToWork app will use a refresh token to silently request an updated access token from Okta.

  • Employee Provisioning for IAM – Okta/Azure

In contrast to IDP-only “signin with” first-time linking process, under IAM, employees must be independently provisioned (i.e. linked to the externally managed user in the IAM directory) by a manager before they can access WhenToWork. In this case, employee user types are never prompted to enter a w2w login id and password.

New page at EMPLOYEES → Okta/Azure Employee Provisioning provides the tools needed to provision new or existing employees.

Grid with three views – New/Existing/Deleted

New – Added to IAM directory, but not yet linked to a w2w employee.

On the right of the list of ext users, there are two columns, Emp Action and Mgr Action. Click on either cell or both set a pending action to provision an existing w2w employee as either employee or manager or both, or to create and provision a new employee or manager.

All actions are executed by clicking on the Save button.

After provisioning changes are saved, affected users will henceforth appear in the “Existing” list.

Existing – Link exists between IAM directory and active w2w employee.

Shows employee status in the “Is Emp” and “Is Mgr” columns.

Provisioning links can be removed by selecting rows and clicking on “Unlink SSO”.

Modifications of provisioning for users in the Existing list can only be accomplished by first unlinking. Unlinking returns the user to the New list, wherein provisioning can be selectively added.

Final column “Last Login” displays an icon which indicates whether the user’s last login succeded or failed. Click on that cell for detail.

Deleted – w2w link exists for active w2w employee, but deleted/missing from external IAM directory.

Provisioning links can be removed by selecting rows and clicking on “Unlink SSO”.