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.

⏱ 10 minutes📍 Page /app/setup✅ Prerequisites: a SQL Server or PostgreSQL database server for the catalog (its connection string is in the settings of the deployment), an account that can register applications in Microsoft Entra ID, and access to the settings of the deployment

Before you start

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.

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.

  1. Download the script

    Choose the Script format (Bicep, ARM template (JSON) or Terraform), then press Download the script.

  2. 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, then az deployment group create --resource-group serenforce-setup --template-file serenforce-entra.bicep (or serenforce-entra.json), then run the command given by the output identifierUriCommand. Terraform: terraform init, then terraform apply in the folder of serenforce-entra.tf.

  3. 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.

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.

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.

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.

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.

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.

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.

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.

  1. 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.

  2. 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).

  3. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  1. 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.

  2. 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.

  3. 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.

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.

Good to know