InTouch Hub · Blue Isle Software

Microsoft 365 Licences

Read Microsoft 365 subscriptions, seat counts and per-user licence assignment through Microsoft Graph.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

identitymsgraphschedulestatus

Microsoft 365 Licences Tool

Read Microsoft 365 subscriptions, seat counts and per-user licence assignment. This is the tool for what the organisation is paying for, how many seats are unused, and what an individual is licensed for.

Tool ID

msgraph-licenses

Credential Required

Yes — the shared msgraph credential, owned by the msgraph connector. Configure the tenant once and all nine tools use it; rotating the client secret is one edit rather than nine.

It is a server-managed OAuth credential: InTouch mints and refreshes the access token itself and the connector never sees the secret. For unattended work set grant_type to client_credentials (the app-only grant) — an app-only token belongs to the application, so a 06:00 schedule does not run as a person, see only what that person can see, and stop working the day they leave.

Credential Properties

Property Type Default Description
client_id string — Required. The Entra app registration's Application (client) ID.
client_secret string — Required for app-only. The secret's Value, not its Secret ID.
token_url string — Required. https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
grant_type string (blank) client_credentials for unattended app-only use. Blank means the user-delegated refresh-token flow.
scope string — https://graph.microsoft.com/.default — resolves to whatever application permissions an admin has consented to.
access_token string — Machine-managed. Leave empty; the server mints and persists it.
refresh_token string — Delegated credentials only. Not used by the app-only grant.
expires_at string 0 Machine-managed expiry, epoch seconds.

Entra setup

  1. https://entra.microsoft.com → App registrations → your app → API permissions.
  2. Add a permission → Microsoft Graph → Application permissions — not Delegated. Picking Delegated is the most common failure: it consents cleanly and then 403s at runtime.
  3. Tick the permissions listed under Permissions below, then Grant admin consent. The Status column must read Granted.
  4. Permissions live in the token, not the portal. A token minted before the grant carries the old claims for about an hour — blank access_token to force a fresh mint.

Permissions

Organization.Read.All — and Directory.Read.All also covers it, so on a tenant where msgraph-identity already works this connector needs no additional consent.

Operations

1. list_subscribed_skus — List subscriptions

Every subscription the tenant owns, with prepaid and consumed seat counts. Calls GET /subscribedSkus.

Properties:

Property Type Default Description
operation string — Required. list_subscribed_skus
query string — Optional. OData query params as a JSON object string — e.g. {"$select": "skuPartNumber,prepaidUnits,consumedUnits"} to return just the seat counts.

Published Outputs: - result — the JSON response body - status — HTTP status code

2. get_subscribed_sku — Get one subscription

One subscription by id, for a report that already knows which product it is asking about. Calls GET /subscribedSkus/{id}.

Properties:

Property Type Default Description
operation string — Required. get_subscribed_sku
id string — Required. Subscribed-SKU id for get_subscribed_sku, or a user id / userPrincipalName (e.g. [email protected]) for get_user_licenses.
query string — Optional. OData query params as a JSON object string — e.g. {"$select": "skuPartNumber,prepaidUnits,consumedUnits"} to return just the seat counts.

Published Outputs: - result — the JSON response body - status — HTTP status code

3. get_user_licenses — Get a user's licences

What one person is assigned, resolved to service-plan level rather than raw GUIDs. Calls GET /users/{id}/licenseDetails.

Properties:

Property Type Default Description
operation string — Required. get_user_licenses
id string — Required. Subscribed-SKU id for get_subscribed_sku, or a user id / userPrincipalName (e.g. [email protected]) for get_user_licenses.
query string — Optional. OData query params as a JSON object string — e.g. {"$select": "skuPartNumber,prepaidUnits,consumedUnits"} to return just the seat counts.

Published Outputs: - result — the JSON response body - status — HTTP status code

Paging

Graph answers a collection with 100 rows and an @odata.nextLink, so a naive listing returns a fraction of a large tenant with HTTP 200 and no sign anything is missing. This connector follows the continuation link until the collection is exhausted. If it stops at the page cap it says so — the result carries complete: false with a warning, and the step returns WARNING rather than SUCCESS. A page cap must never look like the end of the data.

Notes

The number people actually want is a subtraction. list_subscribed_skus returns prepaidUnits.enabled (seats bought) and consumedUnits (seats assigned). Unused seats are the difference, and Graph does not return it — a spend review computes it.

skuPartNumber (ENTERPRISEPACK) is the human-readable half and is what a report should print; the GUID is what assignedLicenses matches on. Both come back.

Self-Contained JAR

The jar bundles all runtime dependencies; only intouch-tool-api is provided by the server.

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.