PowerClerk Support Center

Program Design
Automations
Questions to ask yourself
Locating the Automations feature
Creating an Automation
FAQs
Communication Templates
Questions to ask yourself
Locating the Communications feature
Creating Communication templates
Feature reference
FAQs
Deadlines
Questions to ask yourself
Locating the Deadlines feature
How to create Deadlines
Feature reference
FAQs
Forms
Questions to ask yourself
Locating the Forms feature
How to create and edit Forms
Adding data fields
Configuring Forms
VersaForms
Sensitive Data Fields
Feature reference
FAQs
Roles
Questions to ask yourself
Locating the Roles feature
How to create and edit a Role
Feature reference
FAQs
Workflow
Questions to ask yourself
Locating the Workflow feature
How to create and edit the Workflow
Transitions
Changing a project's status
Feature reference
FAQs
Advanced Program Design
Channels
Locating the Channels feature
What are Channels?
Channels Checklist
3-Step Publishing Process
Channel Type A: Mark As Child
Channel Type B: Make Successor
Channel Type C and D: Create/Submit Related Project
Sending Signals
Document Templates
Questions to ask yourself
Locating the Document Templates feature
How to define a new Template
Feature reference
eSignatures
DocuSign template tags
Mapping eSignature tags
FAQs
Formulas and Calculated Fields
Questions to ask yourself
Locating the Formulas feature
How to create a Formula
Formula Data Dictionary
FAQs
Front Page
Questions to ask yourself
Locating the Front Page feature
How to edit the Front Page
FAQs
Incentive Design
Questions to ask yourself
Locating the Incentive Design feature
How to design an Incentive
Incentive Options
FAQs
Single Sign On (SSO)
Azure AD
Okta IDP Configuration
SP Configuration
PowerClerk API
Custom API IDs
FAQ
API Documentation for Developers
Application & Process Automation
Getting Started
Common Usage Scenarios
Using Custom IDs
API Method Reference
Code Samples
Administration
Business Days
Questions to ask yourself
Locating the Business Days feature
Setting up Business Days
FAQs
Dashboards
Questions to ask yourself
Locating the Dashboards feature
How to create widgets in your Dashboard
Other Dashboard Actions
Data Import
Questions to ask yourself
Locating the Data Import feature
How to validate a Data Import
FAQs
Duplicate Check
Questions to ask yourself
Locating the Duplicate Check feature
How to use Duplicate Checks
FAQs
ePayments
Questions to ask yourself
Locating the ePayments History feature
How to add ePayments
FAQ
Import From V2
Questions to ask yourself
Locating the Import From V2 feature
How to Import From V2
FAQs
Operation Status
Questions to ask yourself
Locating the Operation Status feature
How to use the Operation Status feature
FAQs
Program Info
Project Inquiry
Questions to ask yourself
Locating the Program Info feature
How to edit the Program Info menu
Notification Banners
Billing Info
FAQs
Program Statistics
Questions to ask yourself
Locating the Program Statistics feature
How to use Program Statistics
FAQs
Reports
Questions to ask yourself
Locating the Reports feature
How to setup Reports
Multi-instance reports
Integrate scheduled Reports
Cross-Program Reports
FAQs
Test Environment
Questions to ask yourself
Locating the Test Environment feature
How to setup a Test Environment
FAQs
User Administration
Questions to ask yourself
Locating the User Administration feature
How to work with User Administration
FAQs
Web Adapter Factory
Questions to ask yourself
Locating the Web Adapter Factory
What are Web Adapters
Input and Output Fields
Connecting, Testing, and Enabling
Maintenance and Alterations
Web Adapter Message Format
FAQ
Program Reporting
Data Fields
Questions to ask yourself
Locating the Data Fields feature
How to work with Data Fields
Custom Lists and Data Field Groups
Table form element
PV System + batteries element
FAQs
Milestones
Questions to ask yourself
Locating the Milestones feature
How to define a Milestone
FAQs
Project List Columns
Questions to ask yourself
Locating the Project List Columns feature
How to use Project List Columns
FAQs
Project Summary
Questions to ask yourself
Locating the Project Summary feature
FAQs
How to edit the Project Summary
Project Views
Questions to ask yourself
Locating the Project Views feature
How to edit Project Views
FAQs
Settings
My Account
Questions to ask yourself
Locating the My Account feature
How to use the My Account feature
Setting up Multi-Factor Authentication
MFA Recovery Guidelines
FAQs
FormSense
Questions to ask yourself
Locating the FormSense feature
How to use the FormSense feature
FAQs
Grant Access
Questions to ask yourself
Locating the Grant Access feature
How to Grant Access to users
FAQs
Integration Guides
Integration Guide 001: How to configure a Web Adapter – ArcGIS Implementation
Integration Guide 002: How to configure Electric Power Research Institute’s (EPRI) DRIVE Connect software with PowerClerk
PowerClerk Video Guides
New User Video Guide
Setting up Business Days
Dashboards
Edit Forms - Tutorial #1
Edit Forms - Tutorial #2
Configuring Forms
FormSense
Build A Formula
Automation with Formulas in Action Rules
Formulas and Advanced Visibility Rules
Calculated Fields
Milestones
Project Summary
Roles and User Administration
Visualize Workflows
PowerClerk User Group Sessions (UGS)
PowerClerk Responsive Admin View

Single Sign On (SSO)

SSO streamlines your utility customer experience and allows program users to use login credentials for PowerClerk, that were already created for other SSO utility services, for example to pay their monthly bill.

SSO feature


Questions to ask yourself about SSO:

What SAML 2.0 SSO provider can I use?
Why would I want to use SSO for my PowerClerk program?
How can I configure SSO for my program?

PowerClerk SSO Configuration

Single sign-on (SSO) is a session and user authentication service, which allows a user to create only one set of login credentials to access multiple applications. The service authenticates the end user for all the applications the user has been given rights to and eliminates the need to further prompt the user when switching applications during the same session.
 

Please note: SSO is available as an additional feature for PowerClerk (like web adapters). Please contact your PowerClerk Account Executive if you would like to add the SSO feature to your program. Implementing your SSO solution is possible with a variety of identity providers (IDPs). For example you can use the services of the following IDPs:

 
Before you begin configuration, make sure that you have a user account for the PowerClerk program you intend to configure. This will allow you to properly test the configuration, including the SAML responses.
 
The remainder of this webpage describes how to set up SSO for a PowerClerk program. The setup requires creating and configuring an application within your IDP. Also, certain information must be provided to CPR to configure PowerClerk as the Service Provider (SP). The sections below provide directions for configuration through Azure AD and Okta.
 

Azure AD Configuration

To configure Azure AD for PowerClerk, follow the steps outlined in the following Microsoft tutorial:
 
https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications.
 
In Step 1.6, the “Identifier (Entity ID)” needs to be configured is as follows:

  • Sandbox: https://cleanpowerdemo.com/PCITrial/
  • Production: https://powerclerk.com/

…and the “Reply URL” is:

  • Sandbox: https://<program_name>.cleanpowerdemo.com/PCITrial/MvcAccount/Login/Acs
  • Production: https://<program_name>.powerclerk.com/MvcAccount/Login/Acs

[where program_name is the host name of the PowerClerk program, found in the browser URL].
 
Please note: the other three (3) settings in Step 1.6 (i.e. Sign-on URL, Relay State, Logout URL) *do not* need to be configured (i.e. they should be left blank).
 
In Step 2, the following five (5) attributes need to be configured:

  • FirstName
  • LastName
  • Email
  • UserId
  • PowerClerkRoles

 
The PowerClerkRoles attribute will contain the name of the role in PowerClerk that the user should be assigned to (look to Figure 4 of the Okta configuration, below, for an example). See the following link for details on setting up application-defined roles:
 
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-enterprise-app-role-management
 
If you are unsure on what roles need to be set up on your side, either 1.) ask your internal colleagues who are administering the PowerClerk program, or 2.) log in to PowerClerk and navigate to Program Design > Roles. If you don’t have a PowerClerk account, please request one from an internal colleague that has a PowerClerk user account with administrative privileges.
 
Please note: Azure AD will give an error when the role called “Program Designer” has a space in between “Program” and “Designer”. The workaround is to rename the role (in both PowerClerk and Azure AD) to a naming convention similar to the following examples: “ProgramDesigner”, “Program-Designer”, or “Program_Designer”.
 
From Step 3, CPR needs to be given the SAML Signing Certificate (click the blue “Download” hyperlink for “Certificate (Base64)”). Please note: never send us your private Certificate key, only the public key. Please ensure that the SAML Signing Certificate provided is trusted by a public Certification Authority (CA).
 
From Step 4, CPR needs to be given the “Login URL” and “Azure AD Identifier“.
 
 

Okta IDP Configuration

Create a new application in Okta and choose SAML as the sign on method.

 

Choose SAML as sign on method

Figure 1: Choose SAML as sign on method

 
In Figure 2, below, the Single sign-on URL and Default RelayState, need to be configured as follows:

  • Sandbox: https://<program_name>.cleanpowerdemo.com/PCITrial/MvcAccount/Login/Acs
  • Production: https://<program_name>.powerclerk.com/MvcAccount/Login/Acs

[where program_name is the host name of the PowerClerk program, found in the browser URL].
 
and the “Audience URI (Entity ID)” is:

  • Sandbox: https://cleanpowerdemo.com/PCITrial/
  • Production: https://powerclerk.com/

…and for the “Name ID format” select “EmailAddress”.

 

Setting Default RelayState

Figure 2: Configuration Settings

 

Add 4 entries to the Attribute Statements section for the first name, last name, email, and user id, as shown below:

 

Adding Attribute Statements

Figure 3: Adding Attribute Statements

 

Add 1 entry to the Group Attribute Statements section with the name “PowerClerkRoles”. This will be a regular expression which selects Okta Group Names to pass to PowerClerk to use as the Role. For example, if the PowerClerk Roles are Administrator, Applicant, and Program Designer, the regular expression would be “(Applicant|Administrator|Program Designer)”. Each user must belong to exactly 1 Okta group which has a name that matches the name of a Role in PowerClerk.

 

Group Attribute Statements

Figure 4: Group Attribute Statements

 

SP Configuration

After creating the Okta application, click the “Identity Provider metadata” link in the Settings section. This will generate an XML file that should be sent to CPR. The XML contains the data required to configure PowerClerk to communicate with the IdP application.

 

SP Configuration

Figure 5: SP Configuration

 

By default, if a user is not logged in, the front page in PowerClerk will show a link to Okta’s login page. After logging in through Okta, the user is redirected back to PowerClerk. Alternatively, a program can provide a custom URL that the user will be used instead of PowerClerk’s front page.

 

IDP Configuration Troubleshooting

If you are having trouble getting your IDP configuration to work, plan on reaching out to your PowerClerk support representative (or support@powerclerk.com) to work through the following steps:

  • Step 1: Send us a screenshot of your IDP configuration, so we can cross-check what you have configured in terms of the Entity ID, Reply URL, etc.
  • Step 2: Send us a screenshot of the SAML error message you are receiving and attach the SAML Response and SAML Request .xml files.
  • Step 3: If possible, create an account in your IDP and send us the credentials so that we can login to further troubleshoot your configuration.
  • Step 4: CPR will set up a screenshare session with you to go over the configuration.

FAQs

Q: I am getting error “Attempted to call SAML ACS without valid ‘UserId’”. What does this mean?
A: The error means that the UserID attribute (discussed in the Azure AD configuration, Step 2) has not been configured. In this case, the .xml file shows: The attribute needs to be configured to read “UserId”.
Q: Should my installers use SSO?
A: Since installers could potentially be submitting applications in your program as well as another customer’s program, CPR’s recommended best practice is that installers use “local login” to log in via the PowerClerk login page (so that they can access multiple programs within their portal). In other words, if the installer was part of two (2) programs, and logged into your PowerClerk via your SSO IDP, they would only be able to see your program (not both programs). Your CPR representative can turn “local login” on, which would allow users in your program to log in via SSO or the PowerClerk login page (with traditional username and password credentials).
Q: Is there more than one way to log in via SSO?
A: Yes, there are two (2) ways to log in to PowerClerk with SSO:
  • SP initiated: click the “Sign in with” SSO link on the PowerClerk login page
  • IDP initiated: log into your IDP, click the link, and you're in PowerClerk
Q: Can PowerClerk accommodate multiple IDP configurations, to separate groups (e.g. Internal Administrators, External Installers, etc.)?
A: Yes, but before considering this approach, see if these groups can be delineated by using PowerClerk Roles instead.
Q: Once our SSO IDP integration redirects our customers to PowerClerk, does the user need to remain authenticated at our website or does PowerClerk take up the user engagement/ session within PowerClerk at that point?
A: Once the SSO login is complete, PowerClerk manages the session and the user no longer needs to be logged in to your utility website.
Q:Will the user need to log out of the session? Or is the expectation that the user’s session be terminated at our website?
A: The PowerClerk session will last until the user logs out, closes the window, or the session times out.  The users actions at your website will not affect the PowerClerk session.
Q: Will the session timeout due to inactivity? How long?
A: It's a sliding expiration window of one hour which is refreshed after half an hour. So worst case is 31 minutes.
Q: Do you have a preference if the users are connected to PowerClerk in a new tab or a new window?
A: No preference; but if you launch a new tab for PowerClerk, we can close that tab when the user logs off. This is a better user experience.
Q: While configuring SSO for PowerClerk on our side, my IDP is asking me for a metadata file. Can CPR provide a metadata file?
A: No, CPR does not have a PowerClerk metadata file to provide. Rather, you just need to configure the IDP with the sign-on URL and the Entity ID.

Have additional questions? Contact us to nominate your FAQ and help others find answers to your own questions concerning this feature.

Create A Support Ticket

Not finding your answer here?  Submit a question to our support team at the PowerClerk Ticket System and leverage the PowerClerk team’s expertise.