{"id":19607181,"url":"https://github.com/robocorp/example-oauth-email","last_synced_at":"2025-02-26T16:44:52.063Z","repository":{"id":43055156,"uuid":"491098473","full_name":"robocorp/example-oauth-email","owner":"robocorp","description":"E-mail authorization with OAuth2 flow","archived":false,"fork":false,"pushed_at":"2023-07-12T05:48:46.000Z","size":160,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-01-09T09:26:44.531Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"RobotFramework","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robocorp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-11T12:20:29.000Z","updated_at":"2024-11-22T12:08:20.000Z","dependencies_parsed_at":"2025-01-09T09:26:07.873Z","dependency_job_id":null,"html_url":"https://github.com/robocorp/example-oauth-email","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocorp%2Fexample-oauth-email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocorp%2Fexample-oauth-email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocorp%2Fexample-oauth-email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robocorp%2Fexample-oauth-email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robocorp","download_url":"https://codeload.github.com/robocorp/example-oauth-email/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240895178,"owners_count":19874941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:09:10.795Z","updated_at":"2025-02-26T16:44:52.033Z","avatar_url":"https://github.com/robocorp.png","language":"RobotFramework","funding_links":[],"categories":[],"sub_categories":[],"readme":"# E-mail authorization with OAuth2 flow\n\nIn this example, you will learn how to send e-mails with GMail or Exchange. The\nsending is the easy part, but since these providers started to disable the usage of\npasswords, it is required now to do a more complex kind of authorization which relies\non tokens. And that's usually done through the OAuth2\n[Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) flow.\n\nIf you find this to be too complex to configure and use, there are alternatives like:\n- [Browser](https://robocorp.com/docs/libraries/rpa-framework/rpa-browser-selenium)\n  automation by logging in and sending the e-mail from there as you normally do.\n  (check this MFA [example](https://robocorp.com/portal/robot/robocorp/example-mfa-otp)\n  for learning how to setup OTP and fully automate the authentication step)\n- Outlook app automation with [RPA.Outlook.Application](https://robocorp.com/docs/libraries/rpa-framework/rpa-outlook-application)\n  (mainly for Microsoft).\n\n## Tasks\n\nBefore sending an e-mail to yourself with `Send Google/Microsoft Email`, you have to\nplace a token in the Vault with `Init Google/Microsoft OAuth` task first. This\ninitializer step is required once, then you can send as many e-mails as you want with\nsuch a token already configured.\n\n### Google (GMail)\n\n1. `Init Google OAuth`: Authenticate user, authorize app and have the token generated\n   automatically in the Vault.\n2. `Send Google Email`: Send an e-mail to yourself with GMail.\n\nWatch demo: https://www.loom.com/share/a0ce24d6e1cf4a1e80e4888f9a2483bc\n\n### Microsoft (Exchange)\n\n1. `Init Microsoft OAuth`: Authenticate user, authorize app and have the token\n   generated automatically in the Vault.\n2. `Send Microsoft Email`: Send an e-mail to yourself with Microsoft.\n\nWatch demo: https://www.loom.com/share/e385b021b4c44761811e5e3cfa66de13\n\n## Client app setup\n\nYou need to register an app which will act on behalf of your account. The app\n(Client) is the entity sending e-mails instead of you (User). But you need to\nauthenticate yourself and authorize the app first in order to allow it to send\ne-mails for you. For this, certain settings are required:\n\n### Google (GMail)\n\n1. You have to configure the *[Consent Screen](https://console.cloud.google.com/apis/credentials/consent)*\n   beforehand:\n   - Add a name and your e-mail address.\n   - Under \"Your restricted scopes\" add the `https://mail.google.com/` GMail API scope.\n     (so you give the app full permissions on your mailbox)\n   - In order to see the scope above (client app permission), you have to enable the\n     [Gmail API](https://console.cloud.google.com/marketplace/product/google/gmail.googleapis.com)\n     first.\n   - Add as test users the e-mail addresses you want to allow to complete the flow. This\n     is required as long as the app remains private \u0026 unpublished.\n\n2. Now go to *[Cloud Credentials](https://console.cloud.google.com/apis/credentials)*\n   and click \"+ CREATE CREDENTIALS\" -\u003e \"OAuth client ID\". And select the following:\n   - Application type: **Web application**\n   - Add redirect URI: `https://developers.google.com/oauthplayground`\n   - Take a note of the obtained client credentials as you'll need them later on.\n\nRead more on client setup with Google:\n- [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en)\n- [Migrate Google applications from using the deprecated out-of-band (OOB) workflow](https://support.datavirtuality.com/hc/en-us/community/posts/6854178746909-Migrate-Google-applications-from-using-the-deprecated-out-of-band-OOB-workflow)\n\n### Microsoft (Exchange)\n\n1. Create an Exchange Online [sandbox](https://learn.microsoft.com/en-us/office/developer-program/microsoft-365-developer-program-get-started)\n   (or use your current tenant).\n2. Then go to Azure Active Directory's *[App registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)*\n   page and follow [these](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)\n   app configuration instructions.\n3. Ensure you created a \"Web\" app and have the following checked:\n   - Is a *private* **single** or **multi-tenant** app.\n   - The type of the application is **Web App**.\n   - Redirect URI can be: `https://login.microsoftonline.com/common/oauth2/nativeclient`\n   - Has at least the following permission(s) enabled:\n     - **Delegated**: `EWS.AccessAsUser.All` (Office 365 Exchange Online)\n       ![API Permissions](https://raw.githubusercontent.com/robocorp/example-oauth-email/master/docs/api-permissions.png)\n   - A client secret has beed added. And take note of these credentials, as you need\n     them later on.\n4. Finally, enable **OAuth2** in the tenant and allow **Impersonation** on test users:\n   - From an Administrator PowerShell console, install [ExchangeOnlineManagement](https://www.powershellgallery.com/packages/ExchangeOnlineManagement/2.0.5)\n     module.\n   - Login with the tenant Admin:\n     - `Import-Module ExchangeOnlineManagement`\n     - `Connect-ExchangeOnline -UserPrincipalName \u003ce-mail\u003e`\n   - OAuth2 enabling:\n     - `Set-OrganizationConfig -OAuth2ClientProfileEnabled $true`\n     - Check status with: `Get-OrganizationConfig | Format-Table Name,OAuth* -Auto`\n   - Impersonation for a specific account (in order to be able to let the app send\n     e-mails with that account):\n     - `New-ManagementRoleAssignment -name:\u003cname\u003e -Role:ApplicationImpersonation -User:\u003ce-mail\u003e`\n     - `\u003cname\u003e` has to be unique.\n   - Read more on EWS access and impersonation:\n     - [Impersonation and EWS in Exchange](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/impersonation-and-ews-in-exchange)\n     - [Configure impersonation](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-configure-impersonation)\n\n## Vault setup\n\nThe client ID and client secret obtained above need to be stored securely in the Vault,\nas they'll be used automatically by the robot in order to obtain the token. Also the\ntoken itself needs an entry in the Vault so the robot can update its value in there.\n\n### Online Control Room Vault\n\nCreate a secret called `email_oauth_google/microsoft` in Control Room's Vault with the\nfollowing entries (and make sure to connect **VSCode** to the online Vault afterwards):\n- `client_id`: Your app client ID.\n- `client_secret`: Your app client secret.\n- `token`: You can leave it blank since this will be overridden by the robot.\n\n### Local file based Vault\n\nIf you can't use the online cloud Vault:\n1. Make a copy of the [vault.yaml](https://github.com/robocorp/example-oauth-email/blob/master/devdata/vault.yaml)\n   in a safe place and update the keys as already instructed above at the online Vault\n   step.\n2. Change the `RPA_SECRET_FILE` env var path in the\n   [env-local.json](https://github.com/robocorp/example-oauth-email/blob/master/devdata/env-local.json)\n   in order to make it point to your secrets *.yaml* file above. But that's not all, as:\n   - Only [env.json](https://github.com/robocorp/example-oauth-email/blob/master/devdata/env.json)\n     is picked-up automatically by **VSCode**. So copy the content of the other inside\n     this one if you really want to use the local Vault now.\n   - With **rcc** you have to pass the preferred *env* file with `-e`.\n\n## Robot run\n\nRun with **VSCode** or **rcc** the following tasks in order:\n1. `Init Google/Microsoft OAuth`: Opens a browser window for you to authenticate and\n   finally getting a redirect response URL in the address bar. Once you get there, the\n   browser closes and the token gets generated and updated in the Vault.\n   - Based on the service you want to send the e-mail with, pick from the listed Work\n     Items either **google** or **microsoft**. (and continue with the same in the next\n     step)\n     - Don't forget to configure your `username` (and optionally `tenant`) field in the\n       Work Items *.json* file for either [google](https://github.com/robocorp/example-oauth-email/blob/master/devdata/work-items-in/google/work-items.json)\n       or [microsoft](https://github.com/robocorp/example-oauth-email/blob/master/devdata/work-items-in/microsoft/work-items.json).\n   - Now you should see your brand new `token` field updated and set in the Vault.\n     (keep it private as this is like a password which grants access into your e-mail)\n   - For convenience (copy-pasting local token into Control Room's Vault), run the bot\n     with `TOKEN_AS_JSON=1` env var, so you get a string version of the entire token\n     dictionary in your Vault local file. (look under this *env-local.json*\n     [entry](https://github.com/robocorp/example-oauth-email/blob/master/devdata/env-local.json#L6)\n     on how to enable it)\n   - If by any chance you can't login in the opened \u0026 automated browser window, open\n     that auth URL (which is also printed to console during the run) in your own\n     browser and continue the flow from there. When you finish, copy-paste the final\n     URL found in the address bar from your browser into the one opened by the robot,\n     then press Enter.\n   - This step is required to be run once, requires human intervention (attended) and\n     once you get your token generated, it will stay valid (by refreshing itself)\n     indefinitely.\n2. `Send Google/Microsoft Email`: Sends a test e-mail to yourself given the credentials\n   configured in the Vault during the previous step.\n   - This step can be fully automated and doesn't require the first step run each time.\n     As once the `token` is set, it remains available until you revoke the refresh\n     token or remove the app.\n\n## Remarks\n\n- Access token lifetime:\n  - With Google, the access token (OAuth2 string as e-mail `password`) remains valid\n    for **1h**, after that you have to get a new one by calling again the\n    `Refresh OAuth Token` and `Generate OAuth String` keywords. (as it doesn't have\n    auto-refresh capability, so you need to do it yourself in the bot)\n  - With Microsoft, the token refreshes itself when it expires (internally handled by\n    the library) and is automatically updated into the Vault as well.\n- Learn more about OAuth2:\n  - [Google](https://developers.google.com/identity/protocols/oauth2)\n  - [Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow)\n- You can bypass the flow (less secure way) by using an **App Password** (can be used\n  if *2-Step-Verification* is turned **ON** only):\n  - [Google](https://robocorp.com/docs/development-guide/email/sending-emails-with-gmail-smtp#configuration-of-the-gmail-account)\n  - [Microsoft](https://support.microsoft.com/en-gb/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9)\n    - App Passwords are disabled now with Microsoft, so the only option is the OAuth2\n      flow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobocorp%2Fexample-oauth-email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobocorp%2Fexample-oauth-email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobocorp%2Fexample-oauth-email/lists"}