quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Developer’s guide

21. Give applications and people the right identity

An app registration describes a client or API. Its service principal is the application's identity inside the local tenant. A managed identity is a service principal whose credentials the hosting environment supplies. A user is a person who can authenticate interactively. A group connects a set of users to grants. AAD, Azure AD and Microsoft Entra ID are names for the identity technology; they do not describe three separate databases in Quinzee.

Use a fresh development group and synthetic accounts in this lesson. Start with the bootstrap identity to register and assign objects, then run the application with the restricted identity you created. Keep those two roles separate.

Manage identities in QHQ

Connect QHQ with your environment's bootstrap credentials. Expand Azure / Entra ID in the navigation. Every form uses the same public HTTPS APIs as clients. Use Browse to select an object, then Create / Edit to change it. Save updates the selection; Create makes a new object. Deleting requires the confirmation checkbox. Refresh after changing records through another client.

  1. In Users, enter a display name, username such as alice@example.test, and a password of at least 12 characters; choose Create. Select a user to rename, enable/disable, reset the password or delete it. Password input clears after submission.
  2. In Groups, create a security group with a display name and stable group account name. Select it, open Members, choose a user or group, and use Add member or Remove member. Browse shows the current member IDs. Cycles are rejected.
  3. In App registrations, create a display name and exact redirect URI. Select Public client for an interactive client without a secret. Select Expose API for an API that will issue application roles. The local Application enabled switch controls this emulator's sign-in policy.
  4. Select a registration and open Credentials to add a secret. Copy the one-time value into private application configuration; it cannot be retrieved later. Refresh lists credential IDs for removal. Public clients need no secret.
  5. In Enterprise applications, choose the app registration and create its service principal. This is the tenant identity used for assignments. Select it to edit its display name, sign-in status or Require an app role assignment.
  6. In App roles, choose a registration in Browse, then define a role in Create / Edit, for example Orders.Read. Choose whether users/groups, applications, or both may receive it. Disable a role and remove its assignments before deleting the definition.
  7. In App role assignments, choose the target Enterprise application in Browse. In Create / Edit choose a user, group or service principal and role, then Create. Group assignments grant roles to direct user members only; nested membership does not grant application roles.

Under Azure / Resource access, Managed identities creates standalone user-assigned identities in a resource group. Role assignments assigns a resource role at the entered subscription, resource-group or resource scope. Choose a principal and role, then Create. Group-based RBAC includes nested user membership. App roles and Azure resource roles are independent; neither grants directory administration.

Under Windows / Directory, LDAP directory shows the shared backend and listener status and links to the same Users and Groups. LDAP clients can use the POSIX view or the Windows-oriented user/group view. This module does not implement Windows domain join or Kerberos. Configure PostgreSQL and OpenLDAP using the instructions below before connecting LDAP clients.

Emulator → Modules lists each Azure/Windows frontend separately, including its dependencies. Unloading a frontend preserves records in the shared identity authority. The labels describe the API family; they do not indicate a connection to a Microsoft cloud tenant. Full cloud integration remains separate work.

QHQ app registrations and Azure identity navigation

QHQ shared user editing form

Captured from a disposable HTTPS test environment. The accounts and IDs are synthetic. Scroll the form to reach additional actions below the visible area.

Step 1: understand the IDs before writing code

Creating /v1.0/applications returns id and appId. Use id when editing the registration and appId as the OAuth client ID. Creating its service principal returns another id: assign Azure roles and application permissions to that principal ID. Display names are labels and need not be unique. Resource IDs, object IDs and client IDs are not interchangeable.

The native HTTPS /v1.0 directory API requires a token for https://graph.microsoft.com/.default. An ARM call requires https://management.azure.com/.default. Graph-shaped management is exposed at the local native origin; this does not add graph.microsoft.com DNS interception. QHQ's forms already select the correct audience for you.

To automate registration, POST the following JSON bodies to the named paths, using a Graph-audience administrator bearer token and verified HTTPS:

{ "displayName": "Orders worker" }

Send that to /v1.0/applications, then use its appId:

{ "appId": "<returned-client-id>" }

Send the second body to /v1.0/servicePrincipals. POST {} to /v1.0/applications/<registration-id>/addPassword; store the returned secretText privately immediately. GET later exposes only credential key IDs. A public interactive application uses isFallbackPublicClient: true and needs no secret. For browser authorization code flow also register its exact web.redirectUris; for device code, no callback URI is needed.

Step 2: give the identity a resource permission

At the intended group scope, PUT a UUID-named role assignment using API 2022-04-01. The complete resource body for Reader is:

{
  "properties": {
    "principalId": "<user-or-service-principal-object-id>",
    "roleDefinitionId": "/subscriptions/<subscription-id>/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7"
  }
}

The path is <group-resource-id>/providers/Microsoft.Authorization/roleAssignments/<assignment-uuid>. Save that UUID for redeployment; another UUID creates another assignment attempt, not an update to the original identity. The IaC hosting lesson gives the complete Bicep/ARM version. Reader permits resource reads, Contributor permits resource changes, and Owner additionally permits role assignment changes. Service Bus Data Sender/Receiver/Owner are separate messaging grants. New identities without an applicable role are denied. None of these resource roles grants directory administrator access.

Step 3: sign a person in using MSAL device code

Create a public registration and local user in QHQ. Give the user Reader on your training group. A new user's password is 12–1,024 bytes; there is no default human password. Save a private login.json with your values:

{
  "origin": "https://localhost:11443",
  "tenantId": "<local-tenant-uuid>",
  "clientId": "<public-application-client-id>",
  "groupId": "/subscriptions/<subscription-id>/resourceGroups/book-iac"
}

Prepare an isolated .NET 10 console project on the host. Reuse the exact verified MSAL dependency and lock, then place the complete code below in Program.cs:

mkdir -p .local/book-login
cp tests/compatibility/identity/IdentitySmoke.csproj .local/book-login/BookLogin.csproj
cp tests/compatibility/identity/packages.lock.json .local/book-login/packages.lock.json
using Microsoft.Identity.Client;
using System.Text.Json;

using var document = JsonDocument.Parse(await File.ReadAllTextAsync(args[0]));
var settings = document.RootElement;
string Read(string key) => settings.GetProperty(key).GetString()!;
var client = PublicClientApplicationBuilder.Create(Read("clientId"))
    .WithAuthority(new Uri(Read("origin") + "/" + Read("tenantId")), false)
    .WithInstanceDiscovery(false)
    .Build();
var scopes = new[] { "https://management.azure.com/.default" };
using var timeout = new CancellationTokenSource(TimeSpan.FromMinutes(5));
var result = await client.AcquireTokenWithDeviceCode(scopes, code =>
{
    Console.WriteLine(code.Message);
    return Task.CompletedTask;
}).ExecuteAsync(timeout.Token);
using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get,
    Read("origin") + Read("groupId") + "?api-version=2023-05-01");
request.Headers.Authorization = new("Bearer", result.AccessToken);
using var response = await http.SendAsync(request, timeout.Token);
response.EnsureSuccessStatusCode();
Console.WriteLine("Signed in as " + result.Account.Username);
Console.WriteLine("The assigned resource group is readable.");
// The SDK cache is process-local here. Do not print or persist access tokens.

Build with the local dependency cache, then run with the native development root trusted for this process:

DOTNET_CLI_HOME="$PWD/.packages/dotnet-home" \
NUGET_PACKAGES="$PWD/.packages/nuget" \
  dotnet build .local/book-login/BookLogin.csproj --property:RestoreLockedMode=true
SSL_CERT_FILE="$PWD/.local/certificates/ca/quinzee-dev-root-ca.crt" \
  dotnet run --no-build --project .local/book-login/BookLogin.csproj \
  -- "$PWD/.local/book-login/login.json"

Open the printed local verification URL in a browser that trusts this lab's public development root. Check the application name and code, sign in as the new user and approve. The program should print the username and confirmation that the group is readable. It does not print the token. MSAL handles polling, expiry and token acquisition; the application uses the returned access token only for the intended resource API. Do not approve a device code supplied by someone else. Instance discovery is disabled because this is a private local authority, while normal TLS verification remains enabled.

For browser code flow, use S256 PKCE, state and an exact redirect URI. MSAL's interactive acquisition handles those protocol pieces. make identity-sdk-test verifies the real browser flow, refresh rotation and Reader restrictions in an isolated environment. MFA, federation, Conditional Access and Azure CLI login are not implemented by the local authority.

Step 4: use one group for LDAP visibility and application roles

Create an Engineering group, add your user as a direct member, and create an Orders API registration with Expose API selected. Define an app role with value Orders.Read, allow Users, create the API's Enterprise application and set assignment required. Assign Engineering to Orders.Read.

The equivalent registration PATCH body is:

{
  "identifierUris": ["api://<api-client-id>"],
  "appRoles": [{
    "id": "<new-role-uuid>", "displayName": "Read orders",
    "description": "Read application orders", "value": "Orders.Read",
    "isEnabled": true, "allowedMemberTypes": ["User"]
  }]
}

POST an assignment to /v1.0/servicePrincipals/<api-principal-id>/appRoleAssignedTo:

{
  "principalId": "<engineering-group-id>",
  "resourceId": "<api-principal-id>",
  "appRoleId": "<role-uuid>"
}

Request api://<api-client-id>/.default. Its v2 token audience is the API's client ID and its roles claim contains Orders.Read. The API must validate signature, issuer, audience, lifetime and the required role before reading orders. A group app-role grant applies only to direct user members; nested groups do not convey it. Azure resource RBAC uses transitive group membership, so do not use the two permission models interchangeably. Removing a grant affects newly issued tokens; an already-issued external API token can remain valid until expiry.

When your administrator has enabled the shared PostgreSQL/LDAPS service, inspect the same group with an LDAP client:

LDAPTLS_CACERT=/absolute/path/to/lab-ca.crt ldapsearch -LLL -x \
  -H ldaps://127.0.0.1:11636 \
  -D 'uid=alice@example.test,ou=users,dc=quinzee,dc=cloud' -W \
  -b 'ou=windows,dc=quinzee,dc=cloud' '(objectClass=group)' \
  cn member memberOf objectGUID sAMAccountName

Use the actual account you created, its password prompt and the certificate's matching address. LDAP and the HTTPS directory share the record; no synchronization step is needed. This Windows-oriented view is read-only and supports nested member DNs. The POSIX view retains direct memberUid values. There is no Kerberos, Windows domain join or LDAP write API. LDAP lookup does not grant an app role; it only exposes directory membership.

Give a Function its own identity

Deploy identity: { type: 'SystemAssigned' } on a site, or create and attach a user-assigned identity. Assign the appropriate Service Bus role to its principal. For a binding named ServiceBusConnection use these app settings:

ServiceBusConnection__fullyQualifiedNamespace=booklab-bus.servicebus.quinzee.cloud
ServiceBusConnection__credential=managedidentity
ServiceBusConnection__clientId=<user-assigned-client-id>

Omit clientId for the system identity. The helper supplies IDENTITY_ENDPOINT and IDENTITY_HEADER privately. Do not set them yourself or expose tokens through a public web route. make functions-identity-test verifies a real queue trigger with SAS disabled. The complete identity-hosting IaC lesson explains each resource and permission. Managed identities cannot bind to LDAP with a password.

Clean up the identities you created

Remove application-role and resource-role assignments first, then delete the training user/group or application through QHQ. Disable and unassign a role before deleting its definition. Delete disposable client secrets by key ID. System identities disappear with their site; user-assigned resources survive until explicitly deleted. Keep the bootstrap identity for administration and avoid deleting unrelated records merely because their display names resemble the exercise's names.