Connect Microsoft and Google

How a connection works

• Provider and mode. provider is microsoft or google. mode is own_app, your own Microsoft Entra app or Google service account, or screenrig_app, screenRIG's app, which a Microsoft 365 administrator or a Google account holder approves.
• Status. A connection waits in pending_consent until someone approves screenRIG's app. It is ready while it holds credentials the last attempt did not refuse, and error when Microsoft or Google refused them: last_error says why, and a later success returns it to ready. A throttle or an outage changes nothing.
• Secrets stay sealed. A secret, a key or a refresh token is never shown again. A read shows whether one is held and a hint: the last four characters of a Microsoft client secret, or the address of a Google service account.
• Test it. A test signs in and keeps the result. For Microsoft it also lists the Graph application permissions the sign-in carries.
• Change it. Changing an own app's credentials returns the connection to ready and clears its last error. A connection in screenRIG's app mode can only be renamed: ask for a new consent link to change who approved it.
• Delete it. A delete is refused (resource_conflict) while a source, a Power BI connection or a media sync account reads through the connection. It does not end the vendor's side: the tenant keeps screenRIG's app until an administrator removes it, and a Google account keeps its grant until its holder revokes it.
• Limit. An organization has up to 50 connections across its projects.

Your own app or screenRIG's app

Microsoft

Your own app

Register an app in the Microsoft Entra admin center, add a client secret (copy its value, not its ID), give the app the application permissions below and grant admin consent. Create the connection with the directory ID or primary domain as config.tenant_id (common, organizations and consumers are refused), the app's application ID as config.client_id and the client secret value as secret.

screenRIG's app, with admin consent

Create the connection in mode screenrig_app, with no settings and no secret. The answer carries consent_url, a one-time link that works for 24 hours. Send it to a Microsoft 365 administrator and nobody else: it is the credential of that one consent.

1. The administrator opens the link and approves screenRIG's app for the tenant.
2. Microsoft returns to screenRIG, which asks the administrator to sign in to that tenant. The connection records the tenant that signed in, never one a request only claims.
3. screenRIG signs in to the tenant once with the permission it was given. The connection becomes ready.

A link works once. A newer link, a finished consent or a delete ends an older one, and you can ask for a new link at any time: to renew a connection that moved to error, or to attach another tenant. If the administrator declines or the sign-in does not complete, the connection records consent_denied or consent_failed (with Microsoft's AADSTS code) and keeps its pending consent, so the same link can be opened again. A connection that already works is never degraded by a declined second consent. If the tenant removes screenRIG's app, the connection reads consent_revoked: ask an administrator to approve again.

Approval is per tenant. Once an administrator has approved screenRIG's app, anyone who can sign in to the tenant can connect it to a project of their own, so narrow what the app can read, as below. Deleting the enterprise application in Microsoft Entra ends the access of every project.

What the app can read

A connection test lists which of these the sign-in carries. It warns when only Sites.Selected is held, because each site still needs its grant, and it fails when none is.

Google

Your own app

Create a service account in Google Cloud, enable the Google Calendar API and download its JSON key (at most 16 KiB). Give the connection the whole file as secret: screenRIG checks it when you save. Then share each room calendar with the service account's address, or turn on domain-wide delegation for the account in the Admin console with the scope https://www.googleapis.com/auth/calendar.events.readonly and name a subject on the source.

screenRIG's app

The consent link opens Google's consent page. The account holder grants read-only access to calendar events (the scope calendar.events.readonly, with openid and email so screenRIG learns which account approved). If the person unticks the calendar permission, the consent fails. A source reads the calendars that account can see, so the account has to see every room calendar the source lists, and a source of such a connection cannot name a subject. When Google stops honoring the grant, the connection reads reconnect_required: ask for a new link.

Use a connection

• Meeting-room sources. Set connection_id on a microsoft365 or google_calendar source in place of tenant, client_id and client_secret, or service_account_key. Either mode works. Inline credentials keep working, and cannot be mixed with connection_id.
• SharePoint and OneDrive media sync. A Microsoft 365 sync account takes connection_id in place of tenant_id, client_id and secret.
• Power BI. A Power BI connection takes the connection_id of a Microsoft connection in mode own_app, in place of its own tenant, client ID and secret. Microsoft does not describe an app of another tenant generating embed tokens in a customer's tenant, so screenRIG's app is refused for Power BI. A Power BI administrator still enables the service principal settings and adds the app to each workspace.

A source whose connection is missing, waiting for approval or of the other provider reports config_invalid. When Microsoft or Google refuses the sign-in the source reports auth_failed and the connection moves to error.

Create one

Create a connection in the dashboard, or with POST /api/connections. For your own Microsoft app:

{
  "provider": "microsoft",
  "mode": "own_app",
  "name": "Contoso rooms",
  "config": {"tenant_id": "contoso.com", "client_id": "CLIENT_ID"},
  "secret": "CLIENT_SECRET_VALUE"
}

For screenRIG's app, with no settings and no secret:

{"provider": "google", "mode": "screenrig_app", "name": "Campus rooms"}

The answer to the second carries consent_url and consent_expires_at: send the link to the person who approves. POST /api/connections/ID/connect makes a new link, and POST /api/connections/ID/test signs in and keeps the result. Keep secrets in the request file, not on the command line.

connection_app_not_configured means the server has no screenRIG app for that provider: create the connection with your own app. connection_limit_reached means the organization has 50: delete one nothing reads through, or reuse an existing connection.

Related

• Data sources: the room sources that use a connection.
• API reference: every connection route.
• Single sign-on: how people sign in. A connection is for work that runs with nobody signed in.