AUTH ACCESS mapping table

New in 7.0.5 is the  mapping table, which provides the means to exercise increased control over SMTP session characteristics. This access mapping is consulted during SMTP/LMTP client operations just prior to initiating  client connections, and in particular, prior to DNS or host table  lookup of destination domains. (In particular, and as compared to the later   mapping,    is  consulted prior to MX record lookups.) The    mapping allows  control or override of various SMTP session level features.

The default probe for the  mapping is of the form: channel&#x7c;filename&#x7c;queue-time&#x7c;envelope-from&#x7c;auth-parameter&#x7c;username&#x7c;domain where   is the channel from which the message is being dequeued,   is the full  file name of the message,   is the  approximate time in seconds that the message has been in the queue (or    if that value cannot be determined),    is the envelope From address for  this message,    is the unencoded  value of any MAIL FROM AUTH= parameter associated with the message,    is the authentication identity used to  submit the message (plus an asterisk character suffix), and    is the DNS name of the server to which the  message would (if not overridden by this mapping) be sent. Note that the   is not necessarily the same as the  user&#x27;s canonical e-mail address  (  attribute value) or  any other LDAP attribute value; rather, the    is a canonical identity constructed as     . Note also that the  MTA option, if set, will cause any vertical bar characters that would have been in the   ,  ,  , or   fields to be replaced by the specified character.

New in MS 8.0.2.2, If bit 11, value 2048, of the  MTA option is set the probe changes to include the conversion tag for the message: channel&#x7c;filename&#x7c;queue-time&#x7c;envelope-from&#x7c;auth-parameter&#x7c;username&#x7c;conversiontag&#x7c;domain New in MS 8.0.2.3, if bit 0, value 1, of the  MTA option is set the probe changes to include the count of previous retries for the message: channel&#x7c;filename&#x7c;retry-count&#x7c;queue-time&#x7c;envelope-from&#x7c;auth-parameter&#x7c;username&#x7c;domain The mapping template (right hand side) can contain a number of flags plus a series of vertical bar separated fields. Setting a flag causes the consumption of zero or more fields, processed in the order, and  with the effects, shown in  Table of AUTH_ACCESS mapping output flags.

As of MS 8.1.0.1, there are also a number of input flags:

The  mapping table can be used for a variety of purposes,  including various special-purpose, targetted, override effects on SMTP  connections. However, the combination of effects it allows is especially intended to facilitate special-purpose  identity/authentication scenarios, such as effective "on behalf of  submission", also called "third party submission".

For instance, suppose that local user   also has a remote identity and  mailbox as , and that this local  user when submitting messages through your MTA would sometimes, for  some messages, like those message to go out under the remote  identity/address. In the example below, for specificity, assume further that the user client will authenticate when submitting such messages,  submitting with the user&#x27;s normal, local address as the envelope From,  but with a MAIL FROM AUTH= parameter set to the remote address. Then an   mapping to redirect such messages to a remote.domain.com  server and submit the messages using the remote identity could be: AUTH_ACCESS tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;adam.brown@local.domain.com&#x7c;abrown@remote.domain.com&#x7c;$&#x2a;adam.brown@local.domain.com&#x7c;&#x2a; \ $Fabrown@remote.domain.com&#x7c;$Q&#x7c;abrown@remote.domain.com&#x7c;remotepassword&#x7c;$/$Dremote.domain.com&#x7c;$P587 If such a setup is desired for multiple users, rather than just one or a few special users hard-coded (with their remote passwords!) into the    mapping, then a more real-world example might also include  storing such users&#x27; remote credentials (remote identity and remote  password) in some data repository, for instance, perhaps in the regular  user LDAP directory, or perhaps in a special LDAP directory accessed  via extldap: URLs, or even in some other database, and then looking up  the addresses and credential data when messages come through with a  MAIL FROM AUTH= parameter differing from the envelope From. Note that in such setups, one of the most challenging aspects (not from the MTA  configuration point of view, but rather from the design and maintenance  of the data point of view) is likely to be establishing, and  maintaining, a tight correspondence between each such local user  identity and the remote identity (or identities) that local user is  authorized to use.

In AUTH_ACCESS mapping example: third party submission, when SMTP AUTH was used to submit a message so that a username is present for the message, if also a MAIL FROM AUTH=  parameter is present and differs from the username, then the username  is looked up in LDAP and that user&#x27;s LDAP entry is checked for whether  a value of a special LDAP attribute, here assumed to be  , matches the MAIL FROM AUTH= parameter  value.

The user data is assumed, for purposes of AUTH_ACCESS mapping example: third party submission, to be  organized in two LDAP directories: the usual user/group LDAP directory  (containing, in addition to all the usual attributes for users, a  special site-added, potentially multi-valued,    attribute, used to store any remote  addresses that user is permitted to use), as well as a so-called  "external" LDAP directory (containing remote domain names  under which are stored the remote addresses with their credentials and  an attribute for each remote address specifying which local address(es)  are permitted to use that remote identity). See AUTH_ACCESS mapping example: Excerptoflocal user entry in user/group LDAP and  AUTH_ACCESS mapping example: Excerpt of remote identity entries in alternate (external) LDAP  for example excerpts of such a data setup. Administratively, the management and updating and access to the data in the "external" LDAP directory may well be somewhat separate  and different than for the usual user/group LDAP directory. See the MTA options for configuration of external LDAP lookups, discussed in  LDAP external directory lookup MTA options.

AUTH_ACCESS mapping example: Excerpt of local user entry in user/group LDAP
 In the local.domain.com users portion of the DIT: mail: adam.brown@local.domain.com mailRemoteIdentity: abrown@remote1.domain.com mailRemoteIdentity: adam.brown@remote2.domain.com 

AUTH_ACCESS mapping example: Excerpt of remote identity entries in alternate (external) LDAP
Under the remote1.domain.com portion of the "external" LDAP DIT: mail: abrown@remote1.domain.com username: remote1-username password: remote1-password submittor: adam.brown@local.domain.com Under the remote2.domain.com portion of the "external" LDAP DIT: mail: adam.brown@remote2.domain.com username: remote2-username password: remote2-password submittor: adam.brown@local.domain.com Another important aspect to consider is such setups is error handling: what should happen to messages when (and note that it is almost certain  to be a "when" not merely an "if" occurrence) the  remote credentials are not accepted by the remote server, or the remote  SMTP SUBMIT server is unavailable for an extended period of time. One possible approach, though surely not the only approach, is to have the  MTA repeat attempting the remote submission a few times, but then  "fall back" to emitting the message instead with the original  From address (the locally verified, local user identity) as the sender. The probe to  has access to the message    and ,  which allows differential behavior based on the name (hence number of  delivery attempts) or age (time in queue) of messages. And since   operates by optionally overriding for a delivery attempt  (but not in the underlying message file on disk!) delivery attempt  aspects such as envelope From address, credentials, and remote server  (and port) to which to connect, then message aspects such as original  envelope From, and recipient destination domain remain present in a  message file that has failed delivery attempts, still  available for  "normal" use should one wish the MTA to "fall back"  to attempting a normal delivery without regard to the purported remote  identity. AUTH_ACCESS mapping example: third party submission incorporates such checks both on the number of  delivery attempts, as well as the age (time in queue) of a message, in  order to "fall back" to "normal" delivery (stop  attempting the remote identity submission) after some elapsed time and  number of attempts.

AUTH_ACCESS mapping example: third party submission
 AUTH_ACCESS ! The following three entries detect the three cases, respectively: !  (1) no MAIL FROM AUTH= parameter !  (2) no username (message submitted without SMTP AUTH use) !  (3) MAIL FROM AUTH= parameter matches username ! These are three cases where DUE TO INHERENT FEATURES of the original ! message submission, the message will be sent "normally" (no ! special action taken). !   tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x7c;&#x2a;&#x7c;&#x2a;          $Y tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x7c;&#x2a;         $Y tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;$3&#x2a;&#x7c;&#x2a;      $Y ! ! Now at the case where the MAIL FROM AUTH= parameter differs from the username. ! ! The following entry uses the subsidiary mapping table X-FILE-IS-OLD to  ! check whether the message is "old" either in terms of retries (has had three  ! or more delivery attempts) or in terms of time-in-queue (has been in the MTA  ! queue for more than 3 hours). If the message file is "old" in either sense, ! presumably due to trouble performing the remote identity submission, ! then "fall back" to sending the message "normally" (no further remote ! identity submission attempts). That is, detect the case of a message where ! third party submission seemed appropriate and was attempted, but DUE TO ! OPERATIONAL TROUBLE with the third party submission, it is now desired to  ! "fall back" to "normal" delivery. !   tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;   $C$&#x7c;X-FILE-IS-OLD;$0$&#x7c;$1&#x7c;$Y ! ! If the X-FILE-IS-OLD mapping check "failed" (the message file is still fresh), ! then fall through (continue) with the same input probe. ! So look up the authenticated sender identity in the user LDAP directory and ! check a special mailRemoteIdentity attribute to see whether that sender ! should be allowed to try sending with that AUTH= parameter. ! ! Step (1): Find the base DN for the domain of the authenticated sender ! (username): !   tcp_local&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;$&#x2a;&#x2a;@&#x2a;&#x7c;&#x2a;     $C&#x7c;BDN&#x7c;$}$5,_base_dn_{&#x7c;$3&#x7c;$4@$5 ! ! Step (2): If the base DN was found, then the probe is now !  &#x7c;BDN&#x7c;&#x3c;username-domain-baseDN&#x3e;&#x7c;&#x3c;auth-param&#x3e;&#x7c;&#x3c;username&#x3e; ! The following entry checks for a user entry whose canonical address or some ! alias is the authenticated sender address, with a mailRemoteIdentity ! matching the AUTH= parameter. !   &#x7c;BDN&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;   \ $C&#x7c;LYES&#x7c;$1&#x7c;$&#x5d;ldap:///$0?mail?sub?(&(&#x7c;(mail=$=$2$_)(mailAlternateAddress=$=$2$_)(mailRemoteIdentity=$=$1$_))&#x5b; !  ! If the &#x3c;username&#x3e; user indeed has a mailRemoteIdentity value of the  ! MAIL FROM AUTH= parameter, then the probe is now  !   &#x7c;LYES&#x7c;&#x3c;auth-param&#x3e;&#x7c;&#x3c;username&#x3e;  ! If not, then the probe is still  !   &#x7c;BDN&#x7c;&#x3c;username-domain-baseDN&#x3e;&#x7c;&#x3c;auth-param&#x3e;&#x7c;&#x3c;username&#x3e;  !  ! For the "not" (still &#x7c;BDN&#x7c;...) case, send the message "normally"  !      &#x7c;BDN&#x7c;&#x2a;     $Y  !  ! Step (3): For the &#x7c;LYES&#x7c;... case, now look up the &#x3c;auth-param&#x3e; in the external  ! LDAP directory, assumed to have a structure of external user identities  ! stored under their respective domains, with attributes in the external  ! user entries including:  !  mail: &#x3c;remote-user-address-as-in-AUTH-param&#x3e; ! username: &#x3c;remote-username&#x3e; ! password: &#x3c;remote-password&#x3e; ! submittor: &#x3c;local-username&#x3e; ! ! This entry is checking under the domain of the &#x3c;auth-param&#x3e; for an entry ! with mail=&#x3c;auth-param&#x3e; and submittor=&#x3c;username&#x3e; (&#x3c;username&#x3e; being the local ! username), and if there is such a match returning the username and password ! attribute values. !   &#x7c;LYES&#x7c;&#x2a;@&#x2a;&#x7c;&#x2a;  \ $C&#x7c;RYES&#x7c;$0@$1&#x7c;$&#x5d;extldap:///dc=$1?username?one?(&(mail=$=$0@$1$_)(submittor=$=$2$_))&#x5b;&#x7c;\ $&#x5d;extldap:///dc=$1?password?one?(&(mail=$=$0@$1$_)(submittor=$=$2$_))&#x5b; ! ! Step (4): If the above succeeded, the probe is now: !  &#x7c;RYES&#x7c;&#x3c;auth-param&#x3e;&#x7c;&#x3c;remote-username&#x3e;&#x7c;&#x3c;remote-password&#x3e; ! so now connect to the submit port (587) of a server for the &#x3c;auth-param&#x3e; ! domain, using smtps:, overriding the original envelope From to instead use ! the &#x3c;auth-param&#x3e; value, and supplying the credentials (remote username ! and remote password) that were found with the extldap: lookups. !   &#x7c;RYES&#x7c;&#x2a;@&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;     $F$Q$D$P$S&#x7c;$0@$1&#x7c;&#x7c;$2&#x7c;$3&#x7c;$1&#x7c;587 ! ! If the extldap: lookups didn&#x27;t succeed, so the probe is still &#x7c;LYES&#x7c;... , ! send the message "normally" (original From, etc.): !   &#x7c;LYES&#x7c;&#x2a;        $Y X-FILE-IS-OLD ! The X-FILE-IS-OLD mapping table expects a probe of the form: !  &#x3c;filename&#x3e;&#x7c;&#x3c;seconds-in-queue&#x3e; ! If the filename begins with other than ZZ..., ZY..., or ZX..., or if ! the &#x3c;seconds-in-queue&#x3e; is greater than 3 hours, then the ! mapping returns $Y; otherwise the mapping returns $N. ! When used in a callout from another mapping table, this means that an ! X-FILENAME-IS-OLD callout will only "succeed" if the file was "old". %%&#x2a;&#x7c;&#x2a; \ $`("$0"!="Z"$ &#x7c;&#x7c;$ !find("$1","ZYX")$ &#x7c;&#x7c;$ integer($3)&#x3e;3&#x2a;60&#x2a;60)?"$$Y":"$$N"&#x27;

See also:
 * MX_ACCESS mapping table
 * IP_ACCESS mapping table
 * mapping_paranoia MTA Option
 * maysaslclient Option
 * mustsaslclient Option
 * SSL_CLIENT
 * defaultmx Option
 * randommx Option
 * lastresort Option
 * musttlsclient Option
 * mustsaslclient Option
 * saslpassauth Option
 * sasltrustauth Option
 * LDAP external directory lookup MTA options
 * TCPIP channels