Set up Microsoft 365 sign-in

For: the Microsoft 365 administrator of a sota Enterprise customer. Time: about 15 minutes. Result: your employees sign in to your sota apps with their normal Microsoft 365 account. Nobody outside your organisation gets in.

For now sota does this set-up together with you. A guided set-up in the sota dashboard comes next.

How it works

You create one app registration in Microsoft Entra ID (the identity part of Microsoft 365). It tells Microsoft that the sota sign-in service may ask your users to sign in, and where to send them back. sota receives only what it needs to recognise a person: their internal ID, name and e-mail address. sota never sees passwords and cannot read mail, files or anything else in your Microsoft 365. Who may open which app is decided by you in the sota dashboard.

Before you start

  • You need an account that may create app registrations and grant admin consent. Global Administrator always works; Cloud Application Administrator or Application Administrator is enough.
  • Open the Microsoft Entra admin center: entra.microsoft.com. If you manage several tenants, check the tenant name in the top right corner.

Labels are the English ones; German labels are shown in [brackets] where we are sure of them.

Step 1: Create the app registration

  1. Go to Entra ID → App registrations [App-Registrierungen]. Older menus: Identity → Applications → App registrations.

  2. Click New registration [Neue Registrierung].

  3. Name: sota Access. Your employees may see this name on Microsoft's sign-in page.

  4. Supported account types: the single-tenant option, called Single tenant only or Accounts in this organizational directory only [Nur Konten in diesem Organisationsverzeichnis]. Do not pick a "multiple tenants" or "personal Microsoft accounts" option: sota accepts sign-ins from your own tenant only.

  5. Redirect URI: platform Web (not "Single-page application"), URI:

    https://access.sota.io/oidc/callback
    
  6. Click Register [Registrieren].

On the Authentication page leave everything else as it is: no implicit-grant tokens, no front-channel logout URL, public client flows No.

Step 2: Copy the two IDs

On the app's Overview [Übersicht] page copy the Application (client) ID and the Directory (tenant) ID. Both look like 00000000-0000-0000-0000-000000000000. Copy the IDs, not the domain name.

Step 3: Create the client secret

  1. Open Certificates & secrets → Client secrets → New client secret.
  2. Description sota Access; Expires: the longest your policy allows (Microsoft allows up to 24 months). Write down the expiry date.
  3. Click Add and copy the Value column right away; Microsoft shows it only once. Do not copy the Secret ID: it does not work as a password.

sota asks for exactly three standard sign-in permissions: openid, profile and email.

  1. Open API permissions. Leave Microsoft Graph → User.Read, which Microsoft adds by itself.
  2. Add a permission → Microsoft Graph → Delegated permissions → under OpenId permissions tick email, openid, profile → Add permissions.
  3. Click Grant admin consent for <your organisation> and confirm. After Refresh, every line shows Granted.

Without admin consent each employee would see a "Permissions requested" screen on first sign-in, and in many organisations they are not allowed to accept it.

Open Token configuration → Add optional claim → token type ID → tick email → Add (confirm the Graph permission if asked). sota does not use group or role claims: access is decided in the sota dashboard. If a user has no e-mail address in Entra, sota shows their sign-in name.

Step 6: Who may sign in (leave as it is)

By default every member of your organisation can start the sign-in. That is what sota expects: a new person appears in your sota dashboard as a request, and nobody gets into an app before you approve them. Guests invited into your tenant can sign in too and arrive as requests like everyone else.

If you want Microsoft itself to stop everyone except chosen people, set Enterprise apps → sota Access → Properties → Assignment required? to Yes and assign those people. Everyone else then gets a Microsoft error page instead of the request page.

Hand the values to sota

ValueWhere it is
Directory (tenant) IDapp → Overview
Application (client) IDapp → Overview
Client secret ValueStep 3 (shown once)
Secret expiry dateapp → Certificates & secrets
Primary domainEntra ID → Overview

The two IDs and the domain are not secret. The client secret never goes into e-mail or chat: we agree a secure way to hand it over with you. sota stores it encrypted and never shows it again.

Test

sota sends you a test link. Use two people of your organisation and a private browser window for each:

  1. Person A signs in and sees "Request sent". You approve A and grant one app; A opens it and gets in.
  2. Person B signs in and is not approved. B must never see the app.

When something goes wrong

Microsoft showsCauseFix
AADSTS50011 redirect URI does not matchRedirect URI missing, mistyped or on the wrong platformAuthentication → Web must list exactly https://access.sota.io/oidc/callback
AADSTS65001 / AADSTS90094 need admin approvalAdmin consent missingStep 4, item 3
AADSTS50020 user does not exist in tenantPerson from another organisation, or app in the wrong tenantCheck the tenant ID; invite outside people as guests
AADSTS700016 application not foundClient ID and tenant ID from different tenants, or swappedCopy both again from the same Overview page
sota page "Sign-in failed"Secret copied wrong, deleted or expiredCreate a new secret and hand over the new value; delete the old one after sota confirms
AADSTS50105 not assigned to a roleAssignment required? is on and the person is not assignedAssign the person, or set it back to No

Before the secret expires, create a new one about a month ahead and hand it over; remove the old one after sota has switched.

Signing out

Apps can link to /.sota/access/logout (see identity headers). It ends the sota session and then the Microsoft sign-in in that browser. Nothing needs to be configured in Entra for this.