| 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> or <recoveryCode> 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)"] [tokenType="..."] [productQuery="(0|1)"]> ## AuthRequest
<account by="{acct-selector-by} (adminName | appAdminName | id | foreignPrincipal | name | krb5Principal)">{key}</account> ## AccountSelector
<password>{password} (String)</password>
<recoveryCode>{recoveryCode} (String)</recoveryCode>
<preauth timestamp="(long)" [expires="{expires} (Long)"]>{value}</preauth> ## PreAuth
<authToken [verifyAccount="(0|1)"] [lifetime="(Long)"]>{value}</authToken> ## AuthToken
<jwtToken>{jwtToken} (String)</jwtToken>
<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>
</AuthRequest>
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. |
| @tokenType | Optional (0 or 1) | Type: String type of token to be returned, it can be auth or jwt |
| @productQuery | Optional (0 or 1) | Type: 0|1 either provide `productQuery` in response or not, productQuery return information about product Information example: for now only `productName` is returned. 0: (default) do not include `productQuery` information in the response. 1: include `productQuery` information in the response. |
| /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 |
| /recoveryCode | Optional (0 or 1) | Type: {recoveryCode} (String) RecoveryCode to use in conjunction with an account in case of forgot password flow. |
| /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 |
| /jwtToken | Optional (0 or 1) | Type: {jwtToken} (String) JWT 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 "" |
<AuthResponse> ## AuthResponse
<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>
<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>
<csrfToken>{csrfToken} (String)</csrfToken>
</AuthResponse>
elements and attributes you can define within a
<AuthResponse> element:
| XPath | Required / Optional | Description |
| /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 "" |
| /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. |
| /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 . |