SSO Features for EnergyCAP

Once an organization has been connected for federated login through MyEnergyCAP, the user login workflow utilizes the following set of rules in order to correctly identify an existing EnergyCAP account if it exists. At the current time, EnergyCAP only utilizes the user-specific information during the workflow. There is no current accommodations for passing in active/inactive status, permission role names, or EnergyCAP Topmost Place/Cost Center values. While these features might be available in the future, they are not currently a part of the MyEnergyCAP integration.

Required Claims

In order for users to authenticate with EnergyCAP, these claims must be configured correctly. The claim name must be the entire URI.

Matching Users

All federated users which have successfully authenticated have a matching MyEnergyCAP user created with a unique GUID. This is stored into the EnergyCAP database after the first successful login attempt. This GUID takes precedence over all other matches listed below. If a user is authenticated and EnergyCAP finds a matching GUID for a SystemUser record, it assumes that user record is the correct match. No two users can have the same GUID in a database.

Existing EnergyCAP users are matched as follows:

  1. Look at the GUID of the incoming, authenticated user. If that GUID is found for a user in the SystemUser table, continue authentication as that user.
  2. If a valid, matching GUID is not found, EnergyCAP will then attempt to match the “subject” claim with the EnergyCAP SystemUserCode field in the database. If there is a match, EnergyCAP will populate the GUID field for use with all subsequent logins. (This is value cannot be set through the EnergyCAP UI)
  3. If a GUID is not found AND a matching SystemUserCode is not found, EnergyCAP will then look for a matching email address. If one is found, EnergyCAP will populate the GUID for future logins and move forward.
  4. If none of the above match, we either fail the login OR create an EnergyCAP user with the authenticated information.

Creating New Users

If an authenticated user is not found in the database as described above, clients have two choices:

  1. Create a new user with the DEFAULT (read-only) user role and ROOT-level Topmost Place and Cost Center.
  2. Prevent user login and return a “failed login” message indicating that an existing EnergyCAP user could not be identified.