Sections
2-Step Login (2FA/Multi-factor Authentication)
Authentication refers to how users are validated to access the Penelope database. Each worker has a unique username and confidential password that allows them to log in to the Penelope database.
In version 4.4.0.0 and higher of Penelope there are two types of authentication that you can choose to implement in your database:
Single Sign On (SSO) authentication using an Identify Provider (IDP)
Penelope authentication
You can also choose to employ a combination of SSO and Penelope authentication. Organizations that employ large numbers of volunteers, students or other staff who don’t have user accounts in the IDP may choose to employ both types of authentication.
Getting Started
In this section
About Authentication
Authentication refers to how users are validated to access the Penelope database. Each worker has a unique username and confidential password that allows them to log in to the Penelope database. In version 4.4.0.0 and higher of Penelope, there are two types of authentication that you can choose to implement in your database: Single Sign On (SSO) authentication using an Identify Provider (IDP) and native Penelope authentication.
Additionally, you can also choose to employ a combination of SSO and Penelope authentication. Organizations that employ large numbers of volunteers, students, or other staff who don’t have user accounts in the IDP may choose to employ both types of authentication.
Penelope Authentication
Penelope authentication refers to the use of Penelope’s built-in username and password functionality and the built-in password algorithm. When a worker account is created, a unique username is assigned and you can set a temporary password that the worker can update.
The algorithm for passwords has been designed to better counteract hacking attempts than standard password requirements like requiring a certain number of uppercase characters or numbers. Instead, passwords must meet minimum security requirements based on mathematical difficulty to crack.
Enhancing Penelope Authentication
You can enhance the security of the authentication process by using the 2-step logins, trusted devices, security questions, and/or user managed reset options:
• The 2-step login method enables you to set up additional identity checks (using trusted devices and/or security questions) that users must fulfill to access Penelope.
• A trusted device is an email address or SMS phone number that you have assigned to your user account in Penelope.
• Security questions are a method of verifying the user’s identity where only the user should know the answers to the questions.
• If trusted devices and security questions are enabled, you can make use of the new user managed password reset process allowing the user to reset their own password.
SSO Authentication
Single Sign On (SSO) is an authentication process that allows organizations to manage login credentials for multiple applications in a singular location using an Identity Provider (IDP). The SSO feature in Penelope allows you to use your agency’s existing IDP to manage the username and password that workers use to log in to your Penelope database.
The SSO feature in Penelope uses the OAuth 2.0 protocol, which allows Penelope to connect to an external server to authenticate a user. To implement SSO for your organization, your organization’s IDP must use OAuth 2.0. Examples of IDPs that use OAuth 2.0 and are supported for use with Penelope include Azure (Microsoft Office 365 and Windows 2016) and Google for Business.
SSO authentication in Penelope is limited to maintenance of usernames and passwords. Each user must have an account set up in both Penelope and the IDP. Security settings regarding access and privileges within the Penelope database must also be configured and maintained through Penelope’s built-in security settings.
Penelope Authentication
In this section
About Penelope Authentication
Penelope authentication refers to the use of Penelope’s built-in username and password functionality and the built-in password algorithm. You can enhance the security of the authentication process by using the 2-step logins, trusted devices, security questions, and/or user managed reset options.
Password algorithm
In version 4.1 and above, the algorithm for passwords reflects increased security measures. Instead of requiring that you configure password requirements, passwords must meet minimum security requirements based on mathematical difficulty to crack. As a best practice, we recommend that passwords include a mixture of lower and uppercase letters, numbers, and symbols. Further, you should combine the characters in such a way to create a lengthy password.
2-step logins
The 2-step login method enables you to set up additional identity checks (using trusted devices and/or security questions) that users must fulfill to access Penelope. You can require that, after a specified number of logins, users must respond to a security question or type in a verification code that has been sent to a trusted device.
Further, each time a user logs in to Penelope through a new browser or after they have cleared their cache/cookies, they are required to provide their 2-step login credentials. A trusted device is an email address or SMS phone number that you have assigned to your user account in Penelope. 2- step logins make use of your trusted devices by sending a verification code to the device.
To make use of trusted devices, you must have your External Communication settings enabled. Security questions are a method of verifying the user’s identity where only the user should know the answers to the questions. A System Administrator can set up a list of security questions that users can configure answers for.
User managed password reset process
If trusted devices and security questions are enabled, you can make use of the new user managed password reset process. The user managed password reset feature allows a user to reset their own password. To reset their password, the user must enter the verification code that has been sent using their External Communication settings and input the correct response to their security question.
Maintenance features
Security maintenance features include the ability to require that an administrator review trusted devices, an advanced mechanism for unlocking user accounts, and the ability to force a 2-step login or password reset for all users.
Configure Penelope Authentication for the First Time
Penelope authentication is enabled by default. Complete these steps to customize the Penelope authentication options.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use Penelope account only. 5. In the Login Settings section, complete the following fields:
6. Click Save.
Authentication Type Setup Options
Security Password Setup Options
These configuration settings apply to organizations that have chosen to use Penelope authentication or both Penelope and SSO authentication.
2-step login
In this section
About the 2-Step Login Method
The 2-step login method enables you to set up additional identity checks using trusted devices and/or security questions. You can require that, after a specified number of logins, users must respond to a security question or type in a verification code that has been sent to a trusted device.
Further, each time a user logs in to Penelope through a new a new browser or after they have cleared their cache/cookies, they are required to provide their 2-step login credentials. A trusted device is an email address or SMS phone number that you have assigned to your user account in Penelope. 2- step logins make use of your trusted devices by sending a verification code, or pin, to the device.
To make use of trusted devices, you must have your External Communication settings enabled. Security questions are a method of verifying the user’s identity where only the user should know the answer to the question. A System Administrator can set up a list of security questions that users can configure answers for.
Set Up an Authentication Email
To enable the 2-step login feature using trusted devices, you must configure your External Communication settings (i.e. email and/or SMS).
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the System Setup section, click External Communications.
2. In the Authentication Email section, click edit.
3. Complete one of the following options:
a. To use the same email settings as your general settings, click the Use standard email settings option.
b. To configure a different email for Authentication, complete the following fields using the information as provided by your provider:
4. Click Save.
5. To ensure the settings are configured accurately, click Test.
6. In the Recipient field, type an email address to send a test email to.
7. In the Subject and Body fields, type content you would like to include in the test email.
8. Click Save.
9. If the test email is received successfully, click Enable. Otherwise, review and adjust the settings in step 3 until the test passes.
Configure the 2-Step Login Feature for the First Time
Prerequisite: You must be logged in to Penelope using a System Administrator account. To enable trusted devices, you must configure your external communication settings. For more information about configuring your external communication settings, see Set up external communication accounts.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 2-step log in section, click Enable.
4. Click Edit.
5. Complete one or more of the following options:
a. To enable trusted devices as a 2-step login method, in the Enable trusted devices section, choose one of the following options:
i. Via email
ii. Via SMS
iii. Via email or SMS
b. To choose not enable trusted devices as a 2-step login method, in the Enable trusted devices section, click No.
c. To enable the use of Security Questions as a 2-step login method, click the Enable security questions option.
6. To specify how often users must access Penelope via a 2-step login method, in the Require 2-step login every field, type the number of logins that staff members can complete prior to requiring a secure login.
7. Click Save.
Enable or Disable the 2-Step Login Feature
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 2-step login section, complete one of the following actions:
a. To enable the 2-step login feature, click Enable.
b. To disable to 2-step login feature, click Disable.
Enable or Disable Trusted Devices
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 2-step log in section, click Edit.
4. Complete one of the following actions:
a. To enable trusted devices as a 2-step login method, in the Enable trusted devices section, choose one of the following options:
i. Via email
ii. Via SMS
iii. Via email or SMS
b. To disable trusted devices as a 2-step login method, in the Enable trusted devices section, click No.
5. Click Save.
Enable or Disable Security Questions
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 2-step log in section, click Edit.
4. Complete one of the following options:
a. To enable the use of Security Questions as a 2-step login method, click the Enable security questions option.
b. To disable the use of Security Questions as a 2-step login method, clear the Enable security questions option.
5. Click Save.
Change How Often 2-Step Login is Required
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 2-step log in section, click Edit.
4. To specify how often users must access Penelope via a 2-step login method, in the Require 2-step login every field, type the number of logins that staff members can complete prior to requiring a secure login.
5. Click Save.
Trusted Devices
In this section
About Trusted Devices
A trusted device is an email address or SMS phone number that you have connected to your user account in Penelope. 2- step logins make use of your trusted devices by sending a verification code to the device. Depending on your configuration, at the time of log in, you could be required to enter the verification code as shown on your trusted device(s).
Set How Often Users Must Confirm their Trusted Devices
To confirm a trusted device, users must review the current values for their email address or SMS phone number and confirm that they are correct.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. In the Login settings section, in the Prompt user to confirm trusted devices every field, type how often (in months) that users must confirm their trusted devices.
5. Click Save.
Require that Admins Review Trusted Devices
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. To require that admins review trusted devices, in the Login settings section, complete one or both of the following options:
a. Click the Admin must review 2-step email addresses option.
b. Click the Admin must review 2-step phone numbers option.
5. Click Save.
Accept or Reject an Email Address or SMS Number
If you have configured the option to require an Admin to review trusted email addresses and/or SMS phone numbers, you must review the email addresses and SMS numbers listed in the Review Email or SMS section.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
In the User Setup section, click Security.
Click the Maintenance tab.
In the Review Email and SMS section, choose one of the following options:
To accept or reject all messages, click Select All.
To accept or reject specific messages, select the adjacent checkbox.
Click Accept or Reject as appropriate.
Configure which Worker Category Receives Alerts for Authentication Events
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. In the Send Alert Messages To drop-down list, select which Worker Category you would like to receive authentication alerts.
5. Click Save.
Force all Users to Access Penelope using a 2-Step Login Method at Next Login
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Maintenance tab.
3. In the All Penelope Users section, click Force Secure Login for All Users.
Set Up a Trusted Email Address or SMS Phone Number for the First Time
Prerequisite: Your System Administrator must enable 2-step logins using trust devices. The next time you log in to Penelope, you will be prompted to type the trusted email address and/or SMS phone number.
Before you begin: Browse to your Penelope database. When prompted, type your User name and Password.
1. If applicable, in the Email field, type a trusted email address.
2. If applicable, in the SMS field, type a trusted SMS phone number.
3. On your keyboard, press Enter.
Update a Trusted Email Address and/or SMS Phone Number
Prerequisite: You must be logged into your Penelope worker account.
1. In the My Profile sidebar, click View My Profile.
2. In the Personal Message Settings section, click Edit.
3. In the Email field, type a trusted email address.
4. In the SMS field, type a trusted SMS phone number.
5. Click Save.
Verification Codes
In this article
About Verification Codes
A verification code is a short code that is sent to a user via a trusted email address or SMS phone number. The verification code must be entered into the login screen to access Penelope. You can configure the number of verification codes that can be sent to individual users and across the agency.
Depending on the size of your agency, you may need to set a higher number of verification codes that can be sent across the system on a given day. If the maximum number of verification codes has been reached, the worker category that you set to receive authentication messages is notified.
Set the Daily Maximum Number of Verification Codes for Users
Use this setting to determine the maximum number of verification codes that an individual worker can receive per day.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. In the Login settings section, in the Maximum verification codes per user per day field, type the maximum number of verification codes that a user can receive in a day.
5. Click Save.
Set the Daily Maximum Number of Verification Codes for your Agency
Use this setting to determine the maximum number of verification codes that can be sent across the agency per day.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. In the Login settings, in the Maximum total verification codes per day field, type the maximum number of verification codes that can be sent for the whole agency.
5. Click Save.
Security Questions
In this section
About Security Questions
Security questions are a method of verifying the user’s identity where only the user should know the answers to the questions. A System Administrator can set up a list of security questions that users can configure answers for.
Best Practices: Security Questions
1. Avoid using standard security questions available on Social Networking sites.
2. Avoid creating security questions that colleagues would know the answers to.
3. Create three times more questions for users to choose from than the number of answers you will require that they create. For example, if you require that users create three responses, you should create a minimum of 9 questions.
4. Consult your territorial, regional, or industry best practices to create specific security questions.
Set the Minimum Number of Security Questions that Users Must Configure
Security questions are used for user managed password reset and, optionally, for 2-step login authentication. You can set the minimum number of security questions that users must create answers for. Users will only be asked to provide an answer to one of the questions that they have configured.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the Security questions section, next to Minimum number of security questions users must create answers for, click (edit).
4. In the Minimum number of questions users must create answers for field, type the minimum number of questions that you want staff members to create answers for.
5. Click Save.
Create a List of Security Question Options
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the Security questions section, click Add.
4. In the Question text field, type the desired security question.
5. Click Save.
To add additional security questions, repeat steps 3-5.
Edit the Text of a Security Question
You can only edit the text of an inactive security question. You cannot edit the text of an active security question because it may be in use by users and their answers may become inaccurate.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the Security questions section, click the security question whose text you want to edit.
4. In the Question text field, edit the text as required.
5. Click Save.
Activate a Security Question
To allow users to make use of the security question that you’ve created, you must activate the question.
Caution: Once a security question is activated, the question cannot be edited, and it becomes available immediately for users to create answers for.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the Security questions section, click the security question that you want to activate.
4. Click the Active option.
5. Click Save.
Delete a Security Question
Caution: Deleting an active question will also delete any security question answer set up by a user.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the Security questions section, click (-) icon next to the Security Question that you want to delete.
4. Click okay.
Set Up Security Questions Responses for the First Time
Prerequisite: Your System Administrator must enable 2-step logins using security questions.
The next time you log in to Penelope, you will be prompted to provide answers to the number of questions that your System Administrator has required.
Before you begin: Browse to your Penelope database. When prompted, type your User name and Password.
1. Complete one of the following options:
a. To respond to the first available question, in the answer field, type a response.
b. To choose a different question to answer, click the arrow buttons next to the question. In the answer field, type a response.
2. Click Add.
3. Repeat steps 1 and 2 until you have created responses for at least the minimum number of questions required by your System Administrator.
4. Click Send.
Update your Security Question Responses
Prerequisite: You must be logged into your Penelope worker account.
1. In the My Profile sidebar, click View My Profile.
2. In the Security Questions section, press the (-) icon to delete the security question you no longer want to use.
3. In the Security Questions section, click Add.
4. In the Question drop-down list, select a question to configure.
5. In the Answer field, type an answer.
6. Click Save.
Depending on how many security questions that your System Administrator has required you to set up, repeat steps 2-5.
User Managed Password Reset
In this section:
Unlock a user account
About User Managed Password Reset
If trusted devices and security questions are enabled, you can make use of the new user managed password reset process.
The user managed password reset feature allows a user to reset their own password. To reset their password, the user must enter the verification code that has been sent using their External Communication settings and input the correct response to their security question.
Enable the User Managed Password Reset Feature
The user managed password reset feature allows a user to reset their password using their trusted devices and security questions.
Prerequisite: You must be logged in to Penelope using a System Administrator account. You must also have 2-step logins enabled with at least one trusted device as well as security questions configured.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the User managed password reset section, click enable.
Disable the User Managed Password Reset Feature
The user managed password reset feature allows a user to reset their password using their trusted devices and security questions.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the User managed password reset section, click disable.
Reset your Account Password
Prerequisite: Your System Administrator must enable the User managed password reset feature. You can reset feature your own password using your trusted devices and the sent verification code.
Before you begin: Browse to your Penelope database.
1. Click Reset account password.
2. In the User name field, type your user name.
3. On your keyboard, press Enter. A verification code will be sent to your trusted device(s).
4. In the Verification code field, type the verification code that was sent to your trusted device.
5. On your keyboard, press Enter.
6. In the New password field, type a new password.
7. In the Confirm password field, type the new password again.
8. On your keyboard, press Enter.
Passwords
In this section
About Passwords
Penelope account passwords must meet minimum security requirements based on mathematical difficulty to crack rather than specific requirements (like a certain number of uppercase letters or symbols).
Passwords should include a mixture of lower and uppercase letters, numbers, and symbols; you should combine the characters in such a way to create a lengthy password.
When setting up your password, Penelope will indicate to you whether the password is weak, strong, or stronger. A password must be strong or stronger to fulfill requirements.
Set how often users must change their passwords
You can configure how often users must change their passwords in Penelope. Users will be prompted to create a new password to access Penelope after the specified period of time and each time a System Administrator resets their password. New passwords cannot be the same as the last 10 passwords.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. In the Login settings section, in the Passwords must be changed every field, type how often (in days) that users must change their passwords.
5. Click Save.
Force all users to reset their password at next login
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Maintenance tab.
3. In the All Penelope Users section, click Force Password Reset for All Users.
Unlocking user accounts
A user account is locked when one of the following actions occur:
• The user has 5 consecutive failed login attempts
• The System Administrator or Super User sets or resets a user’s password and the user does not log in to the database within 3 days Please note that System Administrator accounts will also lock after 5 failed login attempts.
We highly recommend ensuring that you have either a second System Administrator account or a Superuser available with access to unlock and reset passwords.
Unlock a user account from the User Account Maintenance page
Prerequisite: You must be logged in to Penelope using a System Administrator account or an Superuser account (defined as someone with access to the Setup sidebar and the ability to create and modify Worker Profiles).
1. Complete one of the following actions:
• If you are logged in as a System Administrator, in the User Setup section, click Security > Maintenance.
• If you are logged in as a Superuser, in the Setup sidebar, click User Accounts Maintenance.
2. In the Locked Accounts section, choose one of the following options:
• To unlock all locked accounts, click Select All.
• To unlock a specific account, select the adjacent checkbox.
3. Click Unlock.
After you finish: You can optionally reset the user’s password from the Worker Profile page following the directions in the Reset a user’s password topic below.
Unlock a single user account from the Worker Profile page
1. Browse to the Worker Profile whose account needs to be unlocked.
2. In the Login Credentials section, click Unlock.
After you finish: You can optionally reset the user’s password from the Worker Profile page following the directions in the Reset a user’s password topic below. Reset a user’s password
Prerequisite: You must be logged in to Penelope using a System Administrator account or an Superuser account (defined as someone with access to the Setup sidebar and the ability to create and modify Worker Profiles).
1. Browse to the Worker Profile whose password you want to reset.
2. In the Login Credentials section, click Change.
3. Click the Change password option.
4. Type a temporary password in both the New password and Retype New Password fields.
5. Click Save.
6. Provide the temporary password to the user so that they can log in for the first time.
After you finish: The user will be prompted to change their password once they log in successfully with the temporary password.
SSO Authentication
In this section
About SSO Single Sign On (SSO) is an authentication process that allows organizations to manage login credentials for multiple applications in a singular location using an Identity Provider (IDP).
The SSO feature in Penelope allows you to use your agency’s existing IDP to manage the username and password that workers use to log in to your Penelope database. The SSO feature in Penelope uses the OAuth 2.0 protocol, which allows Penelope to connect to an external server to authenticate a user.
To implement SSO for your organization, your organization’s IDP must use OAuth 2.0. Examples of IDPs that use OAuth 2.0 and are supported for use with Penelope include Azure (Microsoft Office 365 and Windows 2016) and Google for Business. For important ADFS compatibility information please visit: https://intercom.help/ssgpenelope/en/articles/5125822-getting-started-with-single-sign-on
To configure SSO in Penelope, you must first set up a publicly accessible URL for Penelope that is accessible by your IDP. This URL must be static, and you should avoid using an alias.
Next, you need to register Penelope as an application in your IDP while also entering the external URL for Penelope and determining which users should have access to Penelope. You can then set up the SSO feature in Penelope including the relevant configuration details from your IDP. When you have finished the configuration in Penelope, you must test SSO. Worker accounts in Penelope can then be updated to include their unique SSO credentials.
The SSO feature in Penelope does not include automatic synchronization of accounts; this means each new worker’s user account must be created in both Penelope and your IDP. Further, there is no synchronization of deactivated accounts, so accounts must be deactivated in both the IDP and Penelope. If a worker is active in SSO but not in Penelope, they will be unable to login to Penelope despite successfully entering SSO login credentials.
Although the worker would not be able to log in to Penelope in this scenario, we recommend deactivating former staff members in Penelope as well to avoid having the names of inactive workers appear in future reporting and Service File assignment lists.
Although you can configure Penelope to include the use of both SSO and built-in Penelope authentication, each worker account can use a single authentication method. If you have a group of workers that need access to Penelope but are not configured in your IDP, their accounts should use the default and built-in Penelope authentication process.
The SSO authentication process manages the username and password that the worker uses to log in to the database. Note that password security is managed through your IDP and does not use Penelope’s built-in password algorithms or other security enhancements like two-step logins or security questions.
When you enable SSO authentication, you choose to override the security algorithms used by built-in Penelope authentication. Your organization needs to ensure that the IDP password requirements meet the appropriate standards for a clinical setting.
Authorization configuration for a Penelope user must also still occur with Penelope’s built-in security functionality. This configuration includes managing which aspects of the Penelope database a user has access to; for example, Service Files, the Intake Wizard, Groups, etc.
Process Flow: Enable SSO Authentication
Enable Both SSO and Penelope Authentication for the First Time
Built-in Penelope authentication is enabled by default. Complete these steps to enable SSO authentication using your organization’s Identity Provider.
Note: We highly recommend enabling both SSO and Penelope authentication initially, even if you plan to only use SSO authentication in the long term.
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 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.
Step 1: Configure the External Address for Penelope
To configure SSO in Penelope, you have a publicly accessible URL for Penelope. The URL resides in the resin.properties file and is typically configured when installing Penelope for the first time or when upgrading to v4.8.0.0 or higher.
Step 2: 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
Step 3: Configure SSO and Penelope Authentication
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use both Penelope and SSO accounts.
5. In the Default authentication section, choose which account type you want as the default.
6. (Optional) In the Login Settings section, complete the following fields if you plan to use both SSO and Penelope authentication:
7. In the OAuth 2.0 (OpenID Connect) Configurations section, complete the following fields:
8. Click Save.
Authentication type setup options
Step 4: Test SSO Authentication
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. In the 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 5a: 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; namely, the worker’s unique identifier (uid) from your Identify Provider (IDP).
To assist with creating the SSO identifier file, you can download a template from Penelope that specifies which fields are required. The SSO identifier file template includes columns to capture the following information: kbookitemid, userid, firstname, lastname, and uid. The kbookitemid and userid columns are unique identifiers for workers in Penelope.
You can download a copy of the Penelope-based user authentication information to assist in gathering the kbookitemid and userid values. 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. Note that 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.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. On the Authentication tab, locate the Syncronize UID > Sample SSO identifier file (csv) field and click the adjacent Download option.
2. On the Maintenance tab, locate the User Authentication Information > Download User Authentication Status field and click the adjacent Download option.
3. For each user, copy the following values from the usersInfo.csv (User Authentication Status) file to the sample.csv (Sample SSO identifier) file:
• First name
• Last name
• KBookitemID
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 SSO identifier 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.
Step 5b: Modify Individual Worker Accounts to use SSO Authentication
Prerequisite: You must be logged in to Penelope using a System Administrator account or a Super User account with access to modify a Worker Profile.
1. Click Search.
2. On the Worker tab, in the Worker Name field, type the name of the worker whose authentication settings you want to update.
3. On the Worker Profile, in the Login Credentials section, click Change.
4. In the Login using section, select Single Sign On (SSO).
5. In the New SSO Identifier field, paste the unique ID (sometimes called UID, SID, Object ID, etc.) for the worker as provided by your IDP.
6. Click Save.
7. Repeat steps 1 through 6 for all remaining workers.
Step 6: (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 (steps 1 through 5). You should also ensure that your System Administrator accounts have been configured properly to use SSO.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. Click Save.
Step 7: (Optional) Configure Additional Penelope Authentication Settings
Complete this step if you plan to use both SSO and Penelope authentication types. For more details, see the Penelope authentication section.
Manage SSO Authentication
Modify the Application ID for Penelope
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Application ID field, type the application ID for Penelope defined by your IDP.
6. Click Save.
Modify the Application Secret for Penelope
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Application secret field, type the application secret for Penelope defined by your IDP.
6. Click Save.
Modify the Security Group for Penelope
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Security group (scope) field, type the security group for Penelope defined by your IDP.
6. Click Save.
Modify the Label for Penelope Credentials
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Label for Penelope credentials field, type the desired label for Penelope authentication.
6. Click Save.
Modify the Login Description for Penelope
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Login description for Penelope field, type the desired description for Penelope authentication.
6. Click Save.
Modify the Label for SSO Credentials
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Label for SSO credentials field, type the desired label for SSO authentication.
6. Click Save.
Modify the Login Description for SSO
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use SSO account only.
5. In the OAuth 2.0 (OpenID Connect) Configurations section, in the Login description for SSO field, type the desired description for SSO authentication.
6. Click Save.
Disable SSO Authentication
If you disable SSO authentication in Penelope, all worker accounts will automatically revert back to using their original Penelope usernames and passwords. Any workers who are logged into Penelope at the time that SSO authentication is disabled will automatically be logged out. We recommend implementing the User managed password reset feature to allow staff to reset their own Penelope passwords after SSO authentication is disabled.
Prerequisite: You must be logged in to Penelope using a System Administrator account.
1. In the User Setup section, click Security.
2. Click the Authentication tab.
3. Click Edit.
4. From the Authentication type setup drop-down, choose Use Penelope account only. 5. Modify other Penelope authentication settings as needed.
6. Click Save.