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 support@when2work.com
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 SSO Configuration:
Azure Permissions:
– Add a permission
– Select “Microsoft Graph”
– Select “Application permissions”
– Select User.Read.All
– Click on Add permissions
– Grant admin consent for WhenToWork
Custom Token Configuration:
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”.