Documentation › Set up the platform
Set up the platform (first installation)
A new SerenForce platform has no database at all. The first time you open the application, the Set up SerenForce page (/app/setup) guides you: the page registers the Microsoft sign-in application and names the first administrator. The catalog database is created and kept up to date by the application itself, when it starts.
Before you start
- The catalog is the database that knows every tenant, their subscriptions and the super administrators. Every step of this setup is written in it: you can stop at any step and resume later, from any browser, and the page always shows what is done and what is next.
- Its connection string is the only setting of the deployment you need: a secret,
PLATFORM_CATALOG_CONNECTION_STRINGin theback-prodlibrary of Azure DevOps. There is no step to create the database: each time the application starts, it creates the database if it does not exist yet, brings its tables up to date and adds the permissions and the super administrator role. Until it did, the page only says what is missing (the connection string is not in the settings, or the database cannot be reached: the application tries again every 30 seconds, check the connection string and that the server lets the application in, then press Check again). - The catalog runs on SQL Server (by default) or on PostgreSQL: the setting
PLATFORM_CATALOG_DATABASE_ENGINEofback-prod(SqlServerorPostgreSql) says which, and the connection string is written for that engine (for PostgreSQL:Host=…;Database=…;Username=…;Password=…). The waiting page shows the engine under its message, and the summary of the last step shows it as Catalog database. The tenants you enroll afterwards choose their Database engine too (SQL Server or PostgreSQL); a database On the same server as the catalog takes the engine of the catalog (the Database engine list is then not shown), and Create it on Azure (Bicep file or deployment) is only offered for SQL Server. - On Azure SQL, the application creates the catalog as a Standard S0 database (the size included in the Azure free account, about 13 EUR a month after it), never a General Purpose one. Its default name is
sqldb-sf-catalog-prod, and a tenant database on the same server is proposed assqldb-sf-<identifier>-prod. A database that already exists keeps its name and its size. - On the Database step of the enrollment of a tenant, the list How do you get the database? offers three ways to get the database:
- On the same server as the catalog (the default): only the name of the database is asked; it is created on the server of the catalog, with the same login, wherever that server is (Azure, another cloud, a server of your company). The name of the catalog database itself is refused.
- Use an existing database: only the Connection string of the database is asked.
- Create a new database: the full form (Where is it hosted?, then on Azure How is it created?: Bicep file or connection string; a Terraform file for AWS and Google Cloud).
- Open the address of the application soon after the deployment: while the platform is not set up, you land on the setup page. The first steps need no password (nobody can sign in yet): they are limited in rate and refused as soon as the platform is set up, so do not leave a new deployment unattended. Once it is set up, the page simply says The platform is already set up.
- Each field shows a greyed example and an explanation. Each step creates its own resource with its own button (Register the application, Save the email service, Save the cache, Save the logs destination): when it is done the page goes back to its top and shows a green success message under the title of the step, and a green tick appears in the step and in the side bar. The same happens when you keep Memory (each instance has its own) or No cache for the cache, or No service for the logs: these choices count as a step done. Next and Back only move between the steps and create nothing, so you can skip an optional step.
1. Authentication (Microsoft Entra ID: registration and sign-in)
As soon as you press Register the application, a green message above the Back and Next buttons confirms the registration: click Next to continue.
The platform signs users in with one Microsoft Entra ID application, shared by the setup and the administration (each tenant gets its own afterwards). The setup registers it for you, before anybody signs in.
- Who registers the application: Create it now, with access to Azure (the default), or Generate a script and resume here once it has run if you would rather not give the application an access to Azure (see Register the application with a script below).
- Authenticate to create the Azure App registration (only when this page registers the application): the identity of the API or a service principal. It needs the Microsoft Graph permission Application.ReadWrite.All (or the Application Administrator role). Used for this request only, never stored.
- Sign in with my Azure account (a choice of Authenticate to create the Azure App registration): use it when the registration fails with “Insufficient privileges”. Click Sign in to Azure, open the Microsoft page shown, type the code displayed and sign in with an Application Administrator or Global Administrator account; the page notices it, then you register the application with that account. Nothing is kept.
- Get Azure Token (a choice of Authenticate to create the Azure App registration): use it if your organization refuses the sign-in with a code (for example “error 530035”, device not registered). Get a token where you can sign in, such as the Azure Cloud Shell of the portal, with
az account get-access-token --resource https://graph.microsoft.com --query accessToken -o tsv(the Copy the command button next to it copies it in one click), and paste it in Access token. The token lasts about an hour and is never kept. - Application name: the name shown in Entra ID and on the Microsoft sign-in page, proposed by the convention sp-<product>-<catalog>-<environment>, for example sp-sf-catalog-prod (the environment follows the web address: local, dev, test, staging… or prod). You can change it.
- Web address of the application: where your users open SerenForce, without
/app, for example https://www.serenforce.com. After the sign-in, Microsoft only sends them back to this address (https, or http://localhost in development). - Allow personal Microsoft accounts: choose now, it changes how the application is registered. If on, Outlook, Hotmail and Live accounts can sign in to a tenant that welcomes them, where everybody works in an organization (the sign-in audience becomes work, school and personal accounts). The administration stays reserved to the accounts of your directory, even with this switch on: see A personal account as super administrator.
- Secret lifetime: how long the client secret that SerenForce creates with the application lasts (1, 3, 6, 12, 18 or 24 months; 12 months by default). The date when a secret created today expires is shown below. The script uses the same lifetime. See Client secrets and their alerts.
- AI assistant addresses (optional): the addresses where an AI assistant installed on a person’s computer (such as Claude Code) returns after sign-in, one per line, for example http://localhost/callback. Left empty, the application accepts no assistant. Accepted: https:// addresses, http:// addresses of the local machine only (localhost, 127.0.0.1, [::1]) and the address of a desktop application (myapp://callback), without #. Each organization has its own addresses, typed when it is enrolled. The (i) button next to the field explains why it exists, what to type and how to connect the assistant afterwards (with a sample command for Claude Code). See Connect an AI assistant.
- Permissions given to the application: the list of the scopes the application gets, what each one is for and how the consent is given. Read it before you register the application, and add the same scopes if you register it yourself. See Permissions of the applications.
Press Register the application (or Use this application when you registered it yourself): the application is registered (once only) and the step gets its green tick. Then press Next to go to the Email step (then the Cache and Logs steps); Back returns to the previous step and keeps what you typed. At the Logs step, press Finish the setup (only possible once the application is registered): the setup is finished. The page then shows a summary of what was registered and a link to this guide; press Sign in to the administration and sign in with that application.
Register the application with a script
With Generate a script and resume here once it has run, you register the same application yourself, once the script has run. Fill in the name, the web address and the choice on personal accounts first: the script describes exactly that application.
- Download the script
Choose the Script format (Bicep, ARM template (JSON) or Terraform), then press Download the script.
- Run it
With an account that has the Application Administrator role (or the Application.ReadWrite.All permission) in your directory, after
az login. Bicep (0.36 or later) and ARM template:az group create --name serenforce-setup --location westeurope, thenaz deployment group create --resource-group serenforce-setup --template-file serenforce-entra.bicep(orserenforce-entra.json), then run the command given by the output identifierUriCommand. Terraform:terraform init, thenterraform applyin the folder ofserenforce-entra.tf. - Note the identifiers it gives, then type them
Write them down: SerenForce needs them. Type Application (client) ID: the output clientId (client_id with Terraform). Directory (tenant) ID: the output directoryTenantId (directory_tenant_id). Press Use this application: the step gets its green tick; go on with Next and finish at the Logs step.
Check the two identifiers carefully: the setup records the application only once.
Google Cloud or AWS instead of Microsoft Entra ID
If your organization signs in with Google or with Amazon Cognito, choose the platform in Cloud platform (Google Cloud (Google sign-in) or Amazon Web Services (Cognito)). SerenForce cannot register the application at these providers for you: you create it yourself in the console of the provider, then give two things to the setup.
- On Google Cloud: create an OAuth client of type Web application and add the addresses listed under the fields as authorized redirect URIs. The Authority (address of the issuer) is always https://accounts.google.com.
- On AWS: create an app client in your Amazon Cognito user pool (hosted sign-in page, implicit grant) and add the addresses listed under the fields as callback URLs. The Authority (address of the issuer) is the address of the user pool, such as https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_AbCdEf123.
- Type the Client id of the application, then press Use this application, go on with Next and finish at the Logs step with Finish the setup. No access to Azure is needed, and the choice of personal Microsoft accounts does not apply.
When the web address of the application starts with www. (https://www.serenforce.com), the list also gives the same addresses without www. (https://serenforce.com/app/admin/callback): the site answers at both, so register them all. The Amazon Cognito Terraform file already contains them. With Microsoft Entra ID, the setup registers both by itself.
People sign in with their Google or Cognito account, with the email address that is on it. The first tenant, and every tenant you enroll afterwards, can also choose Cloud platform at the Authentication step: the database and the file storage of a tenant that signs in with Google or AWS are never prepared in Azure.
Where the tenant keeps its files
At the File storage step of the enrollment, Storage provider offers four choices. On-premise: a folder of the SerenForce server. Azure: an Azure Blob Storage container (address of the account, container name, and the name and key of the account unless you go through the Azure sign-in) or an Azure file storage share. AWS: an Amazon S3 bucket; give the address of the region of the bucket (for example https://s3.eu-west-3.amazonaws.com), the bucket name, the Access key ID and the Secret access key of an IAM user allowed to read, write and delete in that bucket. Google Cloud: a Google Cloud Storage bucket; the address is already filled in, give the bucket name and an HMAC key of a service account (Google Cloud console, Cloud Storage settings, Interoperability tab): HMAC access ID and HMAC secret. A bucket that does not exist is created at the end of the enrollment; you can also create or test it right away with Create the bucket now and Test the storage. Nothing is prepared in Azure for a bucket. The secret key is never kept in the enrollment in progress: after a reload, type it again. A tenant that signs in with Google or AWS can keep its files in Azure Blob Storage only with the name and the key of the account. The storage of an enrolled tenant is changed in the Storage tab of its page (Google Cloud Storage included); the files already saved are not moved.
With Azure and Azure Blob Storage, choose the Storage account first. Create a new storage account on Azure: describe the account, then download the Bicep file or deploy it right away; its container is created with it. Use a storage account that already exists: under Find an existing storage account, give the subscription, sign in to Azure and press Find the existing ones; the account you pick with Use this storage account fills in its address and name (you can also type them). Then choose the Container: Create a new container for this tenant (its files stay separate, button Create the container now) or Use a container that already exists in this storage account: press List the containers and pick it in Existing container. The subscription, the way to sign in to Azure and the container chosen are kept with the enrollment in progress; secrets (account key, client secret, token) never are.
Terraform files for AWS and Google Cloud
When you choose AWS or Google Cloud, SerenForce gives the Terraform file that creates what is needed there, the same way it gives a Bicep file for Azure: press Download the Terraform file under Create it on Amazon Web Services with Terraform (or on Google Cloud). SerenForce creates nothing in these clouds itself. Run terraform init then terraform apply with an account of the cloud (on Google Cloud add -var="project_id=<your project>"); passwords and keys are created by Terraform and read with terraform output -raw <name>, they are never in the file.
- Authentication with Amazon Web Services (Cognito) (setup and enrollment): the user pool, its sign-in pages and the app client with the addresses listed. Type the outputs client_id and authority in Client id and Authority (address of the issuer). Google has no way to create its OAuth client from a file: create it in the Google Cloud console as explained above.
- Logs with Amazon CloudWatch or Google Cloud Logging (setup, enrollment, Logs pages): where the logs, traces and metrics land and the key of the collector. The output collector_config is the configuration of the OpenTelemetry Collector; type the address of that collector in the step.
- Database of a tenant, Where is it hosted? = Amazon Web Services or Google Cloud: a SQL Server Express or PostgreSQL server (Amazon RDS, Cloud SQL) that only the addresses you give (allowed_cidr, the outbound address of the API) can reach. Paste the output connection_string in Connection string, then create the database.
- File storage of a tenant on AWS or Google Cloud: the private bucket and the key that reaches it. The outputs give the address, the bucket, the access key and the secret to type in the step.
2. Emails of the platform (optional)
SerenForce sends a few emails itself: the invitations of the people of a new tenant and the confirmation of a sign-up. They are not the emails of the process steps (those leave from the mailbox of the person who runs the step). The second step of the setup, Email, chooses which service sends them; leave Decide later if you are not ready, and choose it later on the Email page of the administration, where you can also test it at any time. That page offers the same guided stages for Microsoft 365 (create the application sp-sf-catalog-email-prod now, download its script or use an application that exists); then press Save.
- Sending service: Microsoft 365 (the emails leave from a mailbox of your company, such as noreply@yourcompany.com) or Resend. Until you choose one, the Resend key and sender of the settings of the deployment are used, if there are any.
- With Microsoft 365, the screen guides you in three numbered stages: Connect to Azure (pick New or existing application, sign in to Azure and press Create the application: SerenForce registers it, grants the permission and fills the next stage for you), Mailbox and credentials (check them, and type the sender mailbox) and Check that it works (send yourself a test email). If you prefer to do it by hand, the steps are these. SerenForce signs in as an application of Microsoft Entra ID and sends from the mailbox you name. Do this once, in the Azure portal: register an application (App registrations › New registration); in API permissions add Microsoft Graph › Application permissions › Mail.Send and press Grant admin consent; in Certificates & secrets create a client secret and copy its value right away. This application is not the one of the sign-in: create another one.
- Let SerenForce create that application. Below the fields, Create the application that sends the emails: with Create it now, with access to Azure choose how SerenForce signs in to Azure (the same choices as the first step) and press Create the application: the application gets the Mail.Send permission, a client secret valid one year, and its identifiers fill the fields. If you see that an administrator still has to grant the permission, a Global Administrator does it in the portal (API permissions › Grant admin consent). With Generate a script and type its results here, download a Bicep file, ARM template or Terraform file, run it, then type the identifiers and the secret yourself (Bicep and ARM give the command that creates the secret; Terraform gives the secret as an output). Or choose Use an application that exists: Find the existing ones lists the applications of your directory that may send mail, you choose one and SerenForce adds a new secret to it (the secret of an existing application cannot be read) and fills the fields. Nothing is kept until you press Save the email service.
- Then type: Sender mailbox (the address only, without a name), Directory (tenant) (the ID or the domain of your directory), Application (client) ID and Client secret. The secret is kept in the catalog and is never shown again: on the Email page, leave the field blank to keep it.
- Limit what the application can do. Mail.Send as an application lets it send as any mailbox of your directory. Ask your Exchange administrator for an application access policy (
New-ApplicationAccessPolicy, or RBAC for Applications) that restricts it to the one mailbox. - With Resend: Sender is an address on a domain verified in Resend (with or without a name, such as SerenForce <hello@yourcompany.com>) and Resend API key the key created in Resend.
- Test recipient and Send a test email send a message with the settings you typed, without saving them, and tell you what the service answered when it refuses (wrong secret, missing consent, unknown mailbox…).
A tenant can have its own service: at the Email step of its enrollment, Emails about this tenant chooses it (for example the Microsoft 365 of its company). With Decide later, the service of the platform sends them. You can choose or change it later in the Email tab of the tenant page. In both places, Microsoft 365 offers the same three stages as here: create the application now with access to Azure, download its script (Bicep, ARM or Terraform) or use an application that exists; the application proposed is named sp-sf-<tenant>-email-prod. In the tab, press Save the email service to keep the result.
3. Cache of the platform (optional)
The catalog reads the tenant of every request. A cache keeps it for a few minutes instead of reading the database each time. This step is optional: Memory (each instance has its own) is the default and enough with a single instance.
- Memory (each instance has its own): nothing to set up. Each instance of the application keeps what it has read in its own memory.
- Redis (shared by all the instances): use it when the application runs on several instances. What one instance has read, the others find it, and the memory of each instance stays in front of the Redis. Choose Where does the Redis run?: A Redis server (your own), Azure Cache for Redis, Amazon ElastiCache (Redis OSS or Valkey) or Google Cloud Memorystore for Redis; the choice only changes the example and the hint under Redis connection, all of them are used the same way. Type the connection (address and port, then options separated by commas, for example password=… and ssl=True when the server uses TLS) and press Test the connection: SerenForce writes then reads a value in the server and tells what it answered. The application must be able to reach the server (firewall, private network). The connection, password included, is kept in the catalog.
- No cache: nothing is kept, every request reads the database. Slower, but there is nothing to keep in step.
- With Azure Cache for Redis, Use an Azure Cache for Redis that exists asks for the subscription and an Azure access that can list the keys of the cache (Contributor), lists the caches found and fills Redis connection and Access key (optional) with the one you choose.
The connection, password included, is kept in the catalog; Access key (optional) holds the key when it is not already in the connection (password=…). A tenant has its own Cache step in its enrollment, with the same choices.
4. Logs (optional)
By default the logs of the application stay in its console and its files. This step sends them to the monitoring service you use, through OpenTelemetry. It is optional: leave No service if you are not ready.
The service of the platform also receives the traces (each request the application answers, with the calls and the database queries it made, and how long each took) and the metrics (number of requests, response times, errors, memory). They tell what was slow or failed, and the logs written during a request are linked to its trace. A request of a tenant carries the identifier of the tenant, so you can filter by tenant. The traces and the metrics only go to the service of the platform, never to the service of a tenant.
- Azure Application Insights: paste the connection string of the resource (InstrumentationKey=…;IngestionEndpoint=…); no key is needed. Or let SerenForce create it: Create Application Insights asks for the subscription (already filled with the one SerenForce runs in when it runs in Azure), the resource group, the region and a name, creates the resource and its Log Analytics resource with the Azure access you choose (the same choices as the first step) and fills the connection string; Use one that exists lists the Application Insights of a subscription (the access only needs the Reader role) and fills the connection string with the one you choose; Download the Bicep file gives the same resources to create yourself, and the connection string is an output of the file. The Azure group of the Application Insights and Application Insights resource fields (optional) are filled in when you create it or choose an existing one; you can also type them, and they are shown again when you come back to this step.
- Datadog, Grafana (Loki), Dynatrace, SigNoz, Sentry: type the OTLP address of the service (the base address, without /v1/logs) and its key or token (Key or token): the Datadog API key, instance ID:token on Grafana Cloud, the Dynatrace API token with the logs.ingest, openTelemetryTrace.ingest and metrics.ingest scopes, the SigNoz ingestion key, the public key of the Sentry DSN. A self-hosted Loki or SigNoz needs no key.
- Amazon CloudWatch, Google Cloud Logging, Loggly, Exceptionless: these services do not take OpenTelemetry directly (AWS asks for signed calls, Google for a Google identity, the others have their own API). Run an OpenTelemetry Collector that forwards to them (the AWS Distro for OpenTelemetry on AWS, a collector with the Google exporter on Google Cloud) and type its OTLP address, usually http://collector:4318. An OpenTelemetry Collector is the same choice for any other OTLP endpoint.
- Service name (optional): the name the logs carry in the service; serenforce-api by default.
- Test the destination sends an empty request and tells whether the service answered or refused the key. Nothing is saved.
The key is kept in the catalog and never shown again. A tenant has its own Logs step in its enrollment, with the same choices: its logs then go to its own service, and without one they go where the platform's go. As soon as a service is chosen, the step proposes names made from the identifier of the tenant: Service name serenforce-<tenant>-api-prod and, for Application Insights, Application Insights name appi-sf-<tenant>-prod. They follow the identifier until you change them; a name you type is kept.
The enrollment of a tenant is kept as you go, except its secrets (passwords, keys, client secrets, Azure tokens), which are never saved: the steps that ask for them say so. If you refresh or leave the page, type them again; the step turns green again without a new test.
5. AI (optional)
The built-in assistant and the hooks in AI mode use an AI provider and one of its models. This step chooses those of the platform and their API key. It is optional: Decide later saves nothing, and each tenant then brings its own key.
- Choose a provider and a model: choose the AI provider (Anthropic (Claude) or Google (Gemini)), then the Model among the ones offered, and paste the key in API key. Press Save the AI.
- The key is kept in the secret store of the platform and never shown again: the step only says a key is saved. Leave the field empty to keep it; if you change the provider, type the key of the new one.
- No key goes in the Azure DevOps libraries: everything is set here, then in the administration.
A tenant has its own AI step in its enrollment: Use the AI of the catalog (the default) takes the provider, the model and the key chosen here; otherwise it chooses its provider and its model, and the API key used: The key of the catalog (only possible when the platform has a key for that provider) or Its own key (bring your own key), typed once and never kept in the enrollment in progress.
6. License of the catalog (required)
SerenForce sends a license key for each catalog (it starts with PN1.). It is issued for this installation only: the License step first shows the Installation ID, which you copy with its button and send to SerenForce to get the key. A key issued for another installation (for example the key of your production catalog pasted into a test catalog) is refused, and the message gives the ID to send. At the License step, paste it in License key and press Save the license. The page then shows what the license gives: its kind, the customer, the period and its id.
- SaaS: no seats and no end. An organization people create themselves pays its seats through its own subscription; the organization of a tenant you enroll yourself in the administration has every feature, with no plan to choose and no limit of members.
- Enterprise: a number of user seats for a period (for example one year), paid directly to SerenForce. Every organization of the catalog that has no subscription of its own uses these seats. The Extra services (AI) line says whether the AI is included: included, the company uses it with its own AI key; not included, it is refused.
A key is refused, with the reason, when it was not issued by SerenForce, was changed, was issued for another installation, has ended, or is a key issued for a tenant before November 2026 (those keys are no longer used). Until the setup is finished you can paste another key in Another license key (replaces the one above). The key itself is never kept in the setup in progress: only what it gives. The organizations you enroll afterwards need no license of their own.
Renew or replace the license
After the setup, the License of the catalog card of the dashboard of the administration shows the license and the Installation ID to give SerenForce for every new key, and warns when an Enterprise license ends within 30 days. Paste the new key SerenForce sends you in New license key and press Replace the license: the new license replaces the old one at once.
7. Encryption (optional)
SerenForce encrypts every secret it keeps, with one key per organization. This step comes after the license; your own key needs no license here (SaaS or Enterprise alike). At the Encryption step, answer the questions one at a time: With the root key of the installation (the Status page shows a warning) or With a key in a vault; then the vault (Azure Key Vault or Google Cloud KMS, AWS KMS is coming soon; Google Cloud KMS is chosen with a script or an existing key, and the service account shown must get the roles "Cloud KMS CryptoKey Encrypter/Decrypter" and "Cloud KMS Viewer" on the key); a new vault or an existing one, found in a list after Connect to Azure; in an existing vault, a new key or an existing one; last, for what is new, SerenForce creates it now or you run a script (Bicep, ARM or Terraform). The Check the key button verifies that everything works. Details: Encryption and your own key.
8. Sign in to the administration
Finish the setup is only possible when every step is done: the application registered, the email service saved (or Use the email service of the deployment), the cache saved, the logs saved (No service is a choice you save too), the AI saved (or Decide later) and the license of the catalog saved. The page lists the steps that are still to do. As soon as you press Finish the setup the platform is set up: every instance of the application notices within seconds, and nothing has to be copied anywhere (the catalog holds everything). The page shows a summary (name, address, identifiers, personal accounts) and a link to this guide; press Sign in to the administration and sign in with the application that was just registered.
The first person who signs in to the administration becomes the super administrator of the platform, so sign in right away with a work or school account of your directory. Once somebody did, nobody else becomes a super administrator by signing in. To be sure you pick the right account, the sign-in always asks which account to use after the setup, even if you are already signed in to Microsoft with another one.
A personal account as super administrator
The administration only accepts the accounts of the directory where its application is registered. A personal Microsoft account (Outlook, Hotmail, Live) that signs in directly is refused, even when Allow personal Microsoft accounts is on: that switch only opens the tenants to personal accounts. This keeps the administration, which controls every tenant, its databases and its secrets, behind your directory.
- Invite the account in your directory
In the Azure portal, Microsoft Entra ID › Users › New user › Invite external user: type the email of the personal account. The person accepts the invitation from the email they receive.
- Make it a super administrator
If nobody signed in to the administration yet, the guest can sign in first and becomes the super administrator. Otherwise a super administrator adds the person on the Users page of the administration (New user, with the email of the personal account and the SuperAdmin role).
- Sign in
The person signs in to the administration with their personal account: Microsoft lets them in as a guest of your directory.
After the setup
- Open the administration
When you press Sign in to the administration on the summary page, Microsoft asks you to sign in with the application that was just registered.
- Enroll the first tenant
No tenant is created automatically: on the dashboard, press Enroll a new tenant. The wizard first asks for the organization (Organization type: enterprise, government, non-profit, academic or other; Organization name; Allowed email domain, optional and limited to one domain for now, for example teqten.com; leave it empty to allow all domains), then for the identifier and the name of the tenant with its administrators (at least one), its database, its file storage, its authentication, its email service, its AI (see AI) and its administrators. For the database and the storage account you choose the provider, the region, the size and the names, then download or deploy the Bicep file, as here. A storage account created this way lets SerenForce reach the files of the tenant on its own, so no account key is needed: whoever creates it needs the Owner, User Access Administrator or Role Based Access Control Administrator role on the resource group. Azure can take a few minutes to apply this access; until then the creation of the tenant waits, then says so if it is still not there: try again a little later. The identifier and the sign-in application chosen during the setup are already filled in. You can close the wizard at any time: the enrollment is kept (except passwords and secrets) and appears in the Tenants page with the status Draft and the step where you stopped. Press Continue to go on at the step where you stopped, or Discard to abandon it (the database, the files and the application already created are not removed). At the Authentication step, the Microsoft Entra ID application of the tenant is chosen the way it is at setup: type the one that exists, Register the application in Microsoft Entra ID for me (with the identity of the application, a service principal or your own Azure account), or download a script (Bicep, ARM, Terraform or Azure CLI) and type the identifiers it gives. The Application name is proposed by the convention sp-sf-<tenant>-<environment> and can be changed in its box. Allow personal Microsoft accounts is chosen tenant by tenant, before the registration: it changes the application. The Advanced settings remain available for an application typed by hand. Secret lifetime works as in the setup: when SerenForce registers the application, it creates its client secret and fills it in with its Secret expiry date. If you type a secret yourself, also type its Secret expiry date.
- Choose the administrators of the tenant
The first step, under the name of the tenant, lets you invite the people of the tenant and choose the role of each one (Administrator, User or Viewer). At least one of them must be an administrator. You can invite yourself with Add myself. Each person receives an email with the link to sign in to the tenant, and receives the chosen role the first time they sign in with that email address. If an email cannot be sent (email service not configured or refused: see Emails of the platform), the tenant is created anyway and the screen tells you which people to warn yourself.
- No license for the tenant
The enrollment asks for no license key: the license is the one of the catalog (see License of the catalog), and the Authentication step is followed by the Email step. On a SaaS catalog, every organization pays its seats with its subscription; on an Enterprise catalog, it uses the seats of the license. For a tenant Shared between several organizations, you (the super administrator who enrolls it) are invited as one of its administrators.
- Invite the other users
They open the address of the application and type their email. With a personal account (if you allowed them), they enter an organization of the tenant: by invitation, by a request to join, or by taking out a Team subscription for a new organization. The Team plan signs up on the first enabled tenant that is Shared between several organizations and welcomes personal accounts; without one, the subscription page says the sign-up is not open yet. To make an existing tenant this one, open it from the Tenants page, turn on Shared between several organizations and Welcome personal Microsoft accounts, then press Save changes. When you turn on Shared between several organizations, a warning reminds you that the people of the other organizations sign in with their own directory: before saving, open the sign-in application of the tenant to them in Microsoft Entra ID (App registrations > Authentication, Supported account types set to Accounts in any organizational directory (Multitenant)), otherwise Microsoft refuses their sign-in.
Invite a person to a tenant again
An invitation link can expire, get lost or be opened by the wrong person. On the page of the tenant, open the Invitations tab (in the ⋮ menu at the end of the tabs when it does not fit on the row), type the Email of the person, choose their Role (Administrator, User or Viewer, User by default) then press Send the invitation. The person receives a new invitation email. On a tenant open to every directory (or shared between several organizations), this email holds a new personal link, valid once for 7 days, and the link sent before stops working; whoever opens it receives the role chosen here, which replaces the one of the previous invitation as long as nobody used it. If the email cannot be sent, the screen says so: the invitation is recorded anyway, check the email service (see Emails of the platform) then send it again. You can also invite a new person this way.
Time zone of a tenant
The dates SerenForce writes itself (end of an invitation link, renewal of the monthly tokens, end of a client secret, deletion date of the data of an organization, name of the process instances a routine starts) are given in the time zone of each person: the one of their browser, noted each time they open the application. An email always names the time zone, for example 18 November 2026 at 10:00 (Europe/Paris). For the people who have not opened the application yet, SerenForce uses the time zone of the tenant: the one of your browser when you enrolled it. Change it in the General tab of the tenant page, field Time zone, then Save changes; None (UTC) writes these dates in UTC.
Audit trail of a tenant
SerenForce keeps, for each tenant, what its users did: every change (creating, editing, deleting, sending), every download, every action refused because the person lacks a permission or that failed, and each time somebody opens the application. Plain page views are not kept. In the administration, open the tenant from the Tenants page, then its Audit trail tab.
- Choose how long it is kept
Keep the audit trail for offers 1 month (the default, as long as you choose nothing), 3 months, 6 months, 12 months or 24 months. Press Save the retention: it is saved on its own, not with the other tabs. Older lines are removed within the hour, for this tenant only.
- Read and search the audit trail
The most recent lines come first, 25 per page: When, the User (Removed user when the person no longer exists), the Action (what was asked and on which item), the Outcome (Succeeded, Denied or Failed), its Duration, the Correlation id and the Address (hover it to see the browser). Type in the search box a name, an email, an address or a correlation id; the filter icon of the When, Action and Outcome columns narrows the list to a period, a kind of action or an outcome. Clear the filters shows everything again.
- Troubleshoot a problem
When a user reports an error, find their line, then give the Correlation id to whoever reads the logs of the platform: the same id is on every log of that request.
Status of the platform
The Status page of the administration (Platform menu, super administrators only) tells whether the resources SerenForce needs answer: one line for the catalog, then one per tenant turned on, and one column per resource: Database, Files (the container, the bucket or the folder of the files), Cache (the Redis server) and Sign-in (the Microsoft Entra ID directory). A green dot: the resource answers; a red dot: it does not, point at it to read the message of the service (for example a database missing from its server); a dash: there is nothing to reach (a cache in memory, no files for the catalog, a Google or AWS sign-in). The Overall column sums up the line. Each resource has 10 seconds to answer; all the tenants are checked at the same time. Every visit checks again, and Refresh runs the check once more.
Permissions of the applications
Each time SerenForce registers an application in Microsoft Entra ID (or gives you the script to do it), the screen lists under Permissions given to the application what the application will be allowed to do. Delegated permissions act on behalf of the person who signs in; an Application permission acts with no person signed in.
- The application of the administration (first step of the setup): openid and offline_access to sign in and stay signed in, User.Read (delegated) to read the profile of the person who signs in, and the scope it exposes itself, api://<client id>/Read.All, used by the web application to call SerenForce.
- The application of a tenant (Authentication step of a new tenant): the same, plus these delegated permissions: User.ReadBasic.All (search the people of the directory to choose participants), GroupMember.Read.All (read the groups and their members), Mail.Read, Mail.Send and Mail.ReadWrite (read, send and write emails of the person who signs in) and Calendars.ReadWrite (create meetings in their calendar).
- The application that sends the emails (Email step, with Microsoft 365): only Mail.Send of type Application. An existing application you choose must have it too.
- Consent. Delegated permissions are consented once for the whole directory, so nobody is asked when they sign in: SerenForce does it when it registers the application, otherwise a Global Administrator presses Grant admin consent (Microsoft Entra ID > App registrations > API permissions). Mail.Send of type Application always needs a Global Administrator or a Privileged Role Administrator, and should be limited to the sender mailbox (see the Email step).
Online sign-up of organizations (self-service)
With the Pro and Business plans, a company signs up on its own at /app/subscribe/organization. This sign-up opens by itself once the platform is set up: there is nothing to configure.
Client secrets and their alerts
Each application (the one of the administration and the one of each tenant) gets a client secret. SerenForce uses it to search for people and groups in your directory, and to send emails and create meetings for your users. The secret stops working on its expiry date.
- When SerenForce registers the application, it creates the secret with the Secret lifetime you chose. It also asks for the Microsoft Graph permissions the application needs and grants the admin consent when your Azure access allows it. Otherwise the page tells you that a Global Administrator still has to grant it (Microsoft Entra ID > App registrations > API permissions).
- The Tenants page warns you before a secret expires. A badge next to the status of the tenant says Secret expires within a month, Secret expires within a week, Secret expires within a day, then Secret expired; hover over it to see the date. A banner above the list does the same for the secret of the administration application.
- Every week, SerenForce checks each secret with Microsoft Entra ID. A secret that was deleted, replaced or typed wrong is seen even before its expiry date: the badge then says Secret refused. The page of the tenant shows the same alert in a banner above its tabs, with the day of the last check.
- When a secret needs attention (it expires within a month, it expired, or it was refused), SerenForce sends an email to the super administrators of the platform and, for the secret of a tenant, to the administrators of that tenant, in their language (for a super administrator, the one of the last time they opened the administration; English until they open it). The email comes back every week until the secret is renewed.
- To renew a secret, create a new one in Microsoft Entra ID (App registrations > Certificates & secrets). Then type it in the Authentication tab of the tenant with its Secret expiry date and press Save changes. The alert goes away, and the new secret is checked within the hour.
- The secret of the administration application is renewed from the banner above the list of the Tenants page: press Renew the secret. Choose Let SerenForce create it now in Microsoft Entra ID: pick the Secret lifetime and how SerenForce signs in to Azure, then press Create the secret. The Azure access must be an owner of the application, or have the Application Administrator or Cloud Application Administrator role, or (for an application) the Application.ReadWrite.All permission of Microsoft Graph: the window lists these rights. Or choose Type a secret created in Microsoft Entra ID: create the secret in the portal, or with the Azure CLI command the window gives you (it keeps the current secrets working), then paste it into New secret value, give its Secret expiry date and press Save. Either way the secret is never shown again, the banner goes away and the new secret is checked within the hour. An administration that signs in with Google or AWS has no secret to renew here.
Good to know
- If the setup is interrupted (closed page, new deployment, another browser), open
/app/setupagain: the steps already done stay done. - The Microsoft Entra ID application stays in your directory (App registrations) if you delete the platform: delete it by hand.
- To start again, delete the catalog database and that application, restart the application (it creates the catalog again when it starts), then open
/app/setup.