Overview | Service | Command |
Authenticate for an account
Authorization token required | false - can't require auth on auth request |
Admin Authorization token required | false |
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 [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. |