Single Sign On (SSO)

SSO provides added security and improves the login experience for utility program administrators. When admins are logged on to their internal networks, they can access PowerClerk without having to log in again.

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:

• Azure Active Directory (AD) (https://azure.microsoft.com/en-us/services/active-directory/)
• Okta (https://www.okta.com/)
• onelogin (http://www.onelogin.com/)
• JumpCloud (https://jumpcloud.com/)

 
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 (SAML)

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://<program_name>.cleanpowerdemo.com/PCITrial/
• Production: https://<program_name>.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 (optional)

Please note: Within Azure >> Entra administrative interfaces, please ensure any optional Attributes and Claims >> Namespace fields are left unset and empty.
 
The optional PowerClerkRoles attribute will contain the name of the role in PowerClerk that the user should be assigned to (look to Figure 7 of the Okta configuration, below, for an example). This attribute may be omitted by setting up a default role that will automatically be assigned to new users, reach out to your PowerClerk representative to configure. 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“.

 

Azure AD Configuration (OIDC)

To configure Azure AD as an OIDC provider to use with PowerClerk, follow the steps in the following Microsoft tutorial: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
When setting up redirect uris, use values as follows:

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

Figure 1: Redirect URIs

In Token Configuration, add the following claims to the access token:

• email
• family_name
• given_name

 
Click Manifest:
 

Figure 2: Manage Manifest

Set accessTokenAcceptedVersion to 2. Click Save. Click Expose an API:
 

Figure 3: Expose an API

 
Add a scope, give it a name to inform users the permissions they are giving to PowerClerk (email, first, and last name). Share the scope name with your PowerClerk representative, something like “api://00000000-0000-0000-0000-000000000000/PowerClerk”
Under Certificate & Secrets, create a Client Secret, share the value with your PowerClerk representative, along with the Client Id.
 

Okta IDP Configuration (SAML)

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

Figure 4: Choose SAML as sign on method

 
In Figure 5, 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://<program_name>.cleanpowerdemo.com/PCITrial/
• Production: https://<program_name>.powerclerk.com/

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

Figure 5: Configuration Settings

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

Figure 6: Adding Attribute Statements

If you are using IDP-configured roles, 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.

Figure 7: 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.

Figure 8: 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.

Configuring SSO for use with multiple PowerClerk Programs

PowerClerk supports multiple IDPs from the same directory, so that you can use SSO with more than one PowerClerk program. Specifically, PowerClerk does not require the login page of a specific program to unconditionally redirect to the page starting the IdP-initiated login. If you use the same EntityID for both programs, you must also use the same Certificate for both programs.
 
Individual/unique Certificates and EntityIDs can also work. Your IDP should be running in IDP-initiated mode. Note that if you want to be able to login by clicking anything in PowerClerk (which in SAML terminology is the Service Provider == SP), SP-initiated MUST also be enabled.
 

Using Azure AD as an example:

In addition to CPR requiring the Login URL (i.e. SignOnURL), Azure AD Identifier (i.e. EntityID), and Certificate for each PowerClerk Program, we will also need the User Access URL from you, which is what we use as the redirect URL for PowerClerk. Allowing CPR to configure your redirect URL on our end will prevent the user from being booted back to the login page (when switching between programs) where they would be forced to click the “SSO” hyperlink to log into the 2nd program (see image below):

Figure 9: Sign in with SSO

Configuring the redirect URL removes this intermediate step and allows the switching between programs to be seamless from a UI perspective, to mimic how it works without using SSO, when using the “Change Program” drop-down menu inside PowerClerk:

Figure 10: Change Program

Please note that the “User Access URL” is found outside of the SSO configuration and in the IDP app properties itself. To find the “User Access URL”, follow these steps for Azure (other IDPs will differ):
 

1. Navigate to Azure Enterprise apps and click the app that has the User Access URL (e.g. this should be the name of your PowerClerk program):
    
   

   Figure 11: Azure Enterprise apps

    

2. Then click “Properties” on the left-hand panel:
    
   

   Figure 12: Azure Enterprise apps – Properties

    

3. On the right side, the User Access URL will be shown for apps with SSO configurations:
    

 


Figure 13: User Access URL

 

IDP Configuration Troubleshooting

To troubleshoot your IDP configuration, there are extensions available, such as the Chrome “SAML Tracer” extension, which is a tool for viewing SAML and WS-Federation messages sent through the browser during single sign-on and single logout. Such SAML tracer will let you watch what claims are sent when you go to login to PowerClerk, which would look similar to the below:

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.

Q: I received the following error: “No providers recognized that match the issuing IDP”

A: This happens when the IdP sends you to one PowerClerk program with the assertion meant for another program. In other words, whatever entity is in the incoming assertion is not configured as a SSO provider for the program.

Q: Should the “UserID” attribute be set to be the user’s email address

A: No, because the typical IdP will change that if the email address of the user changes. Instead, if the email address is “samplename123@gmail.com”, set the “UserID” attribute to “samplename123”. Alternatively, you can just use GUIDs (e.g. “6d977409-b213-4c96-a738-1bbb10e9e742”) or a string similar to PowerClerk’s public IDs (e.g. “83L0p3z17901”) – anything that sticks with the account even in the case of email/name changes.

Q: I am receiving the following error: "SP-Initiated SSO is not enabled”

A: This error is an example of a message contained in the SAML assertion that YOUR side is sending to us. It is not us claiming that SP-initiated SSO is off; rather, it is the assertion you are sending.

Q: What is the Issuer ID?

A: The Issuer ID = EntityID; this needs to match between what is configured inside the IDP on the utility side and what is configured on the PowerClerk side.

Q: What is an example of a correct role attribute to be sending from your IDP SAML?

A: Please note: Taking the above syntax as a direct example would mean there would need to be a role called “SampleRoleName” inside the PowerClerk Program, under the “Roles” page.

Q: On the User Administration page, I show up as an SSO user. But when I am in the Test Environment, I show up as NOT a SSO user – why?

A: You don’t show up as an SSO user in the Test Environment unless you logged into the Test Environment with a separately configured IDP.

Q: I am receiving an error saying "SAML recipient doesn’t match the local service provider name or assertion consumer service URL"

A: Your SAML assertion doesn’t include a “Destination”. This is what your assertion may look like: - screenshot placeholder- And here is what our other customer’s assertion looks like, that are using SSO successfully with PowerClerk. We would recommend matching this: - screenshot placeholder- For example, Okta has this checkbox: - screenshot placeholder- In terms of the “PowerClerkRoles” attribute, let’s add some additional clarity. In between “Please note….” and “From Step 3…..”, include the following: -screenshot placeholder - If you are receiving this error message: -screenshot placeholder - Your IDP (e.g. Azure) will need to set the attribute, as outlined in Step 2. PowerClerk roles need to be mapped to Azure groups so that you can manage access to PowerClerk based on membership. See this Microsoft article for details on setting up application-defined roles. Here is an example showing defined PowerClerk custom roles inside your Azure IDP: - screenshot placeholder - Here are some example users added to the roles inside Azure: - screenshot placeholder - The IDP needs to pass these roles back to PowerClerk when signing in so the IDP knows what access each user should have. Here is a SAML trace example, so you can see how the “PowerClerkRoles” attribute is delineated: - screenshot placeholder - We are looking for Azure to show the authentication was successful. The SAML will need to have attributes that look like the following: - screenshot placeholder -

Q: Once I have all the Roles, and before I go to PATCH and “Run Query” in Graph – am I copying everything (all the code) in the bottom half, pasting in the top half (Request Body) and replacing the “AppRoles” section? Or am I just copying the AppRoles section (that I just created with all the roles) and pasting the new one into the top half (Request Body) of the page and then running the PATCH/Run Query?

A: You are only pasting the appRoles section into the request body. That's the only section you're patching.

Q: Also, the “id” is different for each, I am assuming that I will user the Object ID for that field in each?

A: No, the objectID you have highlighted is for the group. That's not needed for anything here. You are not using the Azure generated Object ID for those groups in PowerClerk. Simply use https://www.guidgenerator.com/ to create a unique value for each and add that to the AppRoles code.

Q: I am getting the following error: "Malformed JSON body - Review the request body and fix any malformatted JSON..."

A: Check for a dangling comma and make sure to enclose the whole thing in brackets. Here is an example from Google: -screenshot placeholder-

Q: I ran the patch to add the appRoles section to what is displayed in the request body, and now the appRoles are reflected in the image below, on the right side column, however, I am now getting this error from Run Query: "Bad Request - 400"

A: Change the “isEnabled” value to “false” then go back in and set the correct AppRoles. Change your query to the original GET and look at the appRoles section to make sure. After all that, you can go and add groups to your app in the gui and choose a role. You must be sure you've got your syntax right or you'll get an error. Also, the syntax needs to be enclosed in brackets (but cross-check this with sources available on the internet to be sure). Then add the roles in your IDP and then assign the role, for example: - screenshot placeholder -

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.