view release on metacpan or  search on metacpan

lib/App/wsgetmail.pm  view on Meta::CPAN

=head3 Configuring client secret authentication

We recommend you deploy wsgetmail by configuring it with a client
secret. Client secrets can be granted limited access to only the mailboxes
you choose. You can adjust or revoke wsgetmail's access without interfering
with other applications.

Microsoft documents how to create a client secret in the L<"Register an
application with the Microsoft identity platform"
quickstart|https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret>,
under the section "Add a client secret." Take care to record the secret
token when it appears; it will never be displayed again. It should look like
a completely random string, not a UUID/GUID.

=over 4

=item global_access

Set this to C<1> in your wsgetmail configuration file.

=item secret

Set this to the secret token string you recorded earlier in your wsgetmail
configuration file.

=item username

wsgetmail will fetch mail from this user's account. Set this to an email
address string in your wsgetmail configuration file.

=back

=head3 Configuring user+password authentication

If you do not want to use a client secret, you can also configure wsgetmail
to authenticate with a traditional username+password combination. As noted
above, this method is not recommended by Microsoft. It also does not work
for systems with federated authentication enabled.

=over 4

=item global_access

Set this to C<0> in your wsgetmail configuration file.

=item username

wsgetmail will authenticate as this user. Set this to an email address
string in your wsgetmail configuration file.

=item user_password

Set this to the password string for C<username> in your wsgetmail
configuration file.

=back

=head3 Configuring Microsoft Government Cloud

If you are connecting to a Microsoft Government Cloud tenant (GCC High or
DoD), the default Microsoft Graph API and OAuth endpoints will not work. Use
the following options to point wsgetmail at the correct endpoints.

=over 4

=item resource_url

Set this to the Microsoft Graph API base URL for your cloud environment.
The default is C<https://graph.microsoft.com/>. For GCC High, use
C<https://graph.microsoft.us/>. For DoD, use
C<https://dod-graph.microsoft.us/>.

=item login_base_url

Set this to the base URL for OAuth authentication. The default is
C<https://login.windows.net>. For GCC High and DoD, use
C<https://login.microsoftonline.us>.

=back

=head2 Configuring the mail delivery command

Now that you've configured wsgetmail to access a mail account, all that's
left is configuring delivery. Set the following in your wsgetmail
configuration file.

=over 4

=item folder

Set this to the name string of a mail folder to read.

=item stripcr

Set this to 1 to make wsgetmail convert the messages from the CRLF
line-ending encoding to the LF line-ending encoding.

This emulates the fetchmail option of the same name, which enabled
the stripcr option if an MDA was declared. The feature is similar,
but you need to enable it explicitly in your configuration.

This option is helpful if you are forwarding email to a Linux
utility that doesn't work with CRLF line-endings.

=item size_limit

Set this to the max size in bytes. Messages bigger than it will be skipped.
Absence or 0 means to not limit size.

E.g. to skip messages bigger than C<10MiB>, you can set it to C<10485760>.

=item body_size_limit

Set this to the max body size in bytes. Messages with body bigger than it will
be skipped. Absence or 0 means to not limit body size.

E.g. to skip messages with body bigger than C<1MiB>, you can set it to
C<1048576>.

The difference between C<size_limit> and C<body_size_limit> is the former
limits the size of the whole message, while the latter parses messages, skips
attachments and only checks text/plain and text/html parts.