Appearance
Microsoft 365
Microsoft 365 connections register an existing Entra application and its certificate in Ordyn. You can verify the connection, renew its certificate, and link it to Ordyn tenants.
Create connections under Services → Microsoft 365 → Connections. Ordyn supports any number of Microsoft tenants, with one connection for each Microsoft tenant ID. Each connection can be linked to any number of Ordyn tenants, and each Ordyn tenant can have any number of connections.
Before you start
You need the Service Operator role in Ordyn, an active Edge service, and access to register an application and grant administrator consent in the Microsoft tenant.
The Microsoft 365 service client needs outbound access to its assigned Edge service, login.microsoftonline.com, and graph.microsoft.com. Public HTTPS ingress is not required. Microsoft sovereign clouds are not supported.
Install and enroll a service client
In Services → Microsoft 365 → Service clients, add a service client with a name and its assigned Edge service. Copy its ID for the deployment configuration.
Use the m365 folder from the Ordyn compose repository:
bash
if [ ! -d /opt/ordyn-compose/.git ]; then
git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add m365
cd m365
cp .env.example .envSet the two required values in .env:
dotenv
ORDYN_M365_EDGE_HOST=ordyn-edge.example.com
ORDYN_M365_SERVICE_CLIENT_ID=<service-client-id>Pull and verify the image:
bash
docker compose pull
python3 /opt/cosign-docker-verify/verify.pyContinue after successful image verification. Under Administration → Enrollment Tokens, create a Service client token for Microsoft 365, selecting the same Edge service and service client. See Enrollment Tokens.
Stop any running service, enroll its persistent state, then start it after enrollment succeeds:
bash
docker compose stop m365
printf '%s' '<enrollment-token>' | docker compose run --rm -T --no-deps m365 npm run enroll -- --token-stdin
docker compose up -d m365Confirm that its detail page shows an active connection and applied configuration. Keep the deployment's data volume when recreating the container.
The certificate used to enroll the service client is separate from the certificates uploaded to Microsoft. For service-client certificate renewal or recovery, stop the service and run the same enrollment command with a new token and --force. See service-client certificate renewal.
Register an application and connect a Microsoft tenant
- In the Microsoft Entra admin center, create an app registration for Accounts in this organizational directory only. A redirect URI is not required for this certificate-based connection.
- Record the Directory (tenant) ID, Application (client) ID, and the app registration's Object ID. Use the object ID from App registrations, not the enterprise application's object ID.
- Under the app registration's API permissions, add the Microsoft Graph application permission
Organization.Read.Alland grant administrator consent. This permission lets Ordyn verify the tenant's organization identity. See Microsoft's organization API permissions. - In Ordyn, add a Microsoft 365 connection with those three IDs and the enrolled service client.
- Open the connection and download its pending public certificate. Upload it under the Entra app registration's Certificates & secrets → Certificates. The private key stays in Ordyn and cannot be downloaded. See Microsoft's certificate upload instructions.
- Find the uploaded certificate's actual key ID in Entra. In the app manifest, this is the
keyIdof the matchingkeyCredentialsentry. Match the certificate using its thumbprint; the thumbprint itself is not the key ID. - Enter that key ID in Ordyn and confirm the upload. A successful verification shows Verified and the Microsoft organization name.
Application registration and initial certificate upload are manual. Ordyn does not require a separate onboarding application or a Microsoft sign-in flow. Automatic renewal uses the application's own existing valid certificate; Microsoft permits an application to roll its own keys without an additional application-management permission. See Microsoft's addKey requirements.
Link connections to Ordyn tenants
Open a tenant folder in Endpoints, select Microsoft 365, and link the required connections. Use the Service Operator role to manage links, with access to the tenant folder.
Tenant users with the Endpoint Viewer role can see linked connections, their status, and public certificate metadata. They cannot manage the shared connection or inspect its infrastructure details through the tenant view.
Unlinking a connection affects only that Ordyn tenant. It does not remove the Microsoft application or change the certificate used by other linked tenants.
Review and restore settings
Open Revisions on a service client or connection to review changes and restore earlier settings. See Configuration history for reviewing proposed changes and resolving conflicting edits.
Restoring settings preserves the connection's current certificates. Restoring a different application object ID requires verification again. Restoring a deleted connection generates a new setup certificate; upload and verify it before using the connection again.
Correct application or certificate identifiers
Service Operators can edit the application object ID or use Correct key ID for a certificate when the connection is idle or awaiting manual action. Check the app registration and match the certificate by thumbprint before entering a correction. The Microsoft tenant ID and a verified application client ID identify the connection and cannot be changed.
Verify the connection after saving a correction. Renewal and removal wait for successful verification. A paused operation remains available for manual reconciliation afterward. If the current certificate has expired, use manual recovery.
Verification confirms certificate authentication and the tenant's organization identity. It does not independently check the entered application object ID or certificate key ID.
Certificate renewal and recovery
Ordyn generates certificates valid for 180 days. It checks for renewal hourly, starting within 30 days of expiry. Renewal adds a replacement certificate, verifies authentication with it, and removes the previous certificate after a seven-day overlap. Keep the assigned service client online so renewal can complete.
Use Renew certificate to start renewal earlier. If the connection needs manual action, inspect the certificates in Entra before proceeding:
- For an uncertain certificate addition, find the pending certificate by thumbprint. Upload it only if absent, then confirm its actual key ID in Ordyn.
- For an uncertain removal, check the retiring certificate by thumbprint and key ID. Confirm that it is absent, or confirm that it is still present to retry removal.
- If the last usable certificate expires, use Prepare manual recovery, upload the generated public certificate, and confirm its key ID. If an expired pending certificate already exists, remove that specific certificate from Entra and confirm its removal before generating another.
When a removal is awaiting confirmation and the replacement has also expired, remove the retiring certificate manually, confirm its absence, then prepare manual recovery.
Disabled connections do not start or dispatch renewal work. Review their certificates before enabling them again.
Remove a connection
Unlink all Ordyn tenants and finish or reconcile any pending operation before deleting the connection. An assigned service client cannot be deleted until its connections are removed or reassigned.
Deleting an Ordyn connection does not delete the Entra application or remove its Microsoft permissions. Remove an unused app registration in Entra separately.