Okta

This guide walks through configuring Okta as a SAML 2.0 identity provider for EnergyCAP SSO.

Prerequisites

Before you begin, ensure you have:

  • Administrator access to your Okta organization
  • The EnergyCAP SAML settings from the SSO Overview:
    • SP SSO URL: https://sso.energycap.com/saml2/idpresponse
    • SP Entity ID: urn:amazon:cognito:sp:us-east-1_laRy9DXoY
  • Contact your EnergyCAP project manager to confirm your organization’s SSO setup is ready

Step 1: Create a SAML Application

  1. Sign in to the Okta Admin Console
  2. Navigate to Applications > Applications
  3. Click Create App Integration
  4. Select SAML 2.0 as the sign-in method
  5. Click Next

Step 2: General Settings

  1. Set the App name to EnergyCAP
  2. Optionally upload the EnergyCAP logo for easy identification in the Okta dashboard
  3. Click Next

Step 3: Configure SAML Settings

Single Sign-On URL and Audience

In the SAML Settings section, configure the following:

Field Value
Single sign-on URL https://sso.energycap.com/saml2/idpresponse
Use this for Recipient URL and Destination URL Checked
Audience URI (SP Entity ID) urn:amazon:cognito:sp:us-east-1_laRy9DXoY
Name ID format Unspecified or EmailAddress
Application username Email or Okta username

Attribute Statements

Scroll to the Attribute Statements section and add the following four attributes. Each Name must be the full URI:

Name Name format Value
https://my.energycap.com/subject URI Reference user.login
https://my.energycap.com/email URI Reference user.email
https://my.energycap.com/firstName URI Reference user.firstName
https://my.energycap.com/lastName URI Reference user.lastName
Tip
The subject attribute determines how users are matched to EnergyCAP accounts. If your organization uses a different attribute as the primary identifier (e.g. user.samAccountName via an AD integration), use that instead of user.login. Confirm with your EnergyCAP project manager which attribute matches your EnergyCAP user codes.
  1. Click Next

Step 4: Feedback

  1. Select I’m an Okta customer adding an internal app
  2. Click Finish

Step 5: Download the IdP Metadata

  1. On the application’s Sign On tab, scroll to the SAML Signing Certificates section
  2. Find the active certificate and click Actions > View IdP metadata
  3. This opens the metadata XML in a new tab — save this file or copy the URL
  4. Send the metadata XML (or URL) to your EnergyCAP project manager — they need it to complete the SSO configuration on the EnergyCAP side

Alternatively, you can find the metadata URL in the Sign On tab under Metadata URL.

Step 6: Assign Users

Users must be assigned to the EnergyCAP application before they can authenticate via SSO.

  1. Navigate to the Assignments tab of the EnergyCAP application
  2. Click Assign and choose Assign to People or Assign to Groups
  3. Select the users or groups that should have access to EnergyCAP
  4. Click Assign for each selection, then click Done
Tip
For a quick rollout, assign a group (such as “EnergyCAP Users”) rather than adding users individually. New users added to the group will automatically gain access.

Step 7: Test the Integration

  1. Open a browser in incognito/private mode
  2. Navigate to your Okta dashboard and click the EnergyCAP app tile
  3. Sign in with a user that:
    • Is assigned to the EnergyCAP application in Okta
    • Has a matching user account in EnergyCAP (by user code or email)
  4. If authentication succeeds, you should be redirected to EnergyCAP and signed in automatically

If the test fails, check:

  • All four attribute statements are configured with the full URI names (https://my.energycap.com/...)
  • The Name format for each attribute is set to URI Reference
  • The user has a valid email attribute in Okta
  • The IdP metadata has been sent to and processed by your EnergyCAP project manager
  • The user exists in EnergyCAP with a matching user code or email address

Viewing SAML assertions for debugging

If you need to inspect the raw SAML response:

  1. Install a browser extension like SAML-tracer (Firefox) or SAML Chrome Panel (Chrome)
  2. Initiate a sign-in to EnergyCAP through Okta
  3. Inspect the SAML response to verify the claim URIs and values are correct

Summary

Step Action
1 Create a SAML 2.0 app integration in Okta
2 Set the app name to “EnergyCAP”
3 Configure SSO URL, Audience URI, and four attribute statements
4 Complete the feedback step
5 Download IdP metadata and send to EnergyCAP PM
6 Assign users or groups to the application
7 Test with an assigned user