Register an OAuth App¶
Setting up a new Gmail / G Suite account? Because of Google’s strict security policies, it’s not as simple as entering your username and password.
First, you’ll have to connect Zammad to your Google account as an OAuth app via the Google Developer settings panel. Once that’s done, you’ll be able to connect as many Gmail accounts to Zammad as you want, using only active Gmail browser sessions (no usernames or passwords required).
🤔 What the heck is OAuth?
If you’ve ever used a website that lets you “Sign in with Google/Facebook/Twitter”, you’ve used OAuth. OAuth is a way for you to let a third-party website see a tiny slice of your Google/Facebook/Twitter account data without giving them your password (which would let them see everything).
When a third-party website wants to use OAuth, it has to register with the provider first (i.e., Google). This way, the provider knows who’s receiving its users’ data, and can give users a way to revoke access if they change their minds.
In this case, Zammad is that third-party website. That’s why adding a Gmail account is a two-stage process: first, you have to register Zammad as a website that wishes to access Google user data; then, you have to add yourself as a Google user who agrees to let Zammad fetch your email.
To get started, head over to Google’s Developer settings panel.
Create a new project
For the purposes of this guide, a “project” and an OAuth app are the same thing. You may name it whatever you wish.
Enable & add the Gmail API
Use the ➕ Enable APIs and Services button to start your search.
Set up the OAuth consent screen
This information will be displayed in the process of connecting a Gmail account to Zammad, when users are redirected to Google for sign-in/confirmation.
- User Type
This option is only available to G Suite users.
If you have the option, choose Internal (unless you plan on creating channels for Gmail addresses from outside your G Suite domain).
- Scopes for Google APIs
Add Gmail API: https://mail.google.com.
Generate OAuth credentials
Click on ➕ Create credentials > OAuth client ID to begin.
- Application type
Choose Web application.
- Authorized redirect URIs
Find it in the Zammad admin panel under Channels > Google > Connect Google App > Your callback URL.
Connect your Google app in Zammad
Copy your new OAuth app’s credentials (client ID and client secret) into Zammad in the admin panel, under Channels > Google > Connect Google App.
🍾 Congratulations! Now you’re ready to connect Gmail accounts to Zammad.
- My OAuth credentials stopped working all of a sudden
Did you recently reset your Google password?
(Google invalidates all your OAuth tokens whenever you change your password. Generate a new one per Steps 4 and 5 above.)