Connecting Gmail and Outlook mailboxes on your server

Applies to: the IT Admin User (one-time registration) and Workspace Admins · Time: about 20 minutes

Overview

This is optional. Invitations and notifications already go out through your company mail server. Connecting Gmail or Outlook lets each person read and send their own email inside Digital Workspace, and sync their calendar.

On your own server, Continue with Gmail and Continue with Outlook work only after your IT Admin User registers an app with Google or Microsoft for your server. Until then, clicking one of them shows Gmail sign-in isn't enabled on this server yet (or Outlook), and people can still use the simple in-app inbox.

Before you begin

• HTTPS is turned on with a server name (see "Turning on HTTPS"). Google and Microsoft accept only https:// return addresses. Google also needs a real domain name, not an IP address.
• The Web address in Workspace settings › Mail server is the HTTPS address.
• The Email Inbox module is turned on in Workspace settings › Modules.
• The server can reach Google (accounts.google.com, googleapis.com) or Microsoft (login.microsoftonline.com, graph.microsoft.com) on the internet. An offline server can't connect these mailboxes.

Your return address (redirect URI)

Both registrations need this address. Replace the first part with your web address:

https://workspace.company.uz/api/email/oauth/callback

Outlook / Microsoft 365 (IT Admin User)

1. In the Microsoft Entra admin center, open App registrations → New registration.
2. Name it Digital Workspace. Under Supported account types, keep Accounts in this organizational directory only. Under Redirect URI, choose Web and paste your return address. Click Register.
3. Copy the Application (client) ID and the Directory (tenant) ID.
4. Open Certificates & secrets → New client secret and copy its Value.
5. Open API permissions → Add a permission → Microsoft Graph → Delegated, and add openid, email, profile, offline_access, User.Read, Mail.Read, Mail.Send and Calendars.ReadWrite. Click Grant admin consent.

Gmail / Google Workspace (IT Admin User)

1. In the Google Cloud console, create a project and enable the Gmail API (and the Google Calendar API for calendars).
2. Set up the OAuth consent screen. For a company Google Workspace, choose Internal so that only your colleagues can use it.
3. Open Credentials → Create credentials → OAuth client ID, type Web application, and add your return address under Authorized redirect URIs.
4. Copy the Client ID and Client secret.

Add the keys to the server (IT Admin User)

1. On the server, open /opt/digital-workspace/.env. Find the lines you need, remove the # at the start of each one, and fill in the value after the = sign:
   • MICROSOFT_CLIENT_ID=, MICROSOFT_CLIENT_SECRET= and MICROSOFT_TENANT= (your Directory (tenant) ID)
   • GOOGLE_CLIENT_ID= and GOOGLE_CLIENT_SECRET=
2. Apply the change: cd /opt/digital-workspace && sudo docker compose up -d app.
3. Keep the client secrets private. Never paste them in chat or email; Microsoft secrets expire, so note the date and replace the secret before it does.

Connect a mailbox

1. Each person opens Email Inbox and clicks Continue with Gmail or Continue with Outlook.
2. They sign in on the Google or Microsoft page and approve access, then return to Digital Workspace.

The rest works as described in "Setting Up Email". Invitations still go out through the company mail server.

Troubleshooting