E-mail authorization with OAuth2 flow

Setup

1. First, you need to register an app which will act on behalf of your account.

   Google (GMail)

   Go to Cloud Credentials and click "+ CREATE CREDENTIALS" -> "OAuth client ID" (Desktop app). You have to configure the Consent Screen beforehand:

   • During the configuration don't forget to add the https://mail.google.com/ GMail API scope. (so you give the app full permissions on your mailbox)
   • If you can't find the scope, enable Gmail API for being able to use the e-mail scope (app permission) from above.

   Microsoft (Exchange Outlook)

   Create an Exchange Online sandbox (or use your current tenant), then go to Azure AD's App registrations and follow these app configuration instructions. Make sure you checked the following:

   • Is a private multi-tenant app. ("Accounts in any organizational directory" is checked)
   • The type of the application is a "Web App".
     • Redirect URI can be: https://login.microsoftonline.com/common/oauth2/nativeclient
   • Has at least the following permission(s) enabled:
     • Delegated: EWS.AccessAsUser.All (Office 365 Exchange Online)
   • OAuth2 and Impersonation are enabled:
     • From an Administrator PowerShell console, install ExchangeOnlineManagement module.
     • Login with the tenant Admin:
       • Import-Module ExchangeOnlineManagement
       • Connect-ExchangeOnline -UserPrincipalName <e-mail>
     • OAuth2 enabling:
       • Set-OrganizationConfig -OAuth2ClientProfileEnabled $true
       • Check status with: Get-OrganizationConfig | Format-Table Name,OAuth* -Auto
     • Impersonation for any account (required to be able to authorize the app and send e-mails):
       • New-ManagementRoleAssignment -name:impersonationAssignmentName -Role:ApplicationImpersonation -User:<e-mail>

2. Create a secret called email_oauth_google/microsoft in Control Room's Vault with the following entries (and make sure to connect VSCode to the online secrets vault first):

   • client_id: Your app client ID (obtained at step 1.)
   • client_secret: Your app client secret (obtained at step 1.)
   • token: You can leave it blank since this will be overridden by the robot

Using the local vault

If you don't want to use the online cloud Vault:

1. Make a copy of the vault.yaml in a safe place and update the keys as already instructed above at the online Vault step.
2. Change the RPA_SECRET_FILE env var path in the env-local.json in order to make it point to your secrets .yaml file above. (then rename this file to env.json if you want it picked up automatically by VSCode)

Robot run

Run with VSCode or rcc the following tasks in order:

1. Init OAuth Flow: Opens a browser window for you to authenticate and finally getting the authorization code which has to be placed in the dialog asking for it. (now you should see your brand new token field updated and set in the Vault; keep it private as this is like a password which grants access into your e-mail)
   • Based on the client you want to send the mail with, pick from the listed Work Items either google or microsoft. (and continue with the same in the next step)
     • Don't forget to configure your username (and optionally tenant) field in the Work Items .json file for either google or microsoft.
   • With Google, you'll see the auth code displayed in the browser window, whether with Microsoft you'll find it in the address bar.
2. Send Google/Microsoft Email: Sends a test e-mail to yourself given the credentials configured in Vault. This step can be fully automated, as once the token is set, it remains available until you revoke it (or removing the app).

Remarks

• Access token lifetime:
  • With Google, the access token (OAuth2 string as e-mail password) remains valid for 1h, after that you have to get a new one by calling again the Generate Google Oauth2 String keyword. (doesn't have auto-refresh capability)
  • With Microsoft, the token refreshes itself when it expires and is automatically updated into Vault as well.
• Learn more about OAuth2:
  • Google
  • Microsoft
• You can bypass the flow (less secure way) by using an App Password (can be used if 2-Step-Verification is turned ON only):
  • Google
  • Microsoft