Single sign-on for the CMS

Out of the box, people sign in to /cms with an email address and a password that Cendia stores. With single sign-on, they can sign in with the account they already have at work instead: the sign-in page offers Sign in with Microsoft (or whatever you call it) below the password form.

Cendia speaks OpenID Connect, the standard behind Microsoft Entra, Okta, Auth0, Ping, Keycloak and Google Workspace. This guide walks through Microsoft Entra step by step, then says what differs for the others.

The short version: register an app with your provider, turn on its groups claim, put three values and your group mappings in configuration, and keep a password administrator as a way back in. No code changes are needed.

How it decides who gets in

Access comes from the person's groups at the provider, mapped to Cendia's groups in your configuration:

The mappings live in configuration, not in the CMS, on purpose: who may administer your CMS is a deployment decision, made by whoever controls the server's settings.

Set it up with Microsoft Entra

You'll need to be able to create app registrations and groups in your Entra tenant. Do these steps in order; each one gives you something the next one needs.

1. Register the app

1. Go to entra.microsoft.com and open Identity › Applications › App registrations. Click New registration.

2. Name: anything your administrators will recognise, such as Cendia CMS.

3. Supported account types: Accounts in this organizational directory only (single tenant).

4. Redirect URI: choose Web, and enter your site's address followed by /cms/signin-oidc:

   https://www.example.com/cms/signin-oidc
   

5. Click Register.

The redirect URI is where Entra sends the browser back after sign-in, and it has to match exactly. Add one for every address the CMS is reached on: the production host, a staging host, and http://localhost:5081/cms/signin-oidc (or your own port) for local development. Entra accepts plain http only for localhost. To add more later, open the app's Authentication page.

2. Copy two IDs

The app's Overview page shows:

• Application (client) ID
• Directory (tenant) ID

Neither is a secret. They go in appsettings.json in step 6.

3. Create a client secret

1. Open Certificates & secrets and click New client secret.
2. Give it a description and an expiry, and click Add.
3. Copy the Value column, not the Secret ID. Entra shows it only once.

This one is a secret. It never goes in appsettings.json; step 6 shows where it does go.

Note the expiry date. When the secret expires, sign-in through Entra stops working (people are sent back to the sign-in page with a message) until you create a new one and update the setting. The password form keeps working throughout.

4. Send group membership in the sign-in

1. Open Token configuration and click Add groups claim.
2. Tick Security groups.
3. Leave ID, Access and SAML on Group ID, and click Add.

Without this, Entra doesn't say which groups the person is in, and every sign-in is refused.

5. Create the groups

Create a security group for each kind of access you want to give. Most installations need two:

1. Open Identity › Groups › All groups and click New group.
2. Group type: Security. Group name: for example Cendia Administrators.
3. Add the people who should have that access as Members, and click Create.
4. Open the group and copy its Object ID.

Repeat for Cendia Authors. Cendia identifies a group by its Object ID, not its name, so renaming a group in Entra later changes nothing.

6. Configure the site

In appsettings.json, with your two IDs from step 2 and the Object IDs from step 5:

{
  "Cendia": {
    "Oidc": {
      "Enabled": true,
      "DisplayName": "Microsoft",
      "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
      "ClientId": "<client-id>",
      "GroupMappings": {
        "<object-id-of-Cendia-Administrators>": [ "Administrator" ],
        "<object-id-of-Cendia-Authors>": [ "Author" ]
      }
    }
  }
}

A provider group can map to several Cendia groups, which is how you give people one of your own groups as well as their role:

"<object-id-of-Marketing-Team>": [ "Author", "Marketing" ]

The client secret from step 3 goes in user-secrets on your own machine:

dotnet user-secrets set "Cendia:Oidc:ClientSecret" "<secret value>"

and in an environment variable on a hosted site:

The double underscore is how .NET spells : in an environment variable. Restart the site after changing any of these settings.

7. Keep a way back in

Before anyone signs in through Entra, make sure the CMS has an administrator who will keep signing in with a password, and that it is not an address anyone will use with Entra. For example:

1. Sign in with your password as you do today.
2. Under Settings › Users, add a user such as [email protected] with a strong password and the Administrator role. Store the password somewhere your team can reach in an emergency.

If you skip this and your own password account is the only administrator, Cendia refuses to link it the first time you sign in through Entra, and tells you to create another administrator first.

8. Check it

1. Sign out, and open /cms. Below the password form you should see Sign in with Microsoft.
2. Click it, and sign in with an account in one of your mapped groups. You should land in the CMS.
3. Under Settings › Users, that person shows a Microsoft badge next to their status, and the roles their group maps to.
4. Optionally, move yourself from one group to the other in Entra, sign out of Cendia and sign in with Microsoft again: your role follows. Group changes can take a minute to reach Entra's sign-ins.

Other providers

Everything above applies to any OpenID Connect provider. What differs is where you find the three values and what the groups claim looks like.

In every case, register https://<your-site>/cms/signin-oidc as the redirect URI, and ask for the openid, profile and email scopes (Cendia asks for these by default).

What people see

Signing out of the CMS signs the person out of Cendia only, not out of the provider. Clicking Sign in with Microsoft again usually signs them straight back in without asking.

Editing a linked person's roles

You can still change a linked person's roles under Settings › Users, and the change takes effect straight away. But their next sign-in sets them back to what their provider groups say, so the roles dialog warns you. To change someone's access for good, change their groups at the provider.

To stop someone signing in again straight away, without waiting for the provider, lock the account under Settings › Users. That holds whichever way they try to sign in.

Troubleshooting

Configuration reference

Cendia uses the authorization code flow with PKCE and doesn't keep the provider's tokens: once the person is signed in, nothing more is asked of the provider until their next sign-in.