Single Sign-On (SSO)

EnergyCAP supports Single Sign-On so your users can authenticate with your organization’s identity provider (IdP) instead of managing separate EnergyCAP credentials. Once configured, users sign in through your IdP and are automatically authenticated in EnergyCAP.

Supported Protocols

Protocol Standard Use case
SAML 2.0 Security Assertion Markup Language Enterprise IdPs like Entra ID, Okta, ADFS, PingFederate
OAuth 2.0 / OIDC OpenID Connect Modern identity platforms and custom integrations

Getting Started

SSO configuration requires coordination between your organization and EnergyCAP. To enable SSO:

  1. Contact your EnergyCAP project manager or account representative to initiate the setup process
  2. Configure your identity provider using the EnergyCAP SAML settings below
  3. Send your IdP metadata to your EnergyCAP project manager
  4. Test the integration with a small group of users before rolling out organization-wide

For step-by-step IdP configuration guides, see:

EnergyCAP SAML Configuration

When configuring your identity provider, use the following EnergyCAP service provider (SP) settings:

Setting Value
SP SSO URL (Assertion Consumer Service URL) https://sso.energycap.com/saml2/idpresponse
SP Entity ID (Audience URI) urn:amazon:cognito:sp:us-east-1_laRy9DXoY

Required Claims / Assertions

Your identity provider must send the following claims with each SAML assertion. The claim name must be the full URI — short names are not accepted.

Claim URI Description Example IdP attribute
https://my.energycap.com/subject Unique user identifier user.userprincipalname, user.samaccountname
https://my.energycap.com/email User’s email address user.mail
https://my.energycap.com/firstName User’s first name user.givenname
https://my.energycap.com/lastName User’s last name user.surname
Tip
The subject claim is the primary identifier used to match users in EnergyCAP. Use whichever directory attribute your organization normally uses as the user principal — typically userprincipalname or samaccountname.

How User Matching Works

When a user authenticates via SSO, EnergyCAP matches them to an existing EnergyCAP user account using the following logic, in order:

  1. GUID match — After a user’s first successful SSO login, EnergyCAP stores a unique GUID for that user. On subsequent logins, this GUID is checked first and takes precedence over all other matching.

  2. Subject match — If no GUID is found, EnergyCAP compares the subject claim to the SystemUserCode field in the database. If a match is found, the GUID is stored for future logins.

  3. Email match — If neither GUID nor subject matches, EnergyCAP looks for a user with a matching email address. If found, the GUID is stored for future logins.

  4. No match — If none of the above match, the behavior depends on your organization’s configuration (see below).

New User Provisioning

If an authenticated user cannot be matched to an existing EnergyCAP account, your organization can choose one of two behaviors:

Option Behavior
Auto-create A new EnergyCAP user is created with the default role (read-only permissions) and root-level Topmost Place and Cost Center. An administrator should update the user’s role promptly.
Deny access The login fails with a message indicating that no matching EnergyCAP user was found. The user must be manually created in EnergyCAP before they can sign in.

Discuss which option is right for your organization with your EnergyCAP project manager during setup.

Tip
EnergyCAP SSO currently handles authentication only. User attributes like permission roles, active/inactive status, and Topmost Place/Cost Center values are not synchronized from your identity provider — they must be managed within EnergyCAP.

Bypassing EnergyCAP Home

By default, SSO users are directed to EnergyCAP Home to select their identity provider before being redirected. If you want your users to skip this step and go directly to your organization’s IdP login, use the following direct SSO URL:

https://sso.energycap.com/oauth2/authorize?identity_provider={org_id_provider}&nonce=1&redirect_uri=https://login.energycap.com/fedsignin&response_type=CODE&client_id=2ackb9bv7dn7qd8dgmoljcb3cp&state=STATE&scope=openid%20profile

Replace {org_id_provider} with your organization’s identity provider identifier, which will be provided by your EnergyCAP project manager after SSO setup is complete.

This URL can be:

  • Bookmarked for users
  • Added to your organization’s intranet or portal
  • Used in identity provider app tiles (e.g. Okta dashboard, Entra My Apps)

Troubleshooting

Issue Cause Resolution
User gets “login failed” after authenticating with IdP No matching EnergyCAP user found and auto-create is disabled Create the user in EnergyCAP first, ensuring the email or user code matches the SSO subject or email claim
User is matched to the wrong EnergyCAP account Email or subject claim matches an unintended user Verify the subject claim maps to the correct directory attribute and that EnergyCAP user codes are accurate
Claims are missing or empty IdP is not sending the required claim URIs Verify all four claim URIs are configured exactly as shown above (full URI, not short name)
New user has limited permissions after first login Auto-created users receive the default read-only role Update the user’s role in EnergyCAP after their first login