In this article:

SSO/Penelope Authentication Settings Reference

Authentication Type Setup

Login Settings

Single Sign On (SSO) Setup

Enable both SSO and Penelope Authentication for the first time (7 steps total, 2 optional)

Troubleshooting


Built-in Penelope authentication is enabled by default. Complete these steps to enable SSO authentication using your organization’s Identity Provider.

Caution

We highly recommend enabling both SSO and Penelope Authentication even if you plan to only use SSO Authentication. Enabling both options allows you to successfully test and reconfigure SSO Authentication settings as needed. If you enable SSO Authentication only, you risk locking user accounts, including System Administrator accounts, if they haven’t been properly configured in your IDP prior to completing the full SSO configuration in Penelope. As such, every worker and System Administrator account in Penelope that will use SSO authentication must be set up with a valid account in your IDP.

SSO/Penelope Authentication Settings Reference

Penelope and SSO Authentication Edit screen

Authentication Type Setup

Setting

Description

Choose authentication type

The authentication type you’d like to implement at your organization: Single Sign On (SSO) using your OAuth 2.0-compatible Identity Provider, built-in Penelope authentication, or both.

Default authentication

If you have chosen to use both Penelope and SSO accounts as available authentication types, you can choose which authentication type is the default option. The default authentication type appears as the default sign in option.

Login Settings

These configuration settings apply to organizations that have chosen to use Penelope Authentication or both Penelope and SSO Authentication.

Setting

Description

Send alert message to

An option to select which Worker Category should receive Authentication alerts.

Passwords must be changed every X day(s)

The frequency (in days) in which Workers must change their passwords.

Lock user accounts after X days since last login

The maximum number of days that a Worker can go without logging in to Penelope prior to their account being automatically locked.

Enter 0 if you do not want to use this feature.

Maximum verification codes per user per day

The maximum number of verification codes that can be sent to a single Worker per day.

Maximum total verification codes per day

The maximum number of verification codes that can be sent to all Workers organization-wide per day.

Prompt user to confirm trusted devices every X months

The frequency in months in which each Worker must confirm the trusted devices they have set up for their user account.

Admin review of trusted emails

An option to require that a Worker with System Administration or Superuser privileges must review and approve a trusted email address.

Admin review of trusted phone numbers

The option to require that a Worker with System Administration or Superuser privileges must review and approve a trusted phone number.

Single Sign On (SSO) Setup

These configuration settings apply to organizations that have chosen to use SSO Authentication only or both Penelope and SSO Authentication types.

Important Information

The terminology in the SSO setup in Penelope corresponds with standard OAuth 2.0 terminology. Your Identify Provider (IDP) may use different terminology for these settings.

Setting

Description

SSO provider

An option to select which IDP your organization uses. You can choose between Google, Microsoft, or a Custom Identity Provider.

Authentication endpoint

The URL to the endpoint on the authorization server of your IDP that processes the access request from the Worker. The authorization endpoint enables Penelope to obtain required access to your IDP by requesting authorization on the Worker's behalf.

If you select either Google or Microsoft Office 365 as your IDP, the Authentication endpoint field pre-populates for you and you should not need to change it. If you select Custom Identity Provider as your IDP, you must paste the applicable Authentication endpoint. This information can be found through your IDP.

Token endpoint

The URL to the token endpoint on the authorization server of your IDP that exchanges the authorization code, application ID, and application secret for an access token.

If you select either Google Identity or Microsoft Office 365 as your IDP, the Token endpoint field pre-populates for you and you should not need to change it. If you select Custom Identity Provider as your IDP, you must paste the applicable Token endpoint. This information can be found through your IDP.

Application ID

The unique identifier for Penelope given by your IDP.

Application secret

The unique passcode or secret for the Penelope application given by your IDP.

Security group (scope)

An optional setting to define a specific group of Workers who have accounts in your IDP that should have access to Penelope. This setting ensures that the IDP knows to only authenticate people with scope set to the defined Penelope security group.

Label for Penelope credentials

An option to set a custom label that will display for Workers logging into Penelope using the built-in Penelope authentication, as well as all other locations throughout Penelope where authentication is referenced (for example, on the Worker Profile). The label defaults to Penelope.

Login description for Penelope

An option to set a custom description for built-in Penelope authentication that appears on the login page only. The description can be used to help Workers understand which credential they should use.

Label for SSO credentials

An option to set a custom label that displays for Workers logging into Penelope using SSO authentication as well as all other locations throughout Penelope where authentication is referenced (for example, on the Worker Profile). The label defaults to Single Sign On (SSO).

Login description for SSO

An option to set a custom description for SSO authentication that appears on the login page only. The description can be used to help workers understand which credential they should use.

Enable both SSO and Penelope Authentication for the First Time

Step 1: Register Penelope in your IDP

You must register Penelope in your Identify Provider (IDP). As each IDP is different and may include a variety of steps, we recommend you consult your IDP for relevant instructions and guidance to configure Penelope as an application.

You will also need to record values for the following fields from your IDP for later use in Penelope:

  • Authentication endpoint

  • Token endpoint

  • Application ID

  • Application secret

  • (Optionally) Security group or scope

***Important***

You will need multiple redirect URIs in order for the SSO to function properly. Those will be in the following format:

This has been tested with Okta, and you will end up with a 400 error during testing if you do not add the secondary URI.

Step 2: Configure SSO and Penelope Authentication

1. Navigate to User Setup > Security > Authentication and click Edit.

2. From the Choose authentication type drop-down, choose Use both Penelope and SSO accounts.

Penelope and SSO Authentication Edit screen

3. In the Default authentication section, choose which Authentication type you want as the default.

4. In the Login Settings andOAuth 2.0 (OpenID Connect) Configurations sections, complete the fields based on your agency’s preferences. Refer to the SSO and Penelope Authentication settings reference topic for details on each field.

5. Click Save.

Step 3: Test SSO Authentication

From the Authentication tab > Single Sign On (SSO) Connection Test section, click Test.

SSO Connection Test

After you click Test, you will be directed to your IDP. You will need to enter login credentials for a valid IDP account. Note that these login credentials can be for any user account in the IDP. You do not necessarily need to use administrator access as this process simply tests the connection.

Penelope will display a result message telling you if the connection was successful or not. If you are successful, you can close the page and proceed with the next steps. If the connection is not successful, you will need to revisit the configuration items in Step 3 based on the contents of the error message and continue testing the connection until it is successful.

Step 4: Modify Worker Accounts to use SSO Authentication in Batch Mode

To update multiple Worker accounts to use SSO authentication, you can upload an SSO Identifier file with the required information for SSO authentication:

  • The Worker’s unique identifier (UID) from your Identify Provider (IDP)

  • The Penelope KBookitemID value from Penelope

  • The First Name and Last Name values from Penelope

To assist with creating the SSO identifier file, you can download two files from Penelope that specifies which fields are required:

User Authentication Status (useresinfo.csv) file can assist you in gathering the KBookitemID, First Name, and Last Name values.

Example of the User Authentication Status file

The Sample SSO Identifier (sample.csv) file is what you will use to upload relevant Authentication values to Penelope to allow Workers to use their SSO credentials. The data you will input into this file comes from the User Authentication Status file in Penelope along with the UID from your IDP.

Example of the SSO Identifier File

When uploading the completed SSO Identifier file to Penelope, Penelope uses these unique identifiers to ensure the correct Worker profile is updated with the UID from your Identity Provider. We do not recommend relying only on the firstname and lastname columns as your organization may have more than one Worker with the same first and last name. If you upload an SSO identifier file with duplicate first and last names, Penelope will ignore the duplicate instances.

Prerequisite: Each Worker must already have a Penelope account. If you include any worker information in the upload file for Workers who do not already have a Penelope account, Penelope will not automatically create a Worker account through the upload.

  1. On the Authentication tab, locate the Syncronize UID > Sample SSO identifier file (csv) field and click the adjacent Download option and open the file in your preferred spreadsheet program.

  2. On the Maintenance tab, locate the User Authentication Information > Download User Authentication Status field and click the adjacent Download option and open the file in your preferred spreadsheet program.

  3. For each Worker, copy the following values from the usersInfo.csv (User Authentication Status) file to the sample.csv (Sample SSO identifier) file:First nameLast nameKBookitemID

  4. In your Identity Provider, locate the unique identifier (UID) for each Worker and copy the value into the sample.csv (Sample SSO identifier) file.

  5. Save the file.

  6. In Penelope, navigate to User Setup > Security > Authentication > Synchronize UID.

  7. Next to Upload SSO identifier file (csv), click Choose File. Locate the sample.csv file and upload.

After you finish: To verify that each worker account has been updated with SSO authentication information, you can search for a Worker Profile and verify the Login Credentials.

Important Information

You can also modify Worker accounts to use SSO individually. Review the Modify individual Worker accounts to use SSO authentication topic for more information.

Step 5: (Optional) Modify the Authentication Type to use SSO Authentication Only

Complete this step if you plan to use only SSO Authentication and have completed all other configuration steps. You should also ensure that your System Administrator accounts have been configured properly to use SSO.

Caution

We highly recommend maintaining both SSO and Penelope authentication even if you plan to only use SSO authentication for Worker logins. Enabling both authentication options allows you to successfully test and reconfigure SSO authentication settings as needed.

If you enable SSO authentication only, you risk locking Worker accounts (including System Administrator accounts) if they haven’t been properly configured in your IDP prior to completing the full SSO configuration in Penelope. As such, every Worker and System Administrator account in Penelope that will use SSO authentication must be set up with a valid account in your IDP.

  1. Navigate to User Setup > Security > Authentication tab and click Edit.

  2. From the Authentication type setup drop-down, choose Use SSO account only.

  3. Click Save.

Step 6: (Optional) Configure additional Penelope Authentication Settings

If you plan to use both Penelope and SSO Authentication options, you can configure additional features like 2-Step Login, Security Questions, and User Managed Password Reset. For more details, see the Penelope Authentication section.

Did this answer your question?