Citizen Space Admin Single Sign-on (SSO) - help and support for organisations

Citizen Space Admin SSO allows you to connect your identity provider to your Citizen Space site so that admin users can sign in with their existing identity provider credentials.

Overview

• Citizen Space Admin SSO is an authentication method only. Users are still required to have a valid Citizen Space account which controls their roles and permissions within Citizen Space.
• Citizen Space Admin SSO is provided using the OpenID Connect (OIDC) protocol. It uses Authorization Code Flow with Proof Key for Code Exchange (PKCE).
• You can only set up one identity provider with your Citizen Space site.

To configure Admin SSO, you will need:

• A Site Admin account on your Citizen Space site.
• Administrative privileges in your identity provider.

Configure Admin SSO with Microsoft Entra ID

Citizen Space is designed to integrate with any identity provider which supports the OpenID Connect (OIDC) protocol. Specific instructions for setting up Microsoft Entra ID are provided below:

Please note: as Citizen Space has a single-tenant deployment model, it is not available as an Entra ID gallery app. You’ll need to set up a new Entra ID app registration which supports a one-to-one connection between your Entra ID database and your Citizen Space site.

Step 1: Add the Citizen Space SSO application to Entra ID

1. Sign in to your account on the Microsoft Entra ID dashboard.
2. Under Identity > Applications, select App registrations then click New registration.
3. Enter a name for your application.
4. Under Supported account types ensure that Accounts in this organizational directory only is selected.
5. Under Redirect URI select the Web option. Leave the URL field blank for now.
6. Click Register.

You'll be taken to an overview screen with details of the application you just created. You'll need these to configure the Citizen Space integration.

Step 2: Configure your Citizen Space site

1. Open a new browser tab or window and log in to your Citizen Space site.
2. Load the SSO configuration screen at https://yourcitizenspacesite/_admin/sso_settings
3. Complete the fields as follows:
   1. The Client / Application ID can be found on Entra ID application overview screen from Step 1
   2. The Discovery / Metadata document can be found via the endpoints tab of the Entra ID application overview screen (labelled OpenID Connect metadata document).
   3. Create a new client secret under the Entra ID Certificates & Secrets submenu and enter this into the Client / Application Secret field.
4. Click Save SSO Settings.

Step 3: Configure the Entra ID Citizen Space SSO application

1. In the Entra ID sidebar click Authentication.
2. Under the Web > Redirect URIs heading, copy and paste both Redirect URIs from the Citizen Space SSO configuration screen.
3. Leave other redirect URI options unchecked.
4. Click Save.

Step 3b: Grant admin consent for Entra ID Citizen Space SSO application (Optional, recommended)

By default, each user will grant consent to the Citizen Space application the first time they log in using SSO. To avoid this you can Grant admin consent to give tenant-wide consent for the Citizen Space application.

1. Click Permissions / API permissions in the Entra ID sidebar.
2. Click Grant admin consent for <user directory>
3. Follow the Entra ID prompts to grant admin consent for the Citizen Space application.
4. Once you have granted admin consent, the permissions screen should include a new 'User.Read' permission as shown below:

Step 4: Test the Citizen Space SSO connection

You can verify that the connect has been set up correctly by activating SSO on your own Citizen Space user account as follows.

1. On your Citizen Space site, navigate to your Citizen Space user profile using the link under your name in the toolbar.
2. Click the Activate SSO link on your user profile.
3. Click the Link Account button on the confirmation page.
4. You will be redirected to the Microsoft login page to enter your Entra ID credentials, and then redirected back to your Citizen Space site. If everything is successful you will see a message that your Citizen Space and Entra ID user accounts have been linked.

Step 5: Log in with Citizen Space SSO

Once your account has been linked, you can log in to your Citizen Space site using your Entra ID credentials.

1. Log out of Citizen Space using the link under your name in the toolbar.
2. From the login screen, click Log in with Single Sign-on.
3. You will be redirected to the Microsoft login page to enter your Entra ID credentials.
4. Enter the credentials for the Entra ID account that you linked in Step 4.
5. You will be redirected back to your Citizen Space site and logged in.

Enforcing SSO for certain users

Once you have successfully configured Admin SSO on your Citizen Space site, all users will have the option to enable SSO on their Citizen Account by linking it to a valid account on your configured identity provider. For more information, see the article Citizen Space Single Sign-on (SSO) - Linking Accounts.

Alternatively, you can require certain users to log in with SSO by specifying one or more Enforced SSO email domains as follows:

1. Open a new browser tab or window and log in to your Citizen Space site.
2. Load the SSO configuration screen at https://yourcitizenspacesite/_admin/sso_settings
3. Enter one or more comma-separated domains in the Enforced SSO email domains field.
4. Click Save SSO Settings.

Any Citizen Space user with an email address matching one of the specified domains will now be required to log in via SSO. Existing non-SSO users will will be sent an email the next time they try and log in, providing them with details on how to activate SSO on their account.

SSO Emergency User

Please note: If you are enforcing SSO for your organisations email domain, we recommend creating one Site Admin 'emergency' account with an email address on a different domain. This allows the emergency account to log in with a username and password and resolve any SSO configuration issues that might arise if your Client secret is invalid or expires.