Press "Enter" to skip to content
< Back

SSO – Azure Setup Assistant Documentation

Azure Setup Assistant Documentation

This is the text from the Azure Setup Assistant for documentation. To get to this Setup Assistant please see: Enterprise SSO

  1. Welcome
  2. Mode
  3. Security Preferences
  4. Azure App Creation
  5. OAuth Base URI
  6. Validate Id Token Settings
  7. External Id Claim
  8. Client Credentials

Welcome

  • This tool will help set up your WhenToWork SSO configuration, providing step-by-step instructions with additional detail for each step.
  • The Setup Assistant loads your current configuration settings and thus can be used at any time to make changes or as an information reference.
  • WhenToWork product references to Azure / Azure AD have the same meaning as Entra / Entra ID.
  • You will need your admin credentials for your Azure portal.
  • WhenToWork SSO support requires cookies for setup by Tech Users and provisioning operations by Managers.
  • You can save your changes at each step, or wait until the final step if you are satisfied with your changes.
  • Once all steps are complete without errors, your configuration should be ready for use by employees and managers.

Click on Next to get started.

Mode

Mode determines how employees are provisioned and signed in using Azure.

The Mode setting has no effect on tech users who can login using either Azure SSO login or WhenToWork login id and password. This prevents tech users from being accidentally locked out do to a configuration error.

There are five options for Mode.

  1. Self-provisioning: Active WhenToWork users provision their own accounts without prior action by the manager. This mode prompts users to select their Azure identity at the time of their next login using WhenToWork credentials. After that, WhenToWork is only accessible using Azure credentials via the Home Page URL. Only a manager can de-provision a user-provisioned account, which then optionally sends instructions to the user to restart the user self-provisioning process. This is the easiest option to set up and maintain as it does not require configuration and permissions for WhenToWork to query user information from Azure, while still delegating access control to Azure and verification via OAuth2.0 conventions.
    If you are implementing SSO on an existing account, you can reduce the manager’s effort of provisioning a large number of users by initially setting SSO Mode to Self-provisioning. In this way, your WhenToWork users, who are already accustomed to signing in with a WhenToWork login id and password, can provision themselves individually. Once that is complete, you can change the Mode to Required wherein the manager will be subsequently responsible for provisioning users as required by the organization.
  2. Email Match: First time login by an unprovisioned Azure user is automatically provisioned by locating the WhenToWork primary email address that matches the incoming Azure email address.
    All WhenToWork primary email addresses must be unique.Email address changes are restricted to managers until after an employee is provisioned.
  3. Auto-create: Automatically create a new user in WhenToWork at the time of login, when no match is found for the incoming Azure email address. An email will be sent to the main manager to indicate that a new WhenToWork user has been generated. Enabling this option will allow users to have immediate access to WhenToWork but the manager will still need to set up the user with positions and schedule.
    This option is appropriate for brand new WhenToWork accounts and for legacy accounts wherein all current users have already been provisioned.
  4. Preemptive: Managers link users in the Azure user directory to a user account in WhenToWork prior to any attempt to log in to WhenToWork, and without any provisioning-related action required on behalf of the user. Preemptive Employee Provisioning is enabled by default and is the most secure method of employee provisioning because it relies on the IAMs immutable user id. However, there is additional effort required in setting up the query and permissions or keys needed to access the Azure user directory from WhenToWork.
  5. Locked: New users cannot be provisioned to for SSO access using Azure. This mode should be applied to any account, including a test account, which is no longer in use.

Optional SSO Login – When enabled, users can log in using either SSO login or their native WhenToWork login id and password, which insures continuity while implementing SSO on an existing account. This option should be turned off after all users have been provisioned.

Optional

Click on Next.

 

Security Preferences

Two-Factor Authentication for Native Login

Even if Mode is set to Required, a tech user, and optionally, the main manager can still log in using their WhenToWork login id and password. This exception for tech users prevents the possibility of a lockout condition wherein an incorrect SSO configuration setting cannot be resolved because the person with authority to make the correction is unable to access the system.

However, this lower standard of security for tech users effectively extends to all users because a tech user has access to settings that control security for all. Enabling this Two-Factor Authentication setting offsets that risk by enforcing an additional layer of security for users that can change security-related settings.

Enforce two-factor authentication for tech users

 

Manager Native Login

When enabled, the main manager can log in using native WhenToWork login id and password credentials.

Allow the main manager to use native login 

 

Access WhenToWork using Work Assistant

If this setting is On, the Work Assistant Alexa skill can only be linked to a WhenToWork employee account from the Employee’s Info page. Thereafter, access to the WhenToWork system is enforced by application of Amazon’s Alexa skill OAuth2 requirements for account linking and access.

When this setting is Off, the Work Assistant skill is not available when SSO Mode is set to either Required or Self-provisioning.

Allow access to WhenToWork using Work Assistant

Click on Next.

 

Azure App Creation

If you haven’t already done so, you will need to create a new SSO app for WhenToWork in your Azure portal.

  1. Go to portal.azure.com and sign in with your administrator account.
  2. Under Azure Services, select Azure Active Directory.
  3. On the left menu, select App registrations.
  4. On the horizontal menu, select New registration.
  5. Set the Application name to WhenToWork.
  6. Set Who can use this application or access this API? to single or multitenant.
  7. From the Select a platform dropdown menu, select Web.
  8. Set redirect URI to:
    https://dev.whentowork.com/cgi-bin/w2w.dll/login
  9. Click on the Register button.
  10. Locate Application (client) ID and copy/paste it here.
    [ ex: 9b6938c3-bdcd-….-8d5a-9dd2338b7651 ]
  11. Locate Directory (tenant) ID and copy/paste it here.
    [ ex: a3d8e841-73ad-….-9cfe-47d7faae96f8 ]
  12. Select Authentication from the left hand menu.
  13. Scroll down to find Implicit grant and hybrid flows.
  14. Check the boxes for both Access tokens and ID tokens.
  15. Click on the Save button.
  16. Select Branding & Properties from the left hand menu.
  17. Click on the folder icon for Upload new logo and enter:
    https://WhenToWork.com/images_sales/w2w_logo_circle.png
  18. In Home page URL, enter:
    https://dev.whentowork.com/cgi-bin/w2w.dll/logincodeflow=azure&companyid=11888&prompt=none

Once complete, return here and click on Next.

 

OAuth Base URI

The value of OAuthBaseURI will be internally appended with “/authorize” and “/token” to return OAuth2 access tokens. This value can be a reference to either the common auth server, or a tenant auth server.

OAuthBaseURI
Click on Next.

 

Validate Id Token Settings

Use this step to verify that your Azure identity token-related settings, such as OAuth Base URI and Metadata URI are correct and working with your Azure WhenToWork app.

Click on the Test Azure login button below and login using any user in your Azure directory. This test does not require the selected user to be granted specific access or permissions to the WhenToWork app, and does not require the selected user to be provisioned to a user in the WhenToWork system.

If the test is successful, you can click on the Show Id Token button below to inspect the Id token returned from the Azure IAM.

If you don’t receive a successful result from this test, use the Back button to check your settings up to this point in the Setup Assistant, and then try this test again. Things to check:

  • Make sure that you have set the Azure app redirect URI to
    https://dev.whentowork.com/cgi-bin/w2w.dll/login
  • Check the values of Directory (tenant) ID and Application (client) ID.

Click on Next.

 

External Id Claim

Name of claim in the OIDC Id token that provides Azure’s immutable unique user id. In general, the default claim identifier, “oid”, is correct.

JWT payload example

However, if you need to override the default Id claim, enter it here
[Default value is “oid”]

Click on Next.

 

Client Credentials

Three options:

  1. Use Client Secret (You have not defined a client secret yet.)
  2. Upload PRIVATE KEY from Certificate
  3. Generate PKCS#1 PRIVATE KEY for Certificate

a. Use Client Secret (You have not defined a client secret yet.)

Use this option to use your client secret to authenticate WhenToWork to your SSO service provider.

  • Make sure to update your client secret in both Azure and WhenToWork before its expiration date.

To create a client secret…

  1. Select the WhenToWork app in App Registrations in Azure AD.
  2. Click on Certificates & secrets.
  3. Then click on New client secret.
  4. Enter information and click on Add.
  5. After the client secret is created, copy the newly created Client Secret Value into the clipboard. This will be your only chance to access the client secret value, so copy it immediately after it is generated. Also, be careful not to accidentally use the Secret ID which is not the same and will not work.
  6. Return here and paste the Client Secret Value into the following field.
    [          ]
    Use caution to keep this value private.
  7. Make a note of the expiration date of your client secret and update as needed in both Azure and WhenToWork to avoid any interruptions in SSO functionality.

Click on Next.

b.  Upload PRIVATE KEY from Certificate

Use this option to authenticate WhenToWork with your SSO service provider using a certificate, and you already have a certificate or .pfx file containing your private key.
  • If you have a .pfx file type, you can export the private key using
      openssl pkcs12 -in domain.pfx -nocerts -out domain_pk.pem -nodes
  • Once you have the certificate and a PEM-formatted PRIVATE KEY file, click on “Choose File” and select that private key file.
     
  • Then go to “Certificates & secrets” under “App Registrations” in Azure AD, and upload the cert file under the “Certificates” tab.
  • Locate the associated thumbprint and copy it into your clipboard. Note, you may have to look in Azure’s application Manifest to read the entire thumbprint.
  • Return to this configuration page and paste it into the following Thumbprint field: 
  • Make a note of the expiration date of your certificate and update as needed in both Azure and WhenToWork to avoid any interruptions in SSO service.

Click on Next.

 

c. Generate PKCS#1 PRIVATE KEY for Certificate

Use this option to authenticate WhenToWork with your SSO service provider using a certificate, and you do not already have an externally-generated private key.
  • Click on  
  • Save the file in a safe location using a filename such as private_key.pem
  • Open a command prompt and enter:
      openssl req -new -key private_key.pem -out myreq.csr
  • You will the be prompted to enter fields in accordance with your openssl config file, openssl.cnf.
  • Use the resulting certificate signing request file, myreq.csr, to purchase an SSL certificate from the Certificate Authority of your choice, or generate a self-signed certificate using
      openssl x509 -signkey private_key.pem -in myreq.csr -req -days 365 -out domain.crt
  • Once you have the certificate, go to “Certificates & secrets” under “App Registrations” in Azure AD, and upload the cert under the “Certificates” tab.
  • Locate the associated thumbprint and copy it into your clipboard. Note, you may have to look in Azure’s application Manifest to read the entire thumbprint.
  • Return to this configuration page and paste it into the following Thumbprint field: 
  • Make a note of the expiration date of your certificate and update as needed in both Azure and WhenToWork to avoid any interruptions in SSO service.

Click on Next.