AUTH_ACCESS mapping table

From Messaging Server Technical Reference Wiki
Jump to: navigation, search



New in 7.0.5 is the AUTH_ACCESS 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 IP_ACCESS mapping, AUTH_ACCESS is consulted prior to MX record lookups.) The AUTH_ACCESS mapping allows control or override of various SMTP session level features.

The default probe for the AUTH_ACCESS mapping is of the form:

channel|filename|queue-time|envelope-from|auth-parameter|username|domain

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

New in MS 8.0.2.2, If bit 11, value 2048, of the include_conversiontag MTA option is set the probe changes to include the conversion tag for the message:

channel|filename|queue-time|envelope-from|auth-parameter|username|conversiontag|domain

New in MS 8.0.2.3, if bit 0, value 1, of the include_retries MTA option is set the probe changes to include the count of previous retries for the message:

channel|filename|retry-count|queue-time|envelope-from|auth-parameter|username|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 flags.

AUTH_ACCESS mapping flags
Flag Fields Description
$U   Enable SMTP client debugging for this transaction. No fields are consumed.
$n error-text (New in MS 8.0.2.3.) Abort this connection attempt for this message. One field is used to specify the error text. No further processing of the mapping result is performed.
$N error-text Permanently fail the first recipient of the message and return a DSN. The delivery operation continues with the next recipient. The entire message fails if there is only one remaining recipient. One field is used to specify the error text. No further processing of the mapping result is performed.
$F env-from Override the message's envelope From address. One field is used to specify that address.
$A auth-param Override the MAIL FROM AUTH= parameter. One field is used to specify the override value.
$Q authorization|username|password Override the credentials used for PLAIN authentication. Three fields are consumed with use of this flag: the first specifies an authorization identity (normally left blank), the second specifies an authentication identity (the "username"), and the third specifies a password.
$/   Treat a PLAIN authentication attempt failure as an SMTP temporary failure. (Normally, when this flag is not set, such an authentication failure is instead treated as: ignored when maysaslclient is in effect, vs. causing an SMTP permanent failure (bounce) when mustsaslclient is in effect.)
$D host Override the DNS name of the server to which the message will be sent. One field is used to specify the new DNS name. (Note that use of this flag causes the TCP/IP-channel-specific option SSL_CLIENT to be ignored; instead use $S to enable smtps: use.)
$P port Override the value of the port channel option (default 25). One field is used to specify the new port number. (Note that use of this flag causes the TCP/IP-channel-specific option SSL_CLIENT to be ignored; instead use $S to enable smtps: use.)
$S   Enables the use of TLS (smtps:). No fields are consumed. Note that this flag enables smtps: use even when $D or $P has also been used.
$X   Disable MX lookups for connection establishment (overriding any channel *mx channel option setting). No fields are consumed.
$M   Enable MX lookups for connection establishment (overriding any channel *mx keyword setting); the effect is randommx MX record use. No fields are consumed.
$B lastresort-server Set a lastresort value, overriding the value specified by the lastresort channel option. One field is consumed as the lastresort server name.
$T   Force musttlsclient on for this message. No fields are consumed.
$H   Disable TLS for this message. No fields are consumed.
$G   Force mustsaslclient on for this message. No fields are consumed.
$I   Disable SASL for this message. No fields are consumed.
$J interface-address (New in 8.0.2.2) Use the specified value as the source IP address. A single field containing the IP address to use is consumed. If a connection is currently open it will be closed unless the interface address has not changed.
$+. host-name (New in 8.0.2.3) Use the specified value as the host name in any EHLO/HELO/LHLO command that the client issues. A single field containing the banner host name is consumed.
$V skip-count (New in 8.0.2.3) Specify a new skip count to be encoded in the queue file name for the message. This flag is used by the smartsend plugin and is not intended for other purposes. One field containing an unsigned integer skip value is consumed.
$+R attempt-count (New in 8.0.2.3) Specify an override value for the ATTEMPT_TRANSACTION_PER_SESSION TCP/IP-specific channel option. A single field containing the override value is consumed.
$( max-mx-count (New in 8.0.2.3) Specify an override value for the MAX_MX_RECORDS TCP/IP-specific channel option. A single field containing the override value is consumed.
$+% backoff-time (New in 8.0.2.3) Specify an override value for the backoff time in the event this delivery attempt fails with a temporary error. A single field containing the time in seconds is consumed.
$, deaccess-parameter-string (New in 8.0.2.3) Specify the deaccess parameter string to pass to the AUTH_DEACCESSS mapping. Note that this consumes all remaining arguments in the mapping result stirng.
$Y   Perform no special overrides and send message normally. This explicit "no-op" result is useful for specifying mapping table match cases that cause SMTP client processing to proceed normally. No fields are consumed.
Input flag comparisons Description
$:| Match only if external material (e.g., the envelope From address) in the probe contained a vertical bar
$;| Match only if no vertical bars were present in any external material in the probe
$:S (New in MS 8.0.2.3) Match only if a connection to the destination for this message is already open and is going to be reused.
$;S (New in MS 8.0.2.3) Match only if no SMTP connection is open or if one is open it is going to be closed prior to processing this message.
$:T (New in MS 8.0.2.3) Match only if STARTTLS is allowed or required for this connection
$;T (New in MS 8.0.2.3) Match only if STARTTLS is not allowed for this connection.
$:U (New in MS 8.0.2.3) Match only if smtps: is allowed or required for this connection
$;U (New in MS 8.0.2.3) Match only if smtps: is not allowed for this connection.

The AUTH_ACCESS 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 adam.brown@local.domain.com also has a remote identity and mailbox as abrown@remote.domain.com, 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's normal, local address as the envelope From, but with a MAIL FROM AUTH= parameter set to the remote address. Then an AUTH_ACCESS 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|*|*|adam.brown@local.domain.com|abrown@remote.domain.com|$*adam.brown@local.domain.com|*  \
$Fabrown@remote.domain.com|$Q|abrown@remote.domain.com|remotepassword|$/$Dremote.domain.com|$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 AUTH_ACCESS mapping, then a more real-world example might also include storing such users' 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's LDAP entry is checked for whether a value of a special LDAP attribute, here assumed to be mailRemoteIdentity, 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, mailRemoteIdentity 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 AUTH_ACCESS has access to the message filename and queue-time, which allows differential behavior based on the name (hence number of delivery attempts) or age (time in queue) of messages. And since AUTH_ACCESS 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|*|*|*||*|*          $Y 
  tcp_local|*|*|*|*||*          $Y 
  tcp_local|*|*|*|*|$3*|*       $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|*|*|*|*|*|*   $C$|X-FILE-IS-OLD;$0$|$1|$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|*|*|*|*|$**@*|*     $C|BDN|$}$5,_base_dn_{|$3|$4@$5 
! 
! Step (2): If the base DN was found, then the probe is now 
!   |BDN|<username-domain-baseDN>|<auth-param>|<username> 
! 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. 
! 
  |BDN|*|*|*   \
$C|LYES|$1|$]ldap:///$0?mail?sub?(&(|(mail=$=$2$_)(mailAlternateAddress=$=$2$_)(mailRemoteIdentity=$=$1$_))[ 
! 
! If the <username> user indeed has a mailRemoteIdentity value of the 
! MAIL FROM AUTH= parameter, then the probe is now 
!   |LYES|<auth-param>|<username> 
! If not, then the probe is still 
!   |BDN|<username-domain-baseDN>|<auth-param>|<username> 
! 
! For the "not" (still |BDN|...) case, send the message "normally" 
!  
   |BDN|*     $Y 
! 
! Step (3): For the |LYES|... case, now look up the <auth-param> 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: <remote-user-address-as-in-AUTH-param> 
!  username: <remote-username> 
!  password: <remote-password> 
!  submittor: <local-username> 
! 
! This entry is checking under the domain of the <auth-param> for an entry 
! with mail=<auth-param> and submittor=<username> (<username> being the local 
! username), and if there is such a match returning the username and password 
! attribute values. 
! 
  |LYES|*@*|*  \
$C|RYES|$0@$1|$]extldap:///dc=$1?username?one?(&(mail=$=$0@$1$_)(submittor=$=$2$_))[|\
$]extldap:///dc=$1?password?one?(&(mail=$=$0@$1$_)(submittor=$=$2$_))[ 
! 
! Step (4): If the above succeeded, the probe is now: 
!   |RYES|<auth-param>|<remote-username>|<remote-password> 
! so now connect to the submit port (587) of a server for the <auth-param> 
! domain, using smtps:, overriding the original envelope From to instead use 
! the <auth-param> value, and supplying the credentials (remote username 
! and remote password) that were found with the extldap: lookups. 
! 
  |RYES|*@*|*|*     $F$Q$D$P$S|$0@$1||$2|$3|$1|587 
! 
! If the extldap: lookups didn't succeed, so the probe is still |LYES|... , 
! send the message "normally" (original From, etc.): 
! 
  |LYES|*        $Y 
 
X-FILE-IS-OLD 
! The X-FILE-IS-OLD mapping table expects a probe of the form: 
!   <filename>|<seconds-in-queue> 
! If the filename begins with other than ZZ..., ZY..., or ZX..., or if 
! the <seconds-in-queue> 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". 
  
  %%*|*  \
$`("$0"!="Z"$ ||$ !find("$1","ZYX")$ ||$ integer($3)>3*60*60)?"$$Y":"$$N"' 
 
----


See also: