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 typically stores and manages credentials (email, password, and optional MFA) to enable users to log in and access programs. For additional security and easier user management, utilities may prefer to control PowerClerk access centrally through their own Identity Provider (IdP), which authenticates and authorizes users and can provide their role to PowerClerk.

• SSO enables IT security teams at the utility to manage access for their employees in a single place for access to PowerClerk and other enterprise applications.
• Users benefit from having the same credentials and authenticated session for all applications, meaning they do not need to sign in separately to each application.

Most SSO configurations are for utility program administrators. A supported but less common use case is to use SSO to manage access for approved trade partners or even customer applicants.
 

Figure 1: Front Page Link for SSO Login

Supported Features

• PowerClerk supports both of the industry standards for SSO: SAML 2.0, and OIDC (OpenID Connect).
• PowerClerk has been integrated with many IdPs, including Microsoft Entra ID (Azure or on-prem AD), Okta, Auth0, and others.
• Multiple SSO configurations can be supported for the same program to support different user domains.
• PowerClerk supports SSO when switching between programs, with either a shared or separate configuration. With a valid authentication session, the user can switch programs without providing credentials again. Users might switch to programs that do not support SSO or for an IdP where they are not already logged in, in which case they will be prompted to sign in with those credentials.
• PowerClerk can display a link on the sign-in page to start SSO (SP-initiated flow). PowerClerk can also support sign-in started from a utility portal (IdP-initiated flow).
• User roles can be provided by the IdP (recommended), or a default role can be set at initial sign in then managed in PowerClerk.
• PowerClerk uses the IdP only during sign in or switching programs. After that, there is no interaction between the PowerClerk and the IdP session.

General Configuration

We recommend testing SSO in a PCITrial sandbox. In production, SSO is an additional PowerClerk feature, not included with a standard license. Contact your CPR Account Executive to discuss adding a new IdP for SSO.
 
To initiate a request for SSO configuration, open a Support Ticket with the Customer Success team. You will need to decide each item on the checklist below to determine the user experience, then share the configuration details listed in either the SAML or OIDC sections for us to complete the setup.

1. Which PowerClerk program(s) need SSO?
• Provide the URL(s) of the program Home page in the ticket.
2. Will sign in with PowerClerk credentials still be allowed?
• Typically, yes. Applicants are usually not managed by the utility IdP and have their own PowerClerk login.
• If no, should PowerClerk send all users to the same IdP, removing the project Front Page entirely.
3. Should a “Sign in with” link appear on the PowerClerk sign-in page?
• Usually, yes, but if SSO users are internal employees and they access PowerClerk via an application portal, the link may confuse applicants, so can be removed.
• If available, the text of the sign in link can be customized. For example, from “Sign in with Entra”, using the IdP name, to “Utility employee sign in”.
4. Should a default role be given to a user at the first sign in if one is not provided by the IdP, or should access be blocked?
• Once SSO is active on your program, the Program Design Roles menu will have a new tab to configure Default Roles.

Figure 2: Default Roles for SSO
5. Are users managed with SSO allowed to use the PowerClerk API?
• If SSO users have an API Key, their client credentials authenticate directly with PowerClerk. Your security team may want to block this because API requests bypass the IdP.
6. Should the SSO configuration be copied to PowerClerk Test Environments?
• Usually, yes, for internal employee SSO.
7. Will your IdP use SAML or OIDC?
• SAML and OIDC each have their own configuration. Check the relevant section below for the requirements and configuration sharing.

SAML Configuration

The following details will be required by your IT team for your IdP configuration:
 

1. The PowerClerk SP Entity Id. This can be a shared name for your PowerClerk programs, or unique for each program:
   Shared for all programs, less IdP configuration but harder to set up distinct users and roles:
   • Sandbox: https://cleanpowerdemo.com/PCITrial/
   • Production: https://powerclerk.com/
   Unique, recommended if programs have users with different roles per program. Use the hostname found in your program URL to replace the placeholder:
   • Sandbox: https://{hostname}.cleanpowerdemo.com/PCITrial/
   • Production: https://{hostname}.powerclerk.com/
2. The ACS URL, the PowerClerk endpoint where the IdP posts the SAML response.
   • Sandbox: https://{hostname}.cleanpowerdemo.com/PCITrial/MvcAccount/Login/Acs
   • Production: https://{hostname}.powerclerk.com/MvcAccount/Login/Acs
3. Assertion claims – SAML provides a token with user attributes. PowerClerk needs specific claims, except as indicated:
   • UserId – unique identifier between PowerClerk and the IdP. Email, names, and roles may change, but the UserId must not change.
   • FirstName – may be used by the PowerClerk program to address the user.
   • LastName – may be used by the PowerClerk program to address the user.
   • Email – may be used by PowerClerk as the user’s email address.
   • PowerClerkRoles (optional) – if provided, values must map to a program role.

You will need to provide the following to the PowerClerk Customer Success team via your assigned Customer Delivery Manager or the
PowerClerk ticket system:

• The IdP Entity Id, a unique identifier of the IdP.
• Which PowerClerk SP Entity Id was configured in the IdP (shared or unique).
• The Sign On URL where PowerClerk will send a user to authenticate.
• The Certificate in PEM format, provided securely as an attachment in the ticket. Certificates can be rotated, typically annually, by submitting a support ticket.

PowerClerk does not support relay states, logout URLs, claims namespaces, custom claims, assertion encryption, or exchanging configuration metadata files.
 

OIDC Configuration

The following details will be required by your IT team for your IdP configuration:
 

1. The Redirect URL, the PowerClerk endpoint where the IdP will reply with an authentication token.
   • Sandbox: https://{hostname}.cleanpowerdemo.com/PCITrial/MvcAccount/Login/OAuth2Redirect
   • Production: https://{hostname}.powerclerk.com/MvcAccount/Login/OAuth2Redirect
2. OIDC claims may be provided in an access token after successful authentication, or via a UserInfo endpoint accessed using an access token.

 

3. PowerClerk needs specific claims, except as indicated.
• sub – unique identifier between PowerClerk and the IdP. Email, names, and roles may change but the sub must not change.
• given_name – may be used by the PowerClerk program to address the user.
• family_name – may be used by the PowerClerk program to address the user.
• email – may be used by PowerClerk as the user’s email address.
• PowerClerkRoles (optional) – if provided, values must map to a program role.

You will need to provide the following to the PowerClerk Customer Success team via your assigned Customer Delivery Manager or the
PowerClerk ticket system: 
 

• Issuer URL which typically hosts the OIDC well-known configuration.
• Client Id identifying the PowerClerk application (or specific program) at the IdP.
• Client Secret which should be securely provided via the ticket system.
• Scopes, if required, PowerClerk can include a list of scopes.

PowerClerk does not support decoding claims directly from an Id token.
 

Troubleshooting

If you run into issues during setup and testing, generally there is a mismatch between configurations. Use a browser in incognito mode, and open the developer tools to the network tab to capture the initial redirect to the IdP and callback to PowerClerk.
 
The following steps follow the SSO flow and describe where incorrect configuration will cause issues.
 
Step 1: The SSO flow begins by sending a user to the IdP sign-in page with some parameters. The user may click on a link on the PowerClerk page or be redirected automatically. In both cases, the IdP expects parameters matching its configuration. If the IdP immediately displays an error, the configuration is missing or mismatched.

For SAML, check the following:
• For an SP-initiated request, PowerClerk must have the correct Sign On URL to a reachable IdP endpoint.
• The initial IdP request contains a SAMLRequest parameter. This is a Base64-encoded parameter that can be decoded for inspection.
• Verify the decoded AuthnRequest values: the ACS URL and SAML Issuer (PowerClerk SP Entity Id) match the IdP configuration.

For OIDC, check the following:
• For an SP-initiated request, PowerClerk must have the correct Issuer URL to a reachable IdP endpoint.
• The initial request contains the Client Id, Redirect URL, and optional scopes. These will be validated by the IdP.

Step 2: User authentication is completed on the IdP. If the account is not recognized or credentials are not valid, the issue may be the IdP’s user database.
 
Step 3: The IdP authorizes the user to access the PowerClerk application. If the user is not allowed access, the IdP typically reports an authorization or access error.
 
Step 4: After authentication and authorization, the IdP redirects the user back to PowerClerk with some information. If PowerClerk displays an error, the configuration is missing or mismatched.

For SAML, check the following:
• The IdP redirects the browser to the PowerClerk ACS URL with a SAMLResponse parameter containing a SAML assertion.
• PowerClerk validates the SAML assertion with the Certificate. An invalid or certificate mismatch will result in a failure.
• PowerClerk might report missing required claims, most frequently the UserId.
• The SAMLResponse contains a Base64-encoded assertion that can be decoded for inspection. Verify the SAML Issuer matches the IdP Entity Id configured in PowerClerk.
• The claims must include the SAML claims. Check the list of required SAML assertion claims are all included and valid.
For OIDC, check the following:
• The IdP redirects the browser to PowerClerk with an authentication code. PowerClerk will exchange this for an access token.
• For a successful exchange, the Client Secret must match between PowerClerk and the IdP.
• If available, PowerClerk calls the UserInfo endpoint to fetch the identity claims. Check PowerClerk has the correct UserInfo URL configured and the UserInfo list of required OIDC identity claims are all included and valid
• If the UserInfo endpoint is not available and the access token is a JWT, PowerClerk will try to extract the OIDC identity claims from the access token.

Step 5: The user needs a valid role to access PowerClerk.

• If the IdP provides a PowerClerkRoles claim, it must match one of the roles in the program. Mismatched role names or a missing role on PowerClerk will be rejected and block the user.
• If the IdP does not provide a PowerClerkRoles claim and there is no default role for the IdP in the program, the user will be blocked.

Figure 3: Single Sign On Role Assignment in PowerClerk

 
Support tickets requesting help with SSO trobleshooting should include the program URL and the IdP or IdP configuration (if more than one). Include descriptions and screenshots of the error. If possible, use the browser developer tools network log, as described in the steps above, to capture and include the request to the IdP and the redirect to PowerClerk. Do not include requests containing your credentials.

FAQs

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.