Service: zimbraAccount
Namespace: "urn:zimbraAccount"
Auth SOAP Command

Authenticate for an account

Authorization token required false - can't require auth on auth request
Admin Authorization token required false

AuthRequest

when specifying an account, one of <password> or <preauth> must be specified. See preauth.txt for a discussion of preauth.
An authToken can be passed instead of account/password/preauth to validate an existing auth token. If {verifyAccount}="1", <account> is required and the account in the auth token is compared to the named account.
Mismatch results in auth failure. An external app that relies on ZCS for user identification can use this to test if the auth token provided by the user belongs to that user. If {verifyAccount}="0" (default), only the auth token is verified and any <account> element specified is ignored.

    <AuthRequest [persistAuthTokenCookie="(0|1)"] [csrfTokenSecured="(0|1)"] [deviceTrusted="(0|1)"]
                    [generateDeviceId="(0|1)"]> ## AuthRequest
        <account by="{acct-selector-by} (adminName|appAdminName|id|foreignPrincipal|name|krb5Principal)">{key}</account> ## AccountSelector
        <password>{password} (String)</password>
        <preauth timestamp="(long)" [expires="{expires} (Long)"]>{value}</preauth> ## PreAuth
        <authToken [verifyAccount="(0|1)"] [lifetime="(Long)"]>{value}</authToken> ## AuthToken
        <virtualHost>{virtualHost} (String)</virtualHost>
        <prefs>
            (<pref name="{pref-name}" [modified="{pref-modified-time} (Long)"]>{value}</pref> ## Pref)*
        </prefs>
        <attrs>
            (<attr name="{attr-name}" [pd="{attr-perm-denied} (0|1)"]>{value}</attr> ## Attr)*
        </attrs>
        <requestedSkin>{requestedSkin} (String)</requestedSkin>
        <twoFactorCode>{twoFactorCode} (String)</twoFactorCode>
        <trustedToken>{trustedDeviceToken} (String)</trustedToken>
        <deviceId>{deviceId} (String)</deviceId>
    </AuthRequest>

The following table describes elements and attributes you can define within a <AuthRequest> element:

XPath Required / Optional Description
@persistAuthTokenCookie Optional (0 or 1) Type:0|1
controls whether the auth token cookie in the response should be persisted when the browser exits.
0: (default)
the cookie will be deleted when the Web browser exits.
1: The "Expires" attribute of the cookie will be set per rfc6265.
@csrfTokenSecured Optional (0 or 1) Type:0|1
controls whether the client supports CSRF token
0: (default)
Client does not support CSRF token
1: The client supports CSRF token.
@deviceTrusted Optional (0 or 1) Type:0|1
whether the client represents a trusted device
@generateDeviceId Optional (0 or 1) Type:0|1
/account Optional (0 or 1) Type:{key}
Specifies the account to authenticate against
Description for element text content:The key used to identify the account. Meaning determined by {acct-selector-by}
/account@by Required (only 1) Type:adminName|appAdminName|id|foreignPrincipal|name|krb5Principal
Select the meaning of {acct-selector-key}
/password Optional (0 or 1) Type:{password} (String)
Password to use in conjunction with an account
/preauth Optional (0 or 1) Type:{value}
<preauth> is an alternative to <account>. See preauth.txt
Description for element text content:Computed preauth value
/preauth@timestamp Required (only 1) Type:long
Time stamp
/preauth@expires Optional (0 or 1) Type:Long
expiration time of the authtoken, in milliseconds. set to 0 to use the default expiration time for the account. Can be used to sync the auth token expiration time with the external system's notion of expiration (like a Kerberos TGT lifetime, for example).
/authToken Optional (0 or 1) Type:{value}
An authToken can be passed instead of account/password/preauth to validate an existing auth token. If {verifyAccount}="1", <account> is required and the account in the auth token is compared to the named account. Mismatch results in auth failure. An external app that relies on ZCS for user identification can use this to test if the auth token provided by the user belongs to that user. If {verifyAccount}="0" (default), only the auth token is verified and any <account> element specified is ignored.
Description for element text content:Value for authorization token
/authToken@verifyAccount Optional (0 or 1) Type:0|1
If verifyAccount="1", <account> is required and the account in the auth token is compared to the named account. If verifyAccount="0" (default), only the auth token is verified and any <account> element specified is ignored.
/authToken@lifetime Optional (0 or 1) Type:Long
Life time of the auth token
/virtualHost Optional (0 or 1) Type:{virtualHost} (String)
if specified (in conjunction with by="name"), virtual-host is used to determine the domain of the account name, if it does not include a domain component. For example, if the domain foo.com has a zimbraVirtualHostname of "mail.foo.com", and an auth request comes in for "joe" with a virtualHost of "mail.foo.com", then the request will be equivalent to logging in with "joe@foo.com".
/prefs Required (only 1)
/prefs/pref Optional (0 or more) Type:{value}
Description for element text content:Preference value
/prefs/pref@name Required (only 1) Type:String
Preference name
/prefs/pref@modified Optional (0 or 1) Type:Long
Preference modified time (may not be present)
/attrs Required (only 1)
/attrs/attr Optional (0 or more) Type:{value}
Description for element text content:Value of attribute
/attrs/attr@name Required (only 1) Type:String
Name of attribute
/attrs/attr@pd Optional (0 or 1) Type:0|1
Flags whether permission has been denied (optional).
If 1 (true), flags that the real value of this attribute has not been provided.
The value is set to ""
/requestedSkin Optional (0 or 1) Type:{requestedSkin} (String)
if specified the name of the skin requested by the client
/twoFactorCode Optional (0 or 1) Type:{twoFactorCode} (String)
the TOTP code used for two-factor authentication
/trustedToken Optional (0 or 1) Type:{trustedDeviceToken} (String)
whether the client represents a trusted device
/deviceId Optional (0 or 1) Type:{deviceId} (String)
unique device identifier; used to verify trusted mobile devices

AuthResponse

    <AuthResponse [zmgProxy="(0|1)"]> ## AuthResponse
        <authToken>{authToken} (String)</authToken>
        <lifetime>{lifetime} (long)</lifetime>
        <trustLifetime>{trustLifetime} (Long)</trustLifetime>
        <session [type="{session-type}"] id="{id}">{sessionId}</session> ## Session
        <refer>{refer} (String)</refer>
        <skin>{skin} (String)</skin>
        <csrfToken>{csrfToken} (String)</csrfToken>
        <deviceId>{deviceId} (String)</deviceId>
        <trustedToken>{trustedToken} (String)</trustedToken>
        <prefs>
            (<pref name="{pref-name}" [modified="{pref-modified-time} (Long)"]>{value}</pref> ## Pref)*
        </prefs>
        <attrs>
            (<attr name="{attr-name}" [pd="{attr-perm-denied} (0|1)"]>{value}</attr> ## Attr)*
        </attrs>
        <twoFactorAuthRequired /> ## 0|1
        <trustedDevicesEnabled /> ## See /twoFactorAuthRequired [ ## 0|1]
    </AuthResponse>

The following table describes elements and attributes you can define within a <AuthResponse> element:

XPath Required / Optional Description
@zmgProxy Optional (0 or 1) Type:0|1
indicates whether the authentication account acts as a "Proxy" to a Zimbra account on another system.
/authToken Required (only 1) Type:{authToken} (String)
The authorization token
/lifetime Required (only 1) Type:{lifetime} (long)
Life time for the authorization
/trustLifetime Optional (0 or 1) Type:{trustLifetime} (Long)
trust lifetime, if a trusted token is issued
/session Optional (0 or 1) Type:{sessionId}
Session information
Description for element text content:Session ID (same as id)
/session@type Optional (0 or 1) Type:String
Session type - currently only set if value is "admin"
/session@id Required (only 1) Type:String
Session ID
/refer Optional (0 or 1) Type:{refer} (String)
host additional SOAP requests should be directed to. Always returned, might be same as original host request was sent to.
/skin Optional (0 or 1) Type:{skin} (String)
if requestedSkin specified, the name of the skin to use Always returned, might be same as original host request was sent to.
/csrfToken Optional (0 or 1) Type:{csrfToken} (String)
if client is CSRF token enabled , the CSRF token Returned only when client says it is CSRF enabled .
/deviceId Optional (0 or 1) Type:{deviceId} (String)
random secure device ID generated for the requesting device
/trustedToken Optional (0 or 1) Type:{trustedToken} (String)
trusted device token
/prefs Required (only 1)
/prefs/pref Optional (0 or more) Type:{value}
Description for element text content:Preference value
/prefs/pref@name Required (only 1) Type:String
Preference name
/prefs/pref@modified Optional (0 or 1) Type:Long
Preference modified time (may not be present)
/attrs Required (only 1)
/attrs/attr Optional (0 or more) Type:{value}
Description for element text content:Value of attribute
/attrs/attr@name Required (only 1) Type:String
Name of attribute
/attrs/attr@pd Optional (0 or 1) Type:0|1
Flags whether permission has been denied (optional).
If 1 (true), flags that the real value of this attribute has not been provided.
The value is set to ""
/twoFactorAuthRequired Optional (0 or 1)
/trustedDevicesEnabled Optional (0 or 1) See /twoFactorAuthRequired for more details.