CoDNA Request access
Contents

Docs Getting started

Sign-in apps: Google, Microsoft and other providers

A connection that reads Google Sheets or Microsoft 365 signs in as the person who made it (Signing a connection in). It does that through a sign-in app that whoever runs CoDNA registers once, inside the company's own Google Cloud project or Microsoft tenant. This page walks through registering one with each, and with any other OAuth 2.0 provider.

Each app is internal: only the company's own people can sign in to it, and Google and Microsoft review nothing. It takes a few minutes, by someone who administers the company's Google Workspace or Microsoft tenant.

Every app needs the same redirect address, which the console's Connections tab shows with a copy button, and codna oauth list prints:

https://acme.codna.me/connections/oauth/callback

Use your own CoDNA's address in place of acme.codna.me.

Google

In the Google Cloud console, signed in as an administrator of the company's Google Workspace:

  1. Pick or create a project for CoDNA, such as codna.
  2. Turn on the APIs people will read, under APIs & Services → Library: Google Sheets API, Google Drive API, Google Calendar API, Gmail API, as needed.
  3. Set up Google Auth Platform, under APIs & Services → OAuth consent screen: give it a name people will recognise when they sign in, such as "CoDNA", and under Audience choose Internal. An external app in testing gives out sign-ins that stop after seven days.
  4. Create a client, under Clients → Create client: application type Web application, and under Authorized redirect URIs add the redirect address above. Copy the client ID and the client secret as it is shown: Google shows a new secret only once.

Then register it in CoDNA, from the console's Connections tab (New app, provider Google), or:

codna oauth add google --provider google \
  --client-id 123456789-abc.apps.googleusercontent.com \
  --scopes https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/drive.readonly

The secret is asked for. The scopes are the most people may ask for; each connection asks for some of them. The common ones:

  • Sheets, read: https://www.googleapis.com/auth/spreadsheets.readonly
  • Sheets, read and write: https://www.googleapis.com/auth/spreadsheets
  • Drive, read: https://www.googleapis.com/auth/drive.readonly
  • Calendar, read: https://www.googleapis.com/auth/calendar.readonly
  • Gmail, read: https://www.googleapis.com/auth/gmail.readonly

CoDNA adds openid and email itself, to show whose account a connection signed in as.

A person's connection then reads from the API's own address. For a sheet, https://sheets.googleapis.com/v4, and a script reads a range with:

source('sheet', { path: '/spreadsheets/1AbC…/values/Applications!A1:F500' })

Microsoft 365

In the Microsoft Entra admin center, as an administrator of the company's tenant:

  1. Register an app, under App registrations → New registration: a name such as "CoDNA"; supported account types Accounts in this organizational directory only (single tenant); redirect URI platform Web, with the redirect address above.
  2. From its Overview, copy the Application (client) ID and the Directory (tenant) ID.
  3. Make a secret, under Certificates & secrets → New client secret. Copy its Value, not its Secret ID. A secret expires, after two years at most: make a new one before then, and give it to CoDNA with codna oauth change microsoft --secret.
  4. Choose what it may ask for, under API permissions → Add a permission → Microsoft Graph → Delegated permissions, such as Files.Read, Sites.Read.All, Calendars.Read or Mail.Read. Grant admin consent for the tenant, so people aren't each asked, and so permissions that need an administrator, such as Sites.Read.All, work at all.

Then register it in CoDNA, from the console (New app, provider Microsoft), or:

codna oauth add microsoft --provider microsoft \
  --client-id 0f1e2d3c-… --tenant acme.ge \
  --scopes Files.Read,Sites.Read.All

The tenant is its directory ID, or a domain of the tenant. CoDNA adds openid, email and offline_access itself. A connection reads from https://graph.microsoft.com/v1.0, for example a file in someone's OneDrive with source('onedrive', { path: '/me/drive/root:/Reports/q3.xlsx' }).

Another OAuth 2.0 provider

HubSpot, Salesforce, Zoom and most others follow the same steps in their developer settings: register an app with the redirect address above, and copy its client ID and secret. CoDNA needs the provider's authorize and token addresses too, from its documentation, and a revoke address if it has one:

codna oauth add hubspot --provider oauth2 --client-id … \
  --authorize-url https://app.hubspot.com/oauth/authorize \
  --token-url https://api.hubapi.com/oauth/v1/token \
  --scopes crm.objects.contacts.read

CoDNA signs in with PKCE. It sends the client ID and secret in the body of each token request, or as HTTP Basic to a provider that refuses them in the body, as Zoom does.

Afterwards

  • People sign in on the Connections page, choosing the app under How it gets its token.
  • Changing an app's scopes leaves connections signed in with what they were given, until they sign in again.
  • Removing an app stops every connection that signed in through it. Their owners can paste a token instead, or sign in again once there is another app.
  • A person who leaves, or revokes CoDNA's access in their Google or Microsoft account, stops their connections. Each owner is told in their inbox, and the Connections page offers Sign in again.