BusinessPlus Single Sign-On (SSO)

BusinessPlus 20.11.0 and later

BusinessPlus supports single sign-on (SSO) authentication for administrative users and Employee Online through third-party identity providers (IDPs), including Google and Microsoft.

Pre-requisites for SSO configuration

BusinessPlus SSO should first be configured in a Test or other non-live environment for acceptance testing and user training.

BusinessPlus requirements

1. BusinessPlus SSO is available for versions 20.11.0 and later.

   1. SSO is only available for BusinessPlus Core and Employee Online. 

   2. PC Products (for example: Admin Console, Document Capture, Workflow Designer, CDD) do not support SSO. PC Products require BP User (NUUPUS) credentials at login.

   3. Cognos is supported with SSO for versions 22.4.0 and later.

2. You must have System Administrator access to the BusinessPlus (BP) environment where you want to set up SSO.

   1. Access to NUUPCD, NUUPSO, NUUPUS, NUUTZZ.

   2. Access to restart IIS on all BP and Employee Online (EO) servers.

   3. Access to restart Data Processing Service on all BP web servers.

3. District Global Identifier (MOTU ID): Contact PowerSchool Support to request the MOTU District Global Identifier.

4. There needs to be a 1:1 user mapping between the BP or EO user account and the IDP account. If two accounts are in use (for example: Core BP and EO), these accounts must be merged by deactivating one account and keeping only one user account per user. 

   1. Keep the existing BP account which has security and deactivate the EO account. 

   2. Moving forward, use accounts which are autogenerated by NUUTNU, and add BP security to those accounts. 

5. Employee Online

   1. Active Employees require a user account in the district IDP to authenticate.

   2. Terminated Employees (employees with a termination date) are able to use the Former Employee login, using their NUUPUS user id and password. The Former Employee login does not use SSO.

      1. It is assumed that the employee’s district user account is deactivated.

      2. The employee must have a valid password set in NUUPUS.

Customer Identity Provider (IDP) requirements

1. Identity Providers

   1. Microsoft Azure

   2. Google

2. Supported Identity Standard: OIDC

3. Complete Client Application Configuration

   1. Client / Application ID and Client Secret

      1. Refer to Add OIDC Applications in SSO Identity Providers.

   2. Redirect URIs (these are case sensitive)

      1. BusinessPlus Core

         1. https://<BusinessPlus Farm URI>/BTMQ/signin-oidc

      2. Employee Online

         1. DMZ: https://<Employee Online URI>/BusinessPlus/signin-oidc 

         2. Internal Web Server: https://<BusinessPlus Farm URI>/BusinessPlus/signin-oidc

      3. Cognos: Refer to the Cognos SSO configuration section of this page.

4. Claim Identifier

   1. Claim Identifier for Microsoft is "OID"

   2. Claim Identifier for Google is "EMAIL"

5. Tenant ID (Microsoft Only): Refer to How do I find the Tenant ID question on FAQ: Setting up SSO.

6. Authority URL

   1. Microsoft Azure:  https://login.microsoftonline.com/[TenantID]/v2.0

   2. Google: https://accounts.google.com

7. Create BSI AD User Account for PowerSchool Support. This account will be used for PowerSchool to be able to authenticate

Use this chart used to gather the necessary information: 

Map users for SSO (bulk and individual)

This should be completed by the customer with PowerSchool Services support as needed. 

SSO Mappings are stored in the sso_user_mapping table. 

Individual user provisioning

1. Open Admin Console.

2. Launch Security Admin / Manage Users.

3. Search for the User ID.

4. Select the SSO Mapping tab.

   1. Add the mapping value and save.

   2. At minimum, a PowerSchool support account would be needed (for example, BSI) to complete the configuration.

Bulk user provisioning

BusinessPlus supports importing users into the SSO mapping table using a .csv or .txt file. BusinessPlus supports COMMA or TAB separated records.

Common code setup

1. Launch NUUPCD

2. Add a record with below values

 Create import file

1. Create a .csv or .txt file as follows for each BusinessPlus User ID. 

   1. Headers are required in the import file. 

Example Import File using Microsoft OID:

user_id,mapping_id
BSI,fe45a351bde745c38e902cd25b25f95a
SBI,648458afe7424a2d9abaf6d1c22b6e99
RBI,b494b939b88748c0a1efc4763aee5e47

Bulk import

1. Launch NUUTZZ

2. Click Location or Other and select the .csv or .txt import file. 

3. Select Trial Mode as No. Select Yes to verify the import file first, if desired.

4. Click Submit. 

5. Verify the job has completed and review the report file to confirm user mappings were added successfully. 

Generate encryption key

An Encryption Key should be generated only once per environment. If you are unsure if an Encryption Key already exists, try to save the NUUPSO configuration first. Replacing the existing key or re-generating a new encryption key will invalidate existing encrypted data. To change the key, all encrypted data must be decrypted with the old key and re-encrypted with a new key manually, and then save that data into tables.

Additional Steps can be referenced at Step 9 of the OAUTH2 Email Configuration. Refer to BusinessPlus OAUTH2 Email Configuration documentation.

1. Open Admin Console.

2. Launch Configure Local Server plug-in.

3. In the Tools area, double-click the Generate Key tool. This will only need to be executed once per BP environment.

Enable App Switcher (Motu ID configuration)

App Switcher should only be enabled for Production/Live environments. App Switcher cannot be configured for both Production and Test environment links. This will allow clients to switch between PowerSchool products. If other PowerSchool products are not in use, then the App Switcher will allow users to switch between BP and EO more easily, but is not required if they only have BP.

Pre-requisites

1. SSO with an external identity provider must be enabled for all PowerSchool applications you intend to include in the Applications list.

2. A single identity provider must be used for administrator and staff users across all applications you intend to include.

3. Your district must have two or more PowerSchool applications where AppSwitcher is available.

4. Unified Classroom must not be enabled.

5. AppSwitcher has been requested and your district applications have been set up for AppSwitcher.

Enable Applications icon

1. Contact PowerSchool Support to request to have the Global Identifier (MOTU) updated with the App Switcher District Settings.

2. In BusinessPlus, launch NUUPCD.

3. Add a Record with the below values:

   1. Code Category - MOTU

   2. Code Value - MOTUID

   3. Ledger - @@

   4. Long Description - District Global Identifier (MOTU GUID)

4. Restart IIS after setting up the common code.

NUUPSO configuration

1. Launch NUUPSO

2. Add a record with below values:

   1. Client ID

   2. Client Secret

   3. Authority URL

      1. Microsoft Azure:  https://login.microsoftonline.com/[TenantID]/v2.0

      2. Google: https://accounts.google.com

   4. Claim Type

      1. Google, select Email

      2. Microsoft, select OID

   5. Vendor Name: Google or Microsoft

   6. SSO Enabled: Selected

3. Press Enter to save settings.

4. Restart IIS on all BP and EO servers.

   1. Open Administrator Command Prompt

   2. Type IISReset into the command prompt, and press Enter. This will disconnect users. 

   3. If LDAP is also enabled at the district, it must be disabled in the BP Connection Properties. After disabling LDAP, a Restart of the Data Processing Services on all BP servers is required.  

Cognos SSO configuration

22.4.0 or later

Pre-requisites

1. Complete SSO configuration for BusinessPlus.

2. Ensure Cognos server configuration has been completed by the Cognos team.

3. Identify the IDP URL (URL for Identity Provider - Microsoft or Google)  

   1. Microsoft Example:

      1. https://login.microsoftonline.com/a7cc9b7f-3968-4812-9509-36e51ed0d0e9/v2.0

   2. Google Example:

      1. https://accounts.google.com

4. Provide the Client ID and Client Secret from Identity Provider to Professional Services if they are assisting with setup.

5. Redirect URL has been created in the Identity Provider (by Cloud or TSG)

   1. Cognos: https://<application server URI>//ibmcognos/redirect.asp

6. Provide the Claim Identifier to Professional Services if they are assisting with setup.

   1. PowerSchool recommends OID as the Microsoft Claim Identifier. If you use a different identifier for your existing SSO, we can leverage your current Claim Identifier.

   2. The Claim identifier for Google is Email.

Note: All configurations must be setup by a user with System Administrator privileges.

Provision Cognos for users

1. Login into Web Server where Admin Console is installed.

2. Select Manager Users.

3. Search for the User ID.

4. On the Main tab, select Cognos User.

Enable Cognos SSO

1. Open NUUPCO in BusinessPlus.

2. Select Cognos Enabled.

3. Complete the following data fields. Values provided are examples only.

   1. Cognos URL: http://bp-cognos11.corp.powerschool.int:9300/bi/v1/disp

   2. Root URL: https://bp-cognos11.bp.powerschool.com/ibmcognos/bi/v1/disp

4. Select SSO Enabled.

5. Enter your Client ID and Client Secret. The Client secret will be encoded to Base64 format after saving the record.

6. Enter the Authority URL.

7. Claim Type: OID or Email

8. Vendor: Microsoft or Google

9. Click Generate Secret to populate Private Key and Public Key. Private Key is encrypted when you save the record.

10. Issuer: powerschool

11. Audience: ibmcognos

12. Timeout: Enter number of minutes.

13. Save changes.

Reload CAP Properties

When changes are made in the Manage Cognos Configuration (NUUPCO) page, the following steps must be completed to update the Cognos properties.

1. Navigate to the following URL in the web browser: https://<application server URL>:9300/bi/?CAMNamespace=businessPlus&capReloadPropertiesFile=true

2. Reload of properties is successful when the message appears: Motio Custom Security: The custom authentication provider properties file was reloaded. Do not click the Sign In button.

3. Log out of the BusinessPlus application.

4. Restart IIS.

Disable SSO configuration from NUUPSO

1. Launch BusinessPlus application as a user with System Administrator privileges (for example: BSI).

2. Navigate to NUUPSO.

3. Clear the SSO Enabled checkbox.

4. Press Enter to Save.

5. Logout of BusinessPlus.

6. Restart IIS on all Web Servers and EO Servers. If LDAP was previously enabled, enable LDAP in the Connection Properties and restart Data Processing Service on all Web Servers.

Disable App Switcher from NUUPCD

App Switcher can also be disabled in BusinessPlus Test environment so it does not link to any other Production/Live PowerSchool products. 

1. Launch BusinessPlus application as a user with System Administrator privileges (for example: BSI).

2. Launch NUUPCD.

3. Search for and select the MOTU record with below criteria:

   1. Code Category - MOTU

   2. Code Value - MOTUID

4. Delete MOTU ID from Long Description field.

5. Save the Record.

6. Log out and then log back in to BusinessPlus.

Disable SSO configuration from database

If the IDP cannot be reached for authentication or if errors exist with the SSO configuration, it may be necessary to disable SSO via SQL update statement. 

1. Launch Admin Console as a user who has access to the SQL Query screen.

2. Open Database Admin / Utilities / SQL Query.

3. Run the following SQL Update Statement: update sso_client_config set sso_enabled = N

4. Close Admin Console.

5. Restart IIS on all Web Servers and EO Servers. If LDAP was previously enabled, enable LDAP in the Connection Properties and restart Data Processing Service on all Web Servers.

Test SSO

Access BusinessPlus

1. Access the BP Farm URL.

2. When you load the BP Farm URL, it navigates to the loading page when the user tries to login immediately after IIS reset. After some time, a message instructs you to retry using Reload Page.

   1. Click Reload Page and the system redirects to the Microsoft or Google authentication page.

   2. Enter valid district credentials.

   3. After you are authenticated by the IDP, your BusinessPlus personal dashboard loads.

3. The App Switcher waffle icon should display.

4. Verify that Change Password is not displayed in the user name menu.

5. Click Sign Out. You will be signed out from BusinessPlus but not from the identity provider.

6. Click Return to BusinessPlus. Your dashboard should load without having to re-authenticate.

Access Employee Online

Employee Online should be tested using both EO on the dedicated EO (DMZ Hosted) server and the internal BP Farm servers. Repeat the steps for each URL.

1. Access the EO URL.

2. The Account Login page should appear, directing the user to select their authentication method.

   • Active Employees: Click here to log in with single sign-on (SSO) 

   • Former Employees: Click here to log in

Active Employees

1. Click Active Employees: Click here to log in with single sign-on (SSO).

2. The user should be redirected to their IDP (Google or Microsoft) for authentication.

3. Enter valid district credentials. After authenticated by the IDP, the user should see the Employee Online home page.

4. The App Switcher waffle icon should display.

Former Employees

To test, use an employee who has a termination date in the Term Date field on their Employee Master record (HREMEN). Verify the termination date aligns with the EO Global Settings for allowing terminated users access to Employee Online.

1. Click on Former Employees: Click here to log in.

2. The user should be redirected to the legacy Employee Online login page.

3. Login using a terminated employee NUUPUS user account. After authenticated, the user should see the Employee Online home page.

Terminate Employee

1. Disable the SSO or LDAP/AD account. This is done by IT.

2. HREMEN: Mark the employee as terminated using the Term Date on the Term Info tab. The EO application will refer to the Term Date to allow the traditional login.

3. NUUPUS or Admin Console, Manage Users

   1. Employee ID to have no access:

      • Remove all security roles

      • Set status to I (inactive)

      • Click the No Password, LDAP/SSO checkbox

      • Remove SSO Mapping

      • Rebuild the user

   2. Employee ID to have EO access:

      • Clear the No Password, LDAP/SSO checkbox

      • Make sure EMPLOYEE association is set

      • Set status to P if you want to force a password change.

There is no defined process of sharing ID and initial password as part of SSO.

FAQs and troubleshooting

1. If the traditional BP Login page is displayed:

   1. Clear local browser cache and attempt to login again.

   2. Refresh the browser window until user is redirected to the IDP login screen.

2. Make sure the redirect URLs are configured in IDP.

   1. Google Application redirect URIs may be case sensitive.

   2. Review against Redirect URIs saved in BusinessPlus web.config on all BP Servers (internal and external).

3. Verify the X:\inetpub\wwwroot\BusinessPlus\web.config accurately reflects the server URL. 

   1. On the BP Servers, the URL should reflect the BP Farm. 

4. On the EO Server, the URL should reflect the EO URL. 
   <add key="ida:PostLogoutRedirectUri" value="https://<application server URI>/BusinessPlus/account/SignIn" />
   <add key="ida:RedirectUri" value="https://<application server URI>/businessplus/signin-oidc"/>
   <add key="NewRelic.AgentEnabled" value="true" />
   <add key="NewRelic.AppName" value="EmployeeOnline" />

These settings are updated by using the BP Config utility and should be reviewed after running the BP Configuration utility.  Make sure on item number 4, that the URL value uses the correct BP farm URLS and not http://localhost.

5. Verify LDAP is not enabled. LDAP and SSO cannot be both enabled. Disable LDAP via Connection Properties in Admin Console.

6. Restart BP Data Processing Services and Reset IIS on all BP Web Servers. Reset IIS on EO Servers.

7. When a user logs out, are they logged out of the identity provider?

   • Single sign-out is not supported at this time. Users are not signed out of the identity provider or other PowerSchool products when they sign out. Refer users to the appropriate location to sign out of the identity provider. 

   • As a best practice for optimal security and privacy, when multiple employees access Employee Online using the same device, consider implementing the following recommendations:

a. Avoid using non-individual accounts : To prevent accessing information of any other employee avoid using non-individual accounts. This applies to the operating level ( Windows, iOS) and the BusinessPlus (application level)

b. Use Incognito Browser Window: To logout after each session from the BusinessPlus application and Identity provider. Quit the browser completely after each active session.

8. Does the HREMEN, Termination tab, Term Date need to be equal to today or in the past?

9. The Term Date needs to be in the past.

10. What happens if there is no SSO Mapping value and no Term Date?

    • The employee cannot log in to the application.

    • A Welcome to BusinessPlus page appears and includes the following messages and buttons:
      Your account was signed into BusinessPlus Application using your district’s identity provider. The identity provider’s session has not been signed out.
      Authentication failed. Click below to retry
      If the problem persists, contact your administrator.
      Button: Click here to log in with SSO - Current Employee
      Button: Click here to log in - Former Employee

11. What happens if employee’s Term Date is blank, today or in the future and has a valid SSO Mapping ID?

    • Only SSO Login is allowed, and employee can login.

12. What happens if employee’s Term Date is blank, today or in the future and has an invalid SSO Mapping ID?

    • Only SSO Login is allowed, and user does not have valid mapping, so user cannot login.

    • A Welcome to BusinessPlus page appears and includes the following messages and buttons:
      Your account was signed into BusinessPlus Application using your district’s identity provider. The identity provider’s session has not been signed out.
      Authentication failed. Click below to retry
      If the problem persists, contact your administrator
      Button: Click here to log in with SSO - Current Employee
      Button: Click here to log in - Former Employee

13. What happens if employee’s Term Date is in the past and has an invalid SSO Mapping ID?

    • Employee cannot log in with SSO but can log in with Former Employee login option.

14. What happens if employee’s Term Date is in the past and has a valid SSO Mapping ID?

    • Employee can login with SSO and Former Employee login option.

15. What happens if employee’s Term Date is in the past and has no SSO Mapping ID?

    • Employee cannot login with SSO but can log in with Former Employee login option.

16. What happens to the Change Password Option in the EO application when SSO is enabled?

    • For Current Employee, the Change Password option is not available in the EO application.

    • For Former Employee, the Change Password option is displayed in the EO application, by selecting the circle with the user’s login initials in it.

There is no defined process of sharing ID and initial password as part of SSO.