Azure (Entra ID) OAuth2 Integration

This document describes the OAuth2 integration that allows enterprise users to sign in to InStore with single sign-on (SSO) through Azure Active Directory / Entra ID, along with the required configuration.

How It Works

When a user selects "Sign in with Azure" in InStore, the standard OAuth2 Authorization Code flow is executed:

1. Redirect — The user is redirected to the Azure sign-in screen.
2. Authentication — The user signs in with their corporate Azure account.
3. Callback — Azure returns the user to the configured address with an authorization code.
4. Token exchange — InStore securely exchanges this code with Azure to obtain an access token.
5. User info — The user's email, first/last name, and store information are retrieved from Azure.
6. Mapping & sign-in — The user is mapped to the relevant store(s) in InStore, the staff record is created/updated, and the session is opened.

User                 InStore                    Azure Entra ID
   │                    │                            │
   │  Sign in w/ Azure  │                            │
   ├───────────────────▶│                            │
   │        Redirect to Azure login screen           │
   │◀────────────────────────────────────────────────
   │            Sign in with corporate account       │
   ├────────────────────────────────────────────────▶│
   │        Callback with code                        │
   │◀────────────────────────────────────────────────
   │                    │  Code → token exchange     │
   │                    ├───────────────────────────▶│
   │                    │  User info                  │
   │                    ├───────────────────────────▶│
   │   Sign-in success  │  Store mapping + session    │
   │◀───────────────────┤                            │

What to Do on the Azure Side

An application registration is created via Azure Portal → Entra ID → App registrations → New registration, and the following details are prepared:

Step	Description
App registration	A new App Registration is created for InStore.
Redirect URI	InStore's post-login return address is added as Web type (must match exactly the address configured on the InStore side).
Client secret	A client secret is generated under "Certificates & secrets".
API permissions	Microsoft Graph → User.Read (read user profile).
User attributes	Email, first/last name, employee ID, and store information attributes must be populated in the directory.

Once the registration is complete, note the following values to enter into InStore: Application (client) ID, Directory (tenant) ID, and the client secret.

Configuration on the InStore Side

The following fields are entered for the Azure provider from the InStore management screen:

Field	Description	Example / Value
Name	Provider name shown to the user	Azure
Slug	Provider identifier	azure
Provider type	Type of service to connect to	azure
Icon	Logo on the login screen (png/jpg, max 128×128)	Company logo
Client ID	Azure Application (client) ID	GUID
Client Secret	Azure client secret (stored encrypted)	—
Authorization URL	Azure authorization endpoint	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?...
Token URL	Token exchange endpoint	https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Userinfo URL	User info endpoint (Microsoft Graph)	https://graph.microsoft.com/v1.0/me?$select=mail,givenName,surname,employeeId,onPremisesExtensionAttributes
Redirect URL	Post-login return address (same as registered in Azure)	https://<instore-address>/oauth/azure/callback
Is active	Whether the provider is in use	true

Replace {tenant} with the Directory (tenant) ID obtained from Azure. The Client Secret is stored encrypted in InStore and is not shown back in the interface.

User and Store Mapping

Below is an example response returned by Azure to the Userinfo URL (Microsoft Graph /me) call — the fields are limited by the $select in the configuration:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(mail,givenName,surname,employeeId,onPremisesExtensionAttributes)/$entity",
  "id": "8f4e2c1a-3b7d-4e9f-a1c2-5d6e7f8a9b0c",
  "mail": "[e-mail]",
  "givenName": "Ayşe",
  "surname": "Yılmaz",
  "employeeId": "10457",
  "onPremisesExtensionAttributes": {
    "extensionAttribute1": "IST001,IST002",
    "extensionAttribute2": null,
    "extensionAttribute3": null,
    "extensionAttribute4": null,
    "extensionAttribute5": null,
    "extensionAttribute6": null,
    "extensionAttribute7": null,
    "extensionAttribute8": null,
    "extensionAttribute9": null,
    "extensionAttribute10": null,
    "extensionAttribute11": null,
    "extensionAttribute12": null,
    "extensionAttribute13": null,
    "extensionAttribute14": null,
    "extensionAttribute15": null
  }
}

Store (ERP) codes are kept as a comma-separated list in the extension attribute configured in the directory (extensionAttribute1 in the example above).

The fields in this response are mapped to the InStore staff record as follows:

InStore data	Source in Azure
Email	User email (mail)
First name	givenName
Last name	surname
Employee ID	employeeId
Store(s)	Extension attribute — comma-separated store (ERP) codes

Mapping Rules

• Store codes are matched against store records in InStore. If no matching store is found, sign-in is rejected.
• If a staff member already exists with the email, their store assignments are updated; otherwise a new staff record is created with the default permission group.
• If the user is assigned to more than one store, the active store selection is managed through the InStore session, and all subsequent operations run in the context of the selected store (SSO continuity).

Summary

• Enterprise users sign in to InStore with a single click using their Azure accounts.
• Passwords are not stored in InStore; authentication is handled entirely by Azure.
• User and store mapping is performed automatically.
• Setup is one-time: an app registration in Azure + provider configuration in InStore.