In this article:
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
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. |
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. |
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. |
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.
3. In the Default authentication section, choose which Authentication type you want as the default.
4. In the Login Settings and OAuth 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.
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.
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.
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.
On the Authentication tab, locate the Synchronize UID > Sample SSO identifier file (csv) field and click the adjacent Download option and open the file in your preferred spreadsheet program.
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.
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
In your Identity Provider, locate the unique identifier (UID) for each Worker and copy the value into the sample.csv (Sample SSO identifier) file.
Save the file.
In Penelope, navigate to User Setup > Security > Authentication > Synchronize UID.
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.
Navigate to User Setup > Security > Authentication tab and click Edit.
From the Authentication type setup drop-down, choose Use SSO account only.
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.