S

Central Identity

SSO Setup Guide

Home Docs

Public guide

How to connect a new app to this login system

This page shows the whole setup in plain English. Start in the admin panel. Then add the login flow to your app. Follow the steps in order.

Quick idea

Your app sends the user here to sign in. This system checks who they are. Then it sends the user back to your app.

Before you start

Know the name of your app. Example: Recipe Board.
Know the web address of your app. Example: https://recipes.example.com.
Know the return page on your app after login. Example: https://recipes.example.com/auth/callback.
Decide whether your app should have a client secret. Most server-based PHP apps should.
Have one test user ready so you can try the login after setup.

Simple words

Redirect URL: This is the page on your app where the user comes back after sign-in.
Callback page: This means the same thing as the redirect URL. It is just the return page after sign-in.
Client ID: This is the app name the login system uses behind the scenes.
Client secret: This is a private password for your app. Keep it on the server. Do not show it in browser code.
Role: This is the label that tells your app what the user is allowed to do.
Code: This is a short one-time pass your app swaps for the user details.
1

Set up a new app in the admin panel

Do this first. It gives your app the details it needs.

1

Go to the service area

Sign in as an admin. Open `Admin`, then open `Services`, then click `Register service`.

2

Enter the app name

Use a clear name people will recognise. Example: `Recipe Board`.

3

Enter the slug

Use a short lowercase label with hyphens only. Example: `recipe-board`.

4

Enter the client ID

Use a stable ID for code and settings. Example: `recipes-web`. Keep it short and clear.

5

Choose the app type

Pick `Confidential client` for a normal PHP app that runs on your server. Pick `Public client` only if the app cannot safely store a secret.

6

Add the redirect URL

Enter the page on your app that receives the user after sign-in. Example: `https://recipes.example.com/auth/callback`.

7

Add any extra redirect URLs

If you have a local test app too, add that as another line. Example: `http://localhost:8000/auth/callback`.

8

Add the role list

Enter the role names your app will use. Example: `admin`, `editor`, `user`, `viewer`.

9

Save the app

Click `Register service`. If the app uses a secret, the system will show it once after save.

10

Copy the values you need

Copy the `Client ID`. If a secret was shown, copy that too and store it in your app settings or `.env` file right away.

11

Keep the secret safe

Do not send the client secret to the browser. Keep it only on the server, like a database password.

12

Check the app is active

Open the service again and make sure its status says `active`. If it says `disabled`, switch it back on.

13

Give users access

Open `Users`, open the user you want, then add the new service in the `Assign service access` area.

14

Choose their role

Pick the role they should get in that app. Example: give one person `admin` and another person `viewer`.

15

Test with one real user

Before you tell everyone, test the login once with a user who has access.

Example values

App name: Recipe Board
Client ID: recipes-web
Redirect URL: https://recipes.example.com/auth/callback
Role list: admin, editor, user, viewer
Client secret: shown after save for confidential apps
2

Set up login on your app

Do this on the app that wants to use the shared login.

1

Collect the app settings

From the admin panel, copy the `Client ID`, the `Client secret` if your app has one, and the exact redirect URL you saved.

2

Add them to your app config

Put them in your app `.env` file or config file. Keep the secret on the server only.

3

Add the auth server URL

Also add the main login system URL. Example: `https://auth.example.com`.

4

Use the shared client library

The easiest path is to use the files in `shared-client-lib`. They already know how to start login, handle the callback, and check the user role.

5

Add a login button

Make a button or link that sends the user to your `/login` route. That route should call the SSO helper and send the user to the central sign-in page.

6

Add the callback route

Create a route like `/auth/callback`. This route receives the user after sign-in.

7

Handle the return from the login system

On the callback route, read the `code` and `state` values from the URL. Then pass them to the shared callback handler.

8

Swap the code for user details

The shared helper sends the code back to the login system from your server. It gets back the user details your app needs.

9

Create your app session

After the helper gives you the user details, save them in your own app session. This is what keeps the user logged in on your app.

10

Read the user details

Use the returned values like `email`, `name`, `role`, and `access_status` to decide what the user should see.

11

Allow or deny access

If `access_status` is not `active`, stop there and show a simple message. If the role is not allowed for a page, block that page too.

12

Protect your pages

On private pages, check that the user has a valid session before showing anything. For admin pages, also check the role.

13

Test with a real user

Try the full flow: click login, sign in, come back to your app, and confirm the right role is loaded.

14

Test a user without access

Try with a user who does not have the app assigned. Make sure they are blocked cleanly.

15

Test logout

Log out from your app and check that the app session is cleared. The current shared helper clears the local app session.

Example `.env` values

SSO_AUTH_URL=https://auth.example.com
SSO_CLIENT_ID=recipes-web
SSO_CLIENT_SECRET=replace_with_real_secret
SSO_REDIRECT_URI=https://recipes.example.com/auth/callback
SSO_TOKEN_SIGNING_KEY=your_shared_signing_key

Simple route idea

`/login` starts the shared sign-in
`/auth/callback` receives the user back
`/logout` clears your app session

Common mistakes

Using a redirect URL that does not exactly match the one saved in the admin panel.
Forgetting to copy the client secret right after creating a confidential app.
Giving a user no access to the app, then wondering why login is denied.
Checking only that the user is logged in, but not checking their role.
Putting the client secret in browser code. Keep it on the server only.

Quick summary

Create the app in the admin panel.
Copy the client ID, redirect URL, and secret if the app has one.
Add those values to your app config.
Use the shared client helper to start login and handle the callback.
Create a local session in your app and check the returned role before showing protected pages.