OAuth Authentication for SMTP

OAuth authentication provides a more secure way to connect your email provider to Chargebee for sending email notifications. Instead of storing passwords, OAuth uses secure tokens that can be revoked at any time and don't expose your actual credentials.

Overview

Chargebee supports OAuth authentication for the following email providers:

Benefits of OAuth vs Password Authentication

Prerequisites

Before configuring OAuth authentication, ensure you have:

For Microsoft 365

• A Microsoft 365 business or enterprise account
• Admin consent for the Chargebee application (may be required by your organization)
• The email account you want to use for sending notifications

For Google Workspace

• A Google Workspace business account
• Admin approval for third-party app access (if required by your organization)
• The email account you want to use for sending notifications

Connecting via OAuth

Follow these steps to connect your email provider using OAuth authentication:

Step 1: Navigate to SMTP Settings

1. Go to Settings > Configure Chargebee > Email Notifications > Change SMTP settings
2. Click Configure SMTP server

Step 2: Select OAuth Authentication

1. In the SMTP configuration modal, click on the OAuth tab
2. You will see the available OAuth providers (Microsoft and Google)

Step 3: Choose Your Provider

Select the email provider you want to connect:

• Click on Microsoft to connect a Microsoft 365 account
• Click on Google to connect a Google Workspace account

Step 4: Authenticate with Your Provider

1. A popup window will open, redirecting you to your email provider's login page

2. Sign in with your email account credentials
3. Review the permissions requested by Chargebee
4. Click Accept or Allow to grant access

Step 5: Verify Connection

Once authentication is successful:

1. The popup will close automatically
2. You will see a confirmation showing the connected email address
3. The connection status will display "Connected" with a timestamp

Managing OAuth Connections

Viewing Connection Details

After connecting via OAuth, you can view:

• Connected Email: The email address used for sending notifications
• Provider: Microsoft or Google
• Connected At: The time when the OAuth connection was established

Disconnecting OAuth

To disconnect an OAuth connection:

1. Go to Settings > Configure Chargebee > Email Notifications > Change SMTP Settings
2. Click Manage SMTP server
3. Click Disconnect

5. Confirm the disconnection when prompted

Reconnecting OAuth after Disconnection

If you need to reconnect:

1. Follow the same steps as the initial connection
2. You may need to re-authorize Chargebee in your email provider's settings

How OAuth Works

When you connect via OAuth:

1. Authorization: You authorize Chargebee to send emails on your behalf
2. Token Exchange: Chargebee receives secure access and refresh tokens
3. Email Sending: Chargebee uses these tokens to authenticate with your email provider's SMTP server
4. Token Refresh: Tokens are automatically refreshed before expiration

Token Expiration and Refresh

• OAuth tokens have a limited lifespan (typically 1 hour for access tokens)
• Chargebee automatically refreshes tokens before they expire
• If a refresh fails (e.g., due to revoked access), you will need to reconnect

Troubleshooting

Popup Blocked

Problem: The authentication popup doesn't appear or is blocked.

Solution:

1. Check your browser's popup blocker settings
2. Allow popups from your Chargebee site domain
3. Try using a different browser
4. Disable browser extensions that might block popups

Connection Failed

Problem: The OAuth connection fails after authentication.

Solution:

1. Ensure you're using a business email account (not a personal account)
2. Check if your organization requires admin consent for third-party apps
3. Verify your email account has the necessary permissions
4. Contact your IT administrator if your organization has restrictions

Admin Consent Required (Microsoft 365)

Problem: Microsoft shows "Admin consent required" or "Need admin approval" message.

Solution:

1. Contact your Microsoft 365 administrator
2. Request approval for the Chargebee application
3. The admin can approve the app from the Azure Active Directory admin center
4. Once approved, retry the connection

Emails Not Being Sent

Problem: OAuth is connected but emails are not being delivered.

Solution:

1. Verify the connection status in SMTP settings
2. Check if the OAuth token needs to be refreshed (try disconnecting and reconnecting)
3. Verify the connected email account is active and not suspended
4. Check your email provider's sending limits

Token Expired or Revoked

Problem: Previously working OAuth connection stops sending emails.

Solution:

1. The OAuth access may have been revoked from your email provider
2. Disconnect the current OAuth connection in Chargebee
3. Reconnect following the standard OAuth flow
4. Check your email provider's connected apps settings

Security Considerations

Permissions Granted

When you authorize Chargebee via OAuth, the following permissions are typically requested:

Microsoft 365:

• Send mail as you (SMTP.Send)
• Maintain access to data you have given it access to (offline_access)

Google Workspace:

• Send email on your behalf (gmail.send)
• View your email address (userinfo.email)

Revoking Access

You can revoke Chargebee's access at any time:

For Microsoft 365:

1. Go to Microsoft Account - App Permissions
2. Find Chargebee in the list of apps
3. Click Remove to revoke access

For Google Workspace:

1. Go to Google Account - Third-party apps
2. Find Chargebee in the list of apps
3. Click Remove Access

Frequently Asked Questions (FAQs)

1. Can I use OAuth with a personal Gmail or Outlook account?

OAuth is primarily designed for business accounts (Google Workspace and Microsoft 365). Personal accounts may have restrictions. We recommend using business accounts for reliable email delivery.

2. What happens if my organization's admin revokes the OAuth consent?

If admin consent is revoked, Chargebee will no longer be able to send emails through your account. You will need to reconnect after the admin re-approves the application.

3. Do I need to update my SMTP configuration when my password changes?

No! This is one of the key benefits of OAuth. Since OAuth doesn't use your password, password changes don't affect your email configuration.

4. Can I have both OAuth and password-based SMTP configured?

No, you can only have one active SMTP configuration at a time. You can switch between OAuth and password-based authentication, but only one will be active.

5. How do I know if my emails are being sent successfully?

Check the Email Logs in Chargebee to monitor email delivery status. Navigate to Settings > Configure Chargebee > Email Notifications > Email Logs.

6. Is OAuth more reliable than password-based SMTP?

OAuth is generally more reliable because:

• It's not affected by password changes
• It works seamlessly with MFA-enabled accounts
• Tokens are automatically refreshed

7. What scopes does Chargebee request for OAuth?

Chargebee requests only the minimum permissions needed to send emails:

• Microsoft: SMTP.Send and offline_access
• Google: gmail.send and userinfo.email

Related Articles

• SMTP Configuration Overview - Overview of SMTP options
• Basic Authentication - Configure username/password SMTP
• Email Notifications - Learn about email notification types
• DMARC Regulation - Understand DMARC and email deliverability
• Email Logs - Monitor your email delivery