-
-
Notifications
You must be signed in to change notification settings - Fork 99
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into gcloud-service-account
- Loading branch information
Showing
4 changed files
with
109 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Security Policy | ||
|
|
||
| ## Supported Versions | ||
|
|
||
| Using the [latest release of the proxy](https://github.com/simonrob/email-oauth2-proxy/releases/latest) is always recommended. | ||
| Any security issues found in prior versions should be reported, but may only be fixed if they affect the latest version. | ||
|
|
||
| ## Reporting a Vulnerability | ||
|
|
||
| Report vulnerabilities or security issues using [GitHub's security tools](https://github.com/simonrob/email-oauth2-proxy/security). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -121,15 +121,36 @@ documentation = Accounts are specified using your email address as the section h | |
| - The proxy supports the client credentials grant (CCG) and resource owner password credentials grant (ROPCG) OAuth | ||
| 2.0 flows (both currently only known to be available for Office 365). To use either of these flows, add an account | ||
| entry as normal, but do not add a `permission_url` value (it does not apply, and its absence signals to the proxy to | ||
| use the appropriate token retrieval mechanism). An example is given at the end of the sample account entries below. | ||
| The CCG flow is the default in this mode; to specify the ROPCG flow add `oauth2_flow = password` in your account | ||
| configuration, and use a normal `oauth2_scope` value rather than the CCG-specific `.default`. Please note also that | ||
| Office 365's CCG flow does not support SMTP, and by default it has essentially no local access control when using | ||
| IMAP/POP in this mode (no user consent is involved, so the proxy cannot validate passwords). Because of this, you | ||
| are encouraged to enable the proxy's secret encryption option - see `encrypt_client_secret_on_first_use` at the end | ||
| of this file. In addition, if you are using the proxy in an environment where there is any possibility of malicious | ||
| access attempts before the first valid login then pre-encrypting account entries is highly recommended - see the | ||
| example setup script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336. | ||
| use the appropriate token retrieval mechanism). For CCG, set `oauth2_scope = https://outlook.office365.com/.default` | ||
| and `oauth2_flow = client_credentials`. For ROPG, set `oauth2_flow = password` (and use a standard scope value). An | ||
| example is given for both methods towards the end of the sample account entries below. | ||
|
|
||
| - WARNING: Please note that by default the CCG flow has essentially no local access control when creating new | ||
| accounts (no user consent is involved, so the proxy cannot validate login attempts unless an account entry | ||
| already exists its configuration file). Using the CCG flow with the proxy in a publicly-accessible context is | ||
| not advised. This is especially important when using the proxy's catch-all feature (which is likely to be the | ||
| case given the typical use-cases for the CCG flow). Because of this, you are highly encouraged to enable the | ||
| proxy's secret encryption option - see `encrypt_client_secret_on_first_use` at the end of this file. In | ||
| addition, if you are using the proxy in an environment where there is any possibility of malicious access | ||
| attempts before the first valid login, pre-encrypting account entries is highly recommended. See the example | ||
| script at https://github.com/simonrob/email-oauth2-proxy/issues/61#issuecomment-1259110336. | ||
|
|
||
| Gmail customisation: | ||
| - The proxy supports the use of service accounts with Gmail for Google Workspace (note: normal Gmail accounts do not | ||
| support this method). To use this option, add an account entry as normal, but do not add a `permission_url` value | ||
| (it does not apply, and its absence signals to the proxy to use the appropriate token retrieval mechanism). Set | ||
| `oauth2_flow = service_account`. The service account key itself can either be referenced in an external file, or | ||
| pasted directly into the account entry. For the file approach, set `client_id = file` and `client_secret` to the | ||
| full path to the JSON key file. To include the key directly, set `client_id = key`, then paste the full contents of | ||
| your service account's JSON key as the value for `client_secret`, making sure all lines are indented by at least one | ||
| space (so that the proxy can tell they are all part of one value). An example is given for both methods towards the | ||
| end of the sample account entries below. | ||
|
|
||
| - WARNING: Please note that the same potential security issues outlined above with O365's CCG flow also apply to | ||
| the service account method: there is essentially no local access control when creating new accounts. Using a | ||
| service account with the proxy in a publicly-accessible context is not advised. You are highly encouraged to | ||
| enable the proxy's secret encryption option (see `encrypt_client_secret_on_first_use` at the end of this file) | ||
| and consider pre-encrypting account entries. | ||
|
|
||
| Advanced account configuration: | ||
| - For most configurations the default `redirect_uri` value of `http://localhost` is correct, unless you have | ||
|
|
@@ -181,7 +202,7 @@ redirect_uri = http://localhost | |
| client_id = *** your client id here *** | ||
| client_secret = *** your client secret here *** | ||
|
|
||
| [ccg.or.ropcg.[email protected]] | ||
| [[email protected]] | ||
| documentation = *** note: this is an advanced O365 account example; in most cases you want the version above instead *** | ||
| token_url = https://login.microsoftonline.com/*** your tenant id here ***/oauth2/v2.0/token | ||
| oauth2_scope = https://outlook.office365.com/.default | ||
|
|
@@ -190,6 +211,34 @@ redirect_uri = http://localhost | |
| client_id = *** your client id here *** | ||
| client_secret = *** your client secret here *** | ||
|
|
||
| [[email protected]] | ||
| documentation = *** note: this is an advanced O365 account example; in most cases you want the version above instead *** | ||
| token_url = https://login.microsoftonline.com/*** your tenant id here ***/oauth2/v2.0/token | ||
| oauth2_scope = https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/POP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access | ||
| oauth2_flow = password | ||
| redirect_uri = http://localhost | ||
| client_id = *** your client id here *** | ||
| client_secret = *** your client secret here *** | ||
|
|
||
| [[email protected]] | ||
| documentation = *** note: this is an advanced Google account example; in most cases you want the version above instead *** | ||
| token_url = https://oauth2.googleapis.com/token | ||
| oauth2_scope = https://mail.google.com/ | ||
| oauth2_flow = service_account | ||
| redirect_uri = http://localhost | ||
| client_id = file | ||
| client_secret = *** your /path/to/service-account-key.json here *** | ||
|
|
||
| [[email protected]] | ||
| documentation = *** note: this is an advanced Google account example; in most cases you want the version above instead *** | ||
| token_url = https://oauth2.googleapis.com/token | ||
| oauth2_scope = https://mail.google.com/ | ||
| oauth2_flow = service_account | ||
| redirect_uri = http://localhost | ||
| client_id = key | ||
| client_secret = *** your pasted service account JSON key file contents here, | ||
| making sure to indent all lines by at least one space *** | ||
|
|
||
| [Advanced proxy configuration] | ||
| documentation = The parameters below control advanced options for the proxy. In most cases you will not need to modify | ||
| the values in this section. If any of these values are not found, the proxy will assume the default value, which | ||
|
|
@@ -204,19 +253,23 @@ documentation = The parameters below control advanced options for the proxy. In | |
| be laborious or need administrator intervention, this can potentially result in a denial-of-service issue, whether | ||
| malicious or not. It can also be the source of confusion if using a client (such as Firefox) that stores a separate | ||
| password per protocol for each account, but does not make this clear when changing account passwords. Set this | ||
| option to False and the proxy will instead return an error when an incorrect password is provided. | ||
| option to False and the proxy will instead return an error when an incorrect password is provided. For accounts | ||
| using the O365 CCG flow or a Google Cloud service account this option will be overridden and always set to False. | ||
|
|
||
| - encrypt_client_secret_on_first_use (default = False): The proxy encrypts sensitive configuration values (e.g., | ||
| cached access tokens) using the password that is given when accessing an account via IMAP/POP/SMTP. It does not do | ||
| this for values that are not sensitive. In the most common operation mode (i.e., interactively authorising account | ||
| access), the `client_secret` value falls into this category - it is not actually secret, and there is no real need | ||
| to prevent access to it. However, when using the Office 365 client credentials grant flow there is no user involved, | ||
| and possession of the secret grants full access to an account. If you use this method and it is possible that others | ||
| may gain access to the proxy's configuration file, set `encrypt_client_secret_on_first_use` to True and the proxy | ||
| will replace the `client_secret` value with a new property `client_secret_encrypted` at the next token refresh. Note | ||
| that this option is not compatible with `allow_catch_all_accounts` unless all accounts use the same login password. | ||
| In addition, if you are using the proxy's `--cache-store` parameter you will need to manually remove unencrypted | ||
| secrets from this configuration file after the encrypted secret has been created (i.e., it will not be automatic). | ||
| to prevent access to it. However, when using the client credentials grant (CCG) flow or a service account, there is | ||
| no user involved, and possession of the secret grants full access to an account. If you use either of these methods | ||
| and it is possible that others may gain access to the proxy's configuration file; or, you are using catch-all | ||
| accounts (see below) and others may attempt to log in with accounts that the secret has access to but that you have | ||
| not yet set up with the proxy, set `encrypt_client_secret_on_first_use` to True and the proxy will replace the | ||
| `client_secret` value with a new property `client_secret_encrypted` at the next token refresh. Note that this option | ||
| is not fully compatible with `allow_catch_all_accounts` unless all accounts use the same login password, or you | ||
| undertake some additional manual setup configuration (see below for further details). In particular, if you are | ||
| using catch-all accounts or the proxy's `--cache-store` parameter you must manually remove unencrypted secrets from | ||
| the local configuration file after the encrypted secret has been created (i.e., this will not be automatic). | ||
|
|
||
| - allow_catch_all_accounts (default = False): The default behaviour of the proxy is to require a full separate | ||
| configuration file entry for each account. However, when proxying multiple accounts from the same domain it can be | ||
|
|
@@ -225,9 +278,11 @@ documentation = The parameters below control advanced options for the proxy. In | |
| example, add a section [@domain.com] with all of the standard required account values, and the proxy will intercept | ||
| authentication requests for all usernames at `domain.com`. Whenever a previously unseen account attempts to connect, | ||
| account authorisation will take place as normal, and the proxy will automatically create a new account-level section | ||
| that does not need to be configured manually. Any account-level configuration will override domain-level values. | ||
| If needed, the global catch-all section [@] can also be used. Please note that this option is not compatible with | ||
| `encrypt_client_secret_on_first_use` unless all IMAP/POP/SMTP accounts at the same domain use the same password. | ||
| that does not need to be configured manually. Any account-level configuration will override domain-level values | ||
| (except for account access and refresh tokens). If needed, the global catch-all section [@] can also be used. Please | ||
| note that this option is not fully compatible with `encrypt_client_secret_on_first_use` unless all IMAP/POP/SMTP | ||
| accounts at the same domain use the same password, or you undertake additional manual configuraton steps - see the | ||
| discussion at https://github.com/simonrob/email-oauth2-proxy/issues/214#issuecomment-1861593781 for details. | ||
|
|
||
| [emailproxy] | ||
| delete_account_token_on_password_error = True | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters