Single Sign-On (SSO) - User manual

Overview

Single Sign-On (SSO) lets the people in your organization log in to ChargePilot with their existing Microsoft work account instead of a separate ChargePilot password. Access is controlled by your own identity provider (Microsoft Entra ID), so joiners, leavers, and password policies are managed in one place — yours.

Who can use this feature: Organizations with a Microsoft Entra ID tenant. SSO is enabled per organization by The Mobility House; once active, it applies to all users in your organization.

What is SSO in ChargePilot?

When SSO is enabled for your organization:

• Users click Login via Microsoft on the ChargePilot login page (or use your organization's dedicated login link), and are authenticated by Microsoft.
• No ChargePilot password is created or stored for SSO users.
• New users get access either through an invitation you send in advance, or automatically on their first login — you decide (see Step 4).
• Roles and site access are managed by your administrators in User Management, exactly as for non-SSO users (see the User management - User manual).

How the Setup Works

The setup involves a short exchange of information between you and our team, followed by configuration on your side. In total there are five steps:

Once we have received the information from Steps 1 and 3, we activate SSO for your organization and confirm with you.

1️⃣ Step 1: Define Your SSO Alias

Before we can activate SSO, we need a unique SSO alias for your organization. The alias identifies your organization at login and is part of your Redirect URL.

Requirements for the alias:

• No spaces
• No special characters
• Maximum length: 64 characters

Example: For The Mobility House Solutions, the alias is TMHS.

Please send us your preferred alias to get started.

⚠️ Choose your alias carefully. Your Redirect URL (Step 2) is built from the alias. If the alias changes after you have configured Entra ID, the app registration has to be redone.

2️⃣ Step 2: Set Up Your Redirect URL

Using your alias, you can build your Redirect URL yourself with this pattern:

https://keycloak.tmh.energy/realms/BackendProd/broker/<SSO-Alias>/endpoint

Replace <SSO-Alias> with your alias exactly as sent to us — upper- and lower-case letters matter.

Example (for alias TMHS):

https://keycloak.tmh.energy/realms/BackendProd/broker/TMHS/endpoint

Add this Redirect URL to your Entra ID app registration under Authentication → Redirect URLs.

3️⃣ Step 3: Send Us Your Microsoft Entra ID App Details

Once your app is set up with the Redirect URL, send us the following details from your Entra ID app registration:

? Send the Client Secret encrypted. The secret is shown only once in Microsoft Entra — afterwards it is hidden. If it is lost, a new one has to be generated.

Once we have your alias and these three values, we activate SSO for your organization and confirm with you.

ℹ️ For security, your Client Secret is never displayed back to us after it is saved. If your SSO configuration ever needs to be changed, the secret must be re-entered (or a new one supplied) at the same time.

4️⃣ Step 4: Choose How SSO Users Get Access

When a user logs in via SSO for the first time and does not yet have an account in ChargePilot, there are two ways they can get access to sites and roles. Both options work — it is up to you how you handle new users.

Option A: Via Invite

You invite each user manually before they log in for the first time:

1. Go to User Management.
2. Click + Invite user and enter the user's details.
3. Select the role for the user (Admin, Editor, or User).
4. Select the site(s) the user should have access to.
5. Click Send invitation. The user receives an invitation email with a login link.

When the user activates their account, they are directed through Microsoft sign-in — no ChargePilot password is set. You can also invite several users at once with the Upload CSV tab.

✅ Best when you want to control roles and site access before a user's first login.

Option B: Automatic Provisioning

Users are granted access automatically the first time they log in via SSO:

• On first login, the user is assigned a standard site and role.
• Afterwards, a User Manager can adjust the user's site access and role under User Management.

✅ Best when you want zero onboarding effort and are happy to fine-tune access afterwards.

⚠️ With automatic provisioning, anyone in your Microsoft tenant who can pass sign-in for the ChargePilot app will be able to create an account. If some people should not have access to ChargePilot at all, restrict who is assigned to the app in Entra ID.

5️⃣ Step 5: Log In via SSO

Once your Entra ID app is configured with the Redirect URL and we have confirmed activation, users can log in via SSO in one of two ways.

Option A: Your Dedicated Login Page

Use your organization's login link with your alias:

https://myaccount-chargepilot.tmh.energy/auth/sso/tenant?alias=<SSO-Alias>

Example (for alias TMHS):

https://myaccount-chargepilot.tmh.energy/auth/sso/tenant?alias=TMHS

Users are taken straight to Microsoft sign-in and then to the ChargePilot dashboard.

? Share this link internally (intranet, onboarding emails, bookmarks) so your users never have to remember the alias.

Option B: Standard Login Page

1. Open the regular ChargePilot login page.
2. Click Login via Microsoft.
3. Enter your organization's SSO alias and click Continue.
4. If you are already signed in to your Microsoft account, you land directly on the ChargePilot dashboard. Otherwise, Microsoft prompts you to sign in, then redirects you to the dashboard.

First-Time Login

The first time a user in your organization logs in via SSO:

• If they were invited (Step 4, Option A), they get the role and site access you chose in the invitation.
• If they were not invited (Step 4, Option B), their account is created automatically with the standard site and role.
• In both cases, their role and site access can be adjusted afterwards in User Management (see Editing a User in the User management manual).

Moving Existing Users to SSO

If your organization already had users with ChargePilot passwords before SSO was enabled:

• Existing accounts are linked by email address on the user's first SSO login. No duplicate account is created, and their role and site access are kept.
• Make sure the email address in ChargePilot matches the user's Microsoft account email exactly.
• Once SSO is enforced for your organization, users can still log in with their old ChargePilot password.

What Is Different for SSO Users

Troubleshooting

Tips & Notes

• Only one alias exists per organization. Everyone in your organization uses the same alias — decide it once, before touching Entra ID.
• Store the Client Secret's expiry date in your IT calendar. When it expires, SSO login stops working for everyone until a new secret is configured.
• Removing a user from the Entra ID app blocks their next login. To also end an active ChargePilot session immediately, delete the user in User Management.
• You can mix both access options: invite key users in advance and let everyone else be provisioned automatically.
• Role and site permissions work exactly as for non-SSO users — see the User management - User manual for details on roles, site scoping, and editing users.