Microsoft Entra ID SAML single sign-on

Before you start

• An active Enterprise subscription on CCTVplanner
• Owner access to the CCTVplanner organization console at cctvplanner.io/organization
• At least the Cloud Application Administrator role in Microsoft Entra ID
• The ability to publish a DNS TXT record for each domain you want to claim
• Your own Entra account, with a mail address at one of those domains, assigned to the enterprise application. The test signs in with it.
• A two-factor factor enrolled on the owner account, if you intend to set the sign-in mode to required

Steps

1. 1

   Verify your domain in the CCTVplanner console

   Open cctvplanner.io/organization and start a single sign-on connection. The console lists your claimed and verified domains and shows the DNS record to publish for each one.

   Publish the TXT record at your DNS provider, then return to the console and re-check the domain. The values are in the table below.

   Do this before anything else. A connection is bound to verified domains, and an assertion carrying an address outside them is refused with SSO_EMAIL_OUTSIDE_DOMAIN, at sign-in and again at every token refresh.

   TXT record name_cctvplanner-challenge.<your-domain>

   TXT record valuecctvplanner-verify=<token the console generates>

   Claim the mail domain people actually sign in with, not the tenant's onmicrosoft.com name. Leave the record published after verification. If your DNS provider strips underscores or appends the zone name twice, confirm the published record resolves before you re-check.

2. 2

   Create the non-gallery enterprise application

   Sign in to the Microsoft Entra admin center at entra.microsoft.com.

   Browse to Entra ID, then Enterprise apps, then All applications.

   Select New application, then Create your own application. Name it CCTVplanner, choose Integrate any other application you don't find in the gallery (Non-gallery), then select Create.

   SAML single sign-on is configurable on single tenant applications and gallery applications only. A multi-tenant application shows the SAML options greyed out.

3. 3

   Open Single sign-on and choose SAML

   In the Manage section of the application's left menu, select Single sign-on.

   On the Select a single sign-on method page, select SAML. The Set up Single Sign-On with SAML page opens.

   Leave this tab open. You move values between it and the CCTVplanner console for the next four steps.

4. 4

   Fill in the Basic SAML Configuration

   Select Edit in the Basic SAML Configuration section.

   Copy the Entity ID and the ACS URL from the CCTVplanner console, using the copy buttons beside them, and paste them into Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL). Do not type them from this page.

   Leave Sign on URL empty. Entra uses it when a person starts from the My Apps portal without a SAML request, and CCTVplanner accepts a sign-in that starts at Entra on the same ACS endpoint.

   Select Save. The fields are summarised in the table below.

   Identifier (Entity ID)https://auth.cctvplanner.io/auth/v1/sso/saml/metadata

   Reply URL (Assertion Consumer Service URL)https://auth.cctvplanner.io/auth/v1/sso/saml/acs

   Sign on URLleave empty

   Relay State (Optional)leave empty

   Logout Url (Optional)leave empty, Single Logout is not supported

   The two URLs above show the shape so you recognise a correct paste. The console is authoritative. A trailing slash or a stray space in the Reply URL is accepted when you save it here: at sign-in Entra then posts the assertion to an address that is not our endpoint, and the person sees no CCTVplanner error at all, because nothing reaches us. Compare the two strings character for character.

5. 5

   Set the Unique User Identifier and the claims

   Select Edit in the Attributes & Claims section.

   Open Unique User Identifier (Name ID). Set Name identifier format to Email address and Source attribute to user.mail, then Save.

   Entra emits four claims by default: the user principal name, the e-mail address, the first name and the surname. We read the e-mail address, the first name and the surname. The user principal name claim we ignore. In most tenants you change nothing here.

   We read the e-mail claim first and use the NameID only when no e-mail claim arrives, so a NameID pointed at the wrong attribute does not by itself break a connection whose e-mail claim is right. An e-mail has to arrive one way or the other. First name and surname are optional and only affect how the person's name is displayed. The full list is under Claims we read, near the end of this page.

   user.mail is empty on accounts that were never given a mailbox address, including many guest and service accounts. Microsoft documents that when the configured source attribute is null, Entra uses the userPrincipalName instead, and a UPN that is not a real mail address at a verified domain lands as SSO_EMAIL_OUTSIDE_DOMAIN. Populate the Mail attribute rather than switching the source to user.userprincipalname.

6. 6

   Add the groups claim, if you want it

   Still in Attributes & Claims, select Add a group claim.

   Choose Groups assigned to the application and leave Source attribute as the group ID. This keeps the assertion small.

   We record the groups claim. We do not map groups to roles. Roles are set in CCTVplanner.

   Skip this step if you have no use for it. Nothing else on this page depends on it.

   Entra limits a SAML assertion to 150 groups, including nested groups. Above that it omits the groups entirely and puts a link to the Microsoft Graph endpoint in their place. We do not follow that link, so the effect here is no groups at all. Restricting the claim to groups assigned to the application avoids the limit, at the cost of nested membership: the person has to be a direct member of an assigned group.

7. 7

   Give CCTVplanner the federation metadata

   Find the SAML Certificates section on the Set up Single Sign-On with SAML page and copy the App Federation Metadata Url. Its shape is in the table below.

   In the CCTVplanner console, paste it into the connection's metadata URL field and save.

   The console also accepts a pasted metadata XML document. Prefer the URL: saving the connection re-reads it, while a pasted document has to be replaced by hand every time the identity provider changes.

   App Federation Metadata Urlhttps://login.microsoftonline.com/<tenant id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app id>

   Entra creates the signing certificate with a three year life and mails a warning 60, 30 and 7 days before expiry to the notification email addresses on the SAML Signing Certificate page. That list starts as the single admin who added the application and holds up to five addresses, so put a distribution list on it. Entra does not replace the certificate by itself: someone creates a new one and selects Make certificate active, or the old one expires. On our side, a daily job reads the signing certificate expiry out of your metadata and e-mails your organization's owner before it lapses. After the certificate is replaced, open the connection in the console and save it again, which re-reads the metadata URL; if you pasted XML, paste the new document. Saving metadata on an active connection returns it to testing, so run the test again and switch the connection on.

8. 8

   Assign yourself and the pilot users

   In the application's left menu, select Users and groups, then Add user/group.

   Assign your own account first. The test in the next step signs in at Entra as you.

   Then assign one group or a small set of people for the pilot.

   Assignment in Entra controls who may reach CCTVplanner at all. It does not create CCTVplanner accounts on its own.

   If just-in-time provisioning is off in the CCTVplanner console, an assigned person who has never been added on our side is refused with SSO_JIT_DISABLED. Either turn just-in-time provisioning on and pick the role it grants, or add people first by hand or over SCIM.

9. 9

   Test the connection, then turn it on

   A connection stays in testing until the test passes. While it is testing, ordinary sign-ins through it are refused with SSO_CONNECTION_TESTING, so nobody can stumble into a half-built connection.

   Open the connection in the CCTVplanner console and start the test. The ordered procedure is under Prove it works below.

   When the test succeeds, switch the connection on.

   Choose the sign-in mode. Optional leaves password sign-in working. Required stops password sign-in for everyone at your verified domains. Before you switch to required, enrol a two-factor factor on the owner account: the owner may keep a password only with two-factor verified, and that is what stops a broken identity provider locking you out.

   Set the session cap while you are here. The default is twenty-four hours and you can shorten it.

   A connection is in one of four states: draft, testing, active or disabled. A disabled connection refuses sign-ins with SSO_PROVIDER_DISABLED, which is a different state and a different message from testing. Editing an active connection's metadata returns it to testing, so treat a later metadata change the way you treated this first setup.

10. 10

    Set up SCIM provisioning, if you want directory-driven accounts

    SCIM is a separate tab on the same enterprise application and a separate set of values in the CCTVplanner console.

    In the application's left menu select Provisioning, set the Mode menu to Automatic, and expand Admin Credentials. Paste the SCIM base URL as Tenant URL and the token from the CCTVplanner console as Secret Token, then select Test Connection. Some tenants start this from a New configuration button, with the same two fields. Both are in the table below.

    Under Mappings, turn the group mapping off: we do not map directory groups to roles. Under Settings, set the scope to sync only assigned users.

    The full procedure, including what deactivation does to seats and sessions, is on our SCIM provisioning page. It is not repeated here.

    SCIM is optional. SAML sign-on works without it.

    Tenant URLhttps://<project>.supabase.co/functions/v1/scim/v2

    Secret Tokenthe bearer token the CCTVplanner console shows once

    The console shows a SCIM token once and stores only a SHA-256 hash of it. Two tokens may be live at a time and each expires after a year. If you lose the token, issue a new one, you cannot read the old one back.

Claims we read, in the order we read them

Prove it works

1. Leave the connection in testing. While it is testing, ordinary sign-ins through it are refused with SSO_CONNECTION_TESTING.
2. Confirm your own Entra account is assigned to the enterprise application and that its mail address is at a verified domain.
3. In the CCTVplanner organization console, open the connection and select the test button. The console opens Microsoft Entra ID in a new browser tab.
4. Sign in there as yourself. That sign-in creates a twin account: a second, separate CCTVplanner account at your own address, held by the identity provider and occupying no seat, because an SSO identity is never linked to an existing password account.
5. The test tab confirms the result, signs the twin account out again and hands the outcome back to the original console tab, which restores your own session.
6. Read the outcome in the console. The connection can only be switched on after the test passes.
7. Switch the connection on. Test first, turn on second, in that order.
8. With the connection on, sign in once from the CCTVplanner sign-in page using your work address, to confirm a sign-in that starts at CCTVplanner.
9. Sign in once from the My Apps portal, to confirm a sign-in that starts at Entra.
10. If you set the sign-in mode to required, confirm in a private window that a password sign-in at a verified domain now fails with SSO_REQUIRED.

Troubleshooting

Worth knowing

• An SSO identity is never linked to an existing password account at the same address. Someone who already had a CCTVplanner password account at their work address ends up with two separate accounts, which is the usual source of confusion in a pilot. It is also why the console's test creates a twin of your own account instead of reusing it.
• A sign-in that starts at Entra, from the My Apps portal, is accepted. The redirect target has to be on our allow list.
• Access tokens live fifteen minutes. A fifteen minute figure in a network trace is not the session length.
• We support SAML 2.0 only. There is no OpenID Connect connector, so an Entra app registration configured for OIDC does not work here.
• The organization console shows the service provider values with copy buttons, the claimed and verified domains with the DNS TXT record to publish, the connection with its display name, provider template, entity id and certificate expiry, the sign-in policy, the provisioning tokens, and an audit list with an export button.
• Microsoft's own documentation for these screens is the Entra ID enterprise application and SAML claims articles on learn.microsoft.com. The screen names used here were checked against them.