SAML Single Sign-On (SSO)
Configure SAML-based single sign-on for your team to centralise authentication through your identity provider.
Overview
Shocking Energy supports SAML 2.0 Single Sign-On (SSO) for teams on the Enterprise plan. SSO lets your team members authenticate through your organisation's identity provider (IdP) instead of managing separate credentials.
Benefits of SSO for enterprise teams:
- Centralised access control -- manage who can access Shocking Energy from your IdP
- Reduced credential fatigue -- team members sign in with existing corporate credentials
- Improved security posture -- enforce your organisation's authentication policies (MFA, conditional access, device trust)
- Automated provisioning -- new team members are created automatically on first sign-in (JIT provisioning)
- Simplified offboarding -- disable a user in your IdP and they immediately lose access
Supported identity providers
Shocking Energy works with any SAML 2.0 compliant identity provider. The following providers have been tested and have dedicated setup guides:
| Provider | Status |
|---|---|
| Microsoft Entra ID (Azure AD) | Fully supported |
| Okta | Fully supported |
| Google Workspace | Fully supported |
| OneLogin | Fully supported |
| Ping Identity | Fully supported |
| JumpCloud | Fully supported |
| ADFS | Fully supported |
| Generic SAML 2.0 | Supported via manual configuration |
Prerequisites
Before configuring SSO, ensure you have:
- An Enterprise plan subscription for your team
- Owner or Administrator role on the Shocking Energy team
- Administrative access to your identity provider
- A verified email domain that your team members use (e.g.
yourcompany.com)
SSO configuration requires an Enterprise plan. Contact sales at sales@shocking.energy to upgrade your team.
Identity provider setup
Microsoft Entra ID (Azure AD)
Create an Enterprise Application
- Sign in to the Azure Portal and navigate to Microsoft Entra ID > Enterprise applications
- Click New application > Create your own application
- Enter Shocking Energy as the application name
- Select Integrate any other application you don't find in the gallery (Non-gallery)
- Click Create
Configure SAML settings
- In the new application, go to Single sign-on > SAML
- Under Basic SAML Configuration, click Edit and set:
- Identifier (Entity ID): Copy this from the Shocking Energy SSO settings page
- Reply URL (Assertion Consumer Service URL): Copy this from the Shocking Energy SSO settings page
- Click Save
Configure attributes and claims
- Under Attributes & Claims, click Edit
- Ensure the following claims are mapped:
| Claim | Value |
|---|---|
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | user.mail |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | user.givenname |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | user.surname |
- Optionally, add a group claim if you intend to use role mapping (see Role mapping below)
Download the metadata
- Under SAML Certificates, download the Federation Metadata XML file
- Alternatively, copy the following values individually:
- Login URL (from the SAML setup section)
- Azure AD Identifier (Entity ID)
- Certificate (Base64) (download from SAML Certificates)
Assign users
- Go to Users and groups > Add user/group
- Assign the users or groups that should have access to Shocking Energy
- Only assigned users will be able to sign in via SSO
Users must be assigned to the Enterprise Application in Entra ID before they can sign in. Unassigned users will receive an error from Microsoft during authentication.
Okta
- In the Okta Admin Console, go to Applications > Create App Integration
- Select SAML 2.0 and click Next
- Set the app name to Shocking Energy
- Configure the SAML settings:
- Single sign-on URL: Copy the ACS URL from the Shocking Energy SSO settings page
- Audience URI (SP Entity ID): Copy the Entity ID from the Shocking Energy SSO settings page
- Name ID format: EmailAddress
- Add attribute statements for
email,firstName, andlastName - Complete the wizard and assign users or groups to the application
- From the Sign On tab, copy the Metadata URL or download the metadata XML
Google Workspace
- In the Google Admin Console, go to Apps > Web and mobile apps > Add app > Add custom SAML app
- Name the app Shocking Energy and click Continue
- On the Google Identity Provider details page, download the IdP metadata file or copy the SSO URL and certificate
- Set the service provider details:
- ACS URL: Copy from the Shocking Energy SSO settings page
- Entity ID: Copy from the Shocking Energy SSO settings page
- Name ID format: EMAIL
- Name ID: Basic Information > Primary email
- Add attribute mappings for
firstNameandlastName - Click Finish and turn the app ON for the relevant organisational units
Generic SAML 2.0
For any SAML 2.0 compliant identity provider:
- Create a new SAML application in your IdP
- Configure the following service provider settings (copy from the Shocking Energy SSO settings page):
- Entity ID (SP Entity ID)
- Assertion Consumer Service (ACS) URL
- Ensure the SAML response includes these attributes:
email(required) -- the user's email addressfirstName(optional) -- used for JIT provisioninglastName(optional) -- used for JIT provisioning
- Set the Name ID format to
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress - Export the IdP metadata XML or note down:
- IdP SSO URL (the login endpoint)
- IdP Entity ID
- X.509 signing certificate
Shocking Energy configuration
Once your identity provider is configured, complete the setup in Shocking Energy.
Navigate to SSO settings
Go to Settings > Single Sign-On in the Shocking Energy dashboard. This page is only visible to team owners and administrators on the Enterprise plan.
Select your identity provider
Choose your identity provider from the dropdown list. If your provider is not listed, select Generic SAML.
Enter IdP metadata
You can configure the connection in one of two ways:
- Metadata URL: Paste the metadata URL from your IdP. Shocking Energy will automatically fetch and parse the configuration. This is the recommended approach as it keeps settings synchronised.
- Manual configuration: Upload the metadata XML file, or enter the IdP SSO URL, IdP Entity ID, and X.509 certificate individually.
Add and verify domains
Add the email domains that should be routed through SSO (e.g. yourcompany.com). Type each domain and press Enter to add it. When a user with a matching email domain signs in, they will be redirected to your identity provider.
Each domain must be verified via a DNS TXT record before SSO can be activated:
- Click Verify next to the domain to generate a verification token
- Add a TXT record to your domain's DNS configuration:
- Host / Name:
_se-verify.yourcompany.com - Value: The token shown on screen (e.g.
se-verify=a1b2c3d4-...)
- Host / Name:
- Click Check DNS to verify. DNS propagation can take up to 48 hours, but typically completes within minutes.
Domain verification proves ownership and prevents other teams from claiming your domain. The TXT record can be removed after verification is confirmed.
Test the connection
Click Test Connection to perform a test sign-in. This opens a new window where you authenticate with your identity provider. The test verifies that:
- The SAML handshake completes successfully
- Required attributes (email, name) are received
- The email domain matches a verified domain
If the test fails, check the error details displayed on screen and refer to the Troubleshooting section.
Activate SSO
Once the test passes, click Activate to enable SSO for your team. Team members with matching email domains will be redirected to your identity provider on their next sign-in.
Role mapping
Role mapping lets you automatically assign Shocking Energy roles based on group membership in your identity provider.
Configuring role mappings
- Navigate to Settings > Single Sign-On > Role Mapping
- Use the visual editor to create mappings between IdP groups and Shocking Energy roles
- For each mapping, specify:
- IdP group name or ID -- the group attribute value sent in the SAML assertion
- Shocking Energy role -- the role to assign (Owner, Member, or Engineer)
Default role
Set a default role that applies when a user signs in via SSO but does not match any role mapping. This ensures new users always receive an appropriate permission level.
If no default role is set and a user does not match any mapping, they will not be able to access the team. It is recommended to always configure a default role.
Group-based mapping
To use group-based role mapping, your identity provider must include group information in the SAML assertion. Refer to your IdP's documentation for configuring group claims:
- Entra ID: Add a group claim in Attributes & Claims
- Okta: Configure a group attribute statement in the SAML app settings
- Google Workspace: Use custom attributes or map organisational units
Role mappings are evaluated on every sign-in, so changes to group membership in your IdP are reflected the next time the user authenticates.
SSO enforcement
By default, SSO is available as an alternative sign-in method alongside email and password. You can enforce SSO-only login to require all team members to authenticate through your identity provider.
When SSO enforcement is enabled:
- Team members with a matching email domain must sign in via SSO
- Email/password and magic link sign-in are disabled for those users on this team
- Existing sessions remain valid until they expire, after which users must re-authenticate via SSO
To enable enforcement, go to Settings > Single Sign-On and toggle Require SSO for all members.
Before enforcing SSO, ensure all team members can authenticate through your identity provider. Users who are not assigned in your IdP will be locked out of the team.
Disabling vs deleting SSO
- Disable: Sets the SSO configuration to inactive. SSO enforcement is automatically removed to prevent lockouts. Team members fall back to email/password or magic link sign-in. The IdP configuration is preserved and can be re-activated later.
- Delete: Permanently removes the SSO configuration, including all domain verifications and the SAML provider registration. This cannot be undone — you will need to reconfigure SSO from scratch.
Login flow
When SSO is configured for your team, the sign-in experience changes to a two-step flow:
- Email entry -- the user enters their work email address and clicks Continue
- Method selection -- Shocking Energy checks whether the email domain has SSO configured:
- If SSO is enforced for the domain, the user is redirected to the identity provider immediately
- If SSO is available (but not enforced), the user sees a Continue with SSO button alongside the standard password option
- If no SSO is configured for the domain, the standard password field is shown
Personal email domains (Gmail, Outlook, Yahoo, etc.) are never routed to SSO, even if SSO is available for the team.
Just-in-time provisioning
Just-in-time (JIT) provisioning automatically creates Shocking Energy user accounts when someone signs in via SSO for the first time. This eliminates the need to manually invite each team member.
When JIT provisioning is enabled:
- A new user account is created using the
email,firstName, andlastNameattributes from the SAML assertion - The user is added to the team with the default role (or a mapped role if role mapping is configured)
- No invitation email is sent -- the user is immediately active
JIT provisioning is enabled by default when SSO is activated. You can disable it in Settings > Single Sign-On > Provisioning if you prefer to manually invite users before they can access the team.
Account Migration
When SSO is enabled, existing team members who previously signed in with email and password will receive a new account when they first sign in via SSO. Their previous data (jobs, notes, settings) remains tied to their old account. Shocking Energy provides two ways to merge these accounts.
Admin Migration Tool
Team owners can proactively manage account migration from Settings > Single Sign-On > Migration tab.
View affected users
The Migration tab shows a list of team members whose email domain matches your SSO configuration and who still have legacy (email/password) accounts.
Trigger bulk migration
Click "Migrate All" to create migration records for all affected users. For users who have already signed in via SSO, the data transfer happens immediately. For users who haven't yet, the migration will execute automatically when they first sign in via SSO.
Monitor progress
The migration table shows the status of each account: Pending SSO Sign-in, Completed, or Failed. Failed migrations can be retried.
Self-Service Account Linking
When a user signs in via SSO and a matching legacy account is detected, they are automatically redirected to the Account Linking page.
Review the prompt
The user sees a message explaining that their previous account data needs to be merged into their new SSO account.
Verify ownership
If the legacy account had a password, the user must enter it to confirm ownership. For magic-link-only accounts, SSO already proves email ownership, so this step is skipped.
Complete the merge
Data is transferred automatically: team memberships, job assignments, notes, tokens, and profile settings. The user is redirected to the dashboard.
Users can skip the linking prompt and merge later. They will be prompted again after 7 days. During this time, their old data remains accessible only under the legacy account.
What Gets Migrated
The migration transfers the following data from the old account to the new SSO account (scoped to the current team):
- Team membership and role (Owner/Member/Engineer)
- Job assignments (assigned_to)
- Job notes (authorship)
- API tokens (created_by)
- Invoice records (created_by)
- Profile data (name, avatar, locale, timezone)
Data in other teams is not affected. If the user is a member of multiple teams, each team's migration is handled independently.