1/20/2016 - 5:03 PM

zimbra-autoprov.md

Rendered
Source

[ZIMBRA] Auto provisioning

available with version 8.x+

Use Case

When using an external LDAP directory (example: Microsoft Active Directory) as the authoritative source for account provisioning, streamline the process of creating the mailbox account and populating GAL attributes.

Assumption :

An external authentication mechanism (i.e. preauth or SSO) has been configured on the zimbra domain.
User A exists in the external source directory for auto provisioning

Auto Provisioning modes

(1) LAZY mode: Zimbra provisions the mailbox for User A on first login.

(2) EAGER mode: Zimbra provisions the mailbox for User A automatically in a background thread.

(3) MANUAL mode: Helpdesk Person searches the external source directory for accounts to be auto provisioned, then select the account(s) to auto provision.

In all three modes, account information (account name, first name, last name, etc) is populated based on attribute mapping configuration from the external source directory to Zimbra directory. Multiple modes can coexist.

Auto provision attributes

All auto provisioning are on domain level.

zimbraAutoProvMode:

- type "enum"
- value "EAGER, LAZY, MANUAL"
- cardinality "multi"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

Auto provision modes enabled.
Multiple modes can be enabled on a domain.

EAGER: A server maintenance thread automatically polls the configured external auto provision LDAP source at a configured interval for
entries due to be auto provisioned in Zimbra, and then auto creates the accounts in Zimbra directory.

LAZY: auto creates the Zimbra account when user first login via one of the external auth mechanisms enabled for auto provisioning. Auth mechanisms enabled for auto provisioning are configured in zimbraAutoProvAuthMech.

MANUAL: admin to search from the configured external auto provision LDAP source and select an entry from the search result to create the corresponding Zimbra account for the external entry.

In all cases, localpart of the Zimbra account is mapped from an attribute on the external entry based on zimbraAutoProvAccountNameMap.

The Zimbra account is populated with attributes mapped from the external entry based on zimbraAutoProvAttrMap.

examples:

enable auto provision in EAGER mode :

$ zmprov md test.com zimbraAutoProvMode EAGER

enable auto provision in LAZY and MANUAL mode :

$ zmprov md test.com +zimbraAutoProvMode LAZY +zimbraAutoProvMode MANUAL

zimbraAutoProvAuthMech:

 - type "enum"
 - value "LDAP,PREAUTH,KRB5,SPNEGO"
 - cardinality "multi"
 - optionalIn "domain"
 - Exposed in admin console: NO

Description:

 EAGER mode: N/A
  LAZY mode: required
MANUAL mode: N/A

Auth mechanisms enabled for auto provision in LAZY mode.

When a user authenticates via one of the external auth mechanisms enabled in this attribute, and when the user account does not yet exist in Zimbra directory, an account entry will be automatically created in Zimbra directory.

examples:

enable LAZY auto provision for users login via preauth :

$ zmprov md test.com zimbraAutoProvAuthMech PREAUTH

enable LAZY auto provision for users login via external ldap(including ad) auth :

$ zmprov md test.com zimbraAutoProvAuthMech LDAP

enable LAZY auto provision for users login via preauth or kerberos auth :

$ zmprov md test.com +zimbraAutoProvAuthMech PREAUTH +zimbraAutoProvAuthMech KRB5

zimbraAutoProvLdapURL:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: required
MANUAL mode: required

LDAP URL of the external LDAP source for auto provision.

examples:

zmprov md test.com zimbraAutoProvLdapURL "ldap://autoprov.source.com:389"

zimbraAutoProvLdapStartTlsEnabled:

- type "boolean"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Default is FALSE.

Whether to use startTLS when accessing the external LDAP server for auto provision.

examples:

$ zmprov md test.com zimbraAutoProvLdapStartTlsEnabled TRUE

zimbraAutoProvLdapAdminBindDn:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: required (if using zimbraAutoProvLdapSearchFilter)
MANUAL mode: required

LDAP search bind DN for auto provision.

examples:

$ zmprov md test.com zimbraAutoProvLdapAdminBindDn "cnadmin,dcautoprov,dccompany,dccom"

zimbraAutoProvLdapAdminBindPassword:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: required
MANUAL mode: required

LDAP search bind password for auto provision.

examples:

$ zmprov md test.com zimbraAutoProvLdapAdminBindPassword secret

zimbraAutoProvLdapSearchBase:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: required (if using zimbraAutoProvLdapSearchFilter),
MANUAL mode: required

LDAP search base for auto provision, used in conjunction with zimbraAutoProvLdapSearchFilter.

If not set, LDAP root DSE will be used.

examples:

$ zmprov md test.com zimbraAutoProvLdapSearchBase "dcautoprov,dccompany,dccom"

zimbraAutoProvLdapSearchFilter

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: optional (if not using zimbraAutoProvLdapBindDn)
MANUAL mode: optional (if not using zimbraAutoProvLdapBindDn)

LDAP search filter template for account auto provisioning.

For LAZY and MANUAL modes, either zimbraAutoProvLdapSearchFilter or zimbraAutoProvLdapBindDn has to be set.

If both are set, zimbraAutoProvLdapSearchFilter will take precedence.

Supported place holders:

%n  username with @ (or without, if no @ was specified)
%u  username with @ removed
%d  domain as foo.com
%D  domain as dcfoo,dccom

examples:

$ zmprov md test.com zimbraAutoProvLdapSearchFilter "(uid%u)"

zimbraAutoProvLdapBindDn:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: optional (if not using zimbraAutoProvLdapSearchFilters)
MANUAL mode: optional (if not using zimbraAutoProvLdapSearchFilters)

LDAP external DN template for account auto provisioning.

For LAZY and MANUAL modes, either zimbraAutoProvLdapSearchFilter or zimbraAutoProvLdapBindDn has to be set.

If both are set, zimbraAutoProvLdapSearchFilter will take precedence.

Supported place holders:

%n  username with @ (or without, if no @ was specified)
%u  username with @ removed
%d  domain as foo.com
%D  domain as dcfoo,dccom

examples:

$ zmprov md test.com zimbraAutoProvLdapBindDn "uid%u,oupeople,%D"

zimbraAutoProvAccountNameMap:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: optional
MANUAL mode: optional

Attribute name in the external directory that contains localpart of the account name.

If not specified, localpart of the account name is the principal user used to authenticated to Zimbra.

examples:

use the uid value on the external entry for localpart of the account name to be provisioned in Zimbra

$ zmprov md test.com zimbraAutoProvAccountNameMap uid

zimbraAutoProvAttrMap:

- type "string"
- max "256"
- cardinality "multi"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Attribute map for mapping attribute values from the external entry to Zimbra account attributes.

Values are in the format of {external attribute}{zimbra attribute}.

If not set, no attributes from the external directory will be populated in Zimrba directory.

Invalid mapping configuration will cause the account creation to fail.

Examples of bad mapping:

    invalid external attribute name.
    invalid Zimbra attribute name.
    external attribute has multiple values but the zimbra attribute is singlevalued.
    syntax violation.  e.g. Value on the external attribute is a String but the Zimbra
    attribute is declared an integer.

examples:

- map "sn" value on the external entry to "displayName" on the Zimbra account,
- and map "description" value on the external entry to "description" on the Zimbra account.

$ zmprov md test.com +zimbraAutoProvAttrMap sndisplayName +zimbraAutoProvAttrMap descriptiondescription

zimbraAutoProvNotificationFromAddress:

- type "string"
- max "256"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Email address to put in the From header for the notification email to the newly created account.

If not set, no notification email will sent to the newly created account.

examples:

$ zmprov md test.com zimbraAutoProvNotificationFromAddress provadmin@test.com

zimbraAutoProvNotificationSubject:

- type "string"
- cardinality "single"
- optionalIn "globalConfig,domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Template used to construct the subject of the notification message sent to the user when the user's account is auto provisioned.

Supported variables:

${ACCOUNT_ADDRESS}
${ACCOUNT_DISPLAY_NAME}

examples:

$ zmprov md test.com zimbraAutoProvNotificationSubject \
> "New account auto provisioned for ${ACCOUNT_DISPLAY_NAME}"

zimbraAutoProvNotificationBody:

- type "string"
- cardinality "single"
- optionalIn "globalConfig,domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Template used to construct the subject of the notification message sent to the user when the user's account is auto provisioned.

Supported variables:

${ACCOUNT_ADDRESS}
${ACCOUNT_DISPLAY_NAME}

examples:

$ zmprov md test.com zimbraAutoProvNotificationBody \
> "Your account ${ACCOUNT_ADDRESS} has been auto provisioned"

zimbraAutoProvListenerClass:

- type "string"
- max "1024"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: optional
  LAZY mode: optional
MANUAL mode: optional

Class name of auto provision listener.

The class must implement the com.zimbra.cs.account.Account.AutoProvisionListener interface.

The singleton listener instance is invoked after each account is auto created in Zimbra.

Listener can be plugged in as a server extension to handle tasks like updating the account auto provision status in the external LDAP directory.

At each eager provision interval, ZCS does an LDAP search based on the value configured in zimbraAutoProvLdapSearchFilter.

Returned entries from this search are candidates to be auto provisioned in this batch.

The zimbraAutoProvLdapSearchFilter should include an assertion that will only hit entries in the external directory that have not yet been provisioned in ZCS, otherwise it's likely the same entries will be repeated pulled in to ZCS.

After an account is auto provisioned in ZCS, com.zimbra.cs.account.Account.AutoProvisionListener.postCreate(Domain domain, Account acct, String externalDN) will be called by the auto provisioning framework.

Customer can implement the AutoProvisionListener interface in a ZCS server extension and get their AutoProvisionListener.postCreate() get called.

The implementation of customer's postCreate method can be, for example, setting an attribute in the external directory on the account just provisioned in ZCS.

The attribute can be included as a condition in the zimbraAutoProvLdapSearchFilter, so the entry won't be returned again by the LDAP search in the next interval.

examples:

$ zmprov md test.com zimbraAutoProvListenerClass com.company.PostAutoProvision

zimbraAutoProvBatchSize:

- type "integer"
- cardinality "single"
- optionalIn "domain,globalConfig"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: N/A
MANUAL mode: N/A

Max number of accounts to process in each interval for EAGER auto provision.

examples:

$ zmprov md test.com zimbraAutoProvBatchSize 20

zimbraAutoProvLastPolledTimestamp:

- type "gentime"
- cardinality "single"
- optionalIn "domain"
- Exposed in admin console: NO

Description:

 EAGER mode: for Zimbra internal use only  do not change it.
  LAZY mode: N/A
MANUAL mode: N/A

Timestampt when the external domain is last polled for EAGER auto provision.

The poll (LDAP search) for the next iteration will fetch external entries with create timestamp later than the timestamp recorded from the previous iteration.

zimbraAutoProvLock:

- type "string"
- cardinality "single"
- optionalIn"domain"
- Exposed in admin console: NO

Description:

 EAGER mode: for Zimbra internal use only  do not change it.
  LAZY mode: N/A
MANUAL mode: N/A

For EAGER auto provision, a domain can be scheduled on multiple server. To avoid conflict, only one server can perform provisioning for a domain at one time. This attribute servers a lock for the testandset LDAP operation to shchronize EAGER auto provision attempts between servers.

zimbraAutoProvScheduledDomains:

- type "string"
- cardinality "multi"
- optionalIn "server"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: N/A
MANUAL mode: N/A

Domain scheduled for eager auto provision on this server.

Scheduled domains must have EAGER mode enabled in zimbraAutoProvMode.

Multiple domains can be scheduled on a server for EAGER auto provision.

Also, a domain can be scheduled on multiple servers for EAGER auto provision.

examples:

schedule domain1.com and domain2.com for EAGER auto provision on server server.com

$ zmprov ms server.com \
> +zimbraAutoProvScheduledDomains domain1.com \
> +zimbraAutoProvScheduledDomains domain2.com

zimbraAutoProvPollingInterval:

- type "duration"
- cardinality "single"
- optionalIn "server,globalConfig"
- Exposed in admin console: NO

Description:

 EAGER mode: required
  LAZY mode: N/A
MANUAL mode: N/A

Interval between successive polling and provisioning accounts in EAGER mode.

The actual interval may take longer since it can be affected by two other factors: zimbraAutoProvBatchSize and number of domains configured in zimbraAutoProvScheduledDomains.

At each interval, the auto provision thread iterates through all domains in zimbraAutoProvScheduledDomains and auto creates up to domain.zimbraAutoProvBatchSize accounts.

If that process takes longer than zimbraAutoProvPollingInterval then the next iteration will start immediately instead of waiting for zimbraAutoProvPollingInterval amount of time.

If set to 0 when server starts up, the auto provision thread will not start.

If changed from a non0 value to 0 while server is running, the auto provision thread will be shutdown.

If changed from 0 to a non0 value while server is running, the auto provision thread will be started.

examples:

set polling interval for EAGER auto provision to 15 minutes

$ zmprov ms server.com zimbraAutoProvPollingInterval 15m

source: file zimbra/docs/autoprov.txt

Cacher is the code snippet organizer for pro developers

We empower you and your team to get more done, faster

zimbra-autoprov.md

[ZIMBRA] Auto provisioning

Use Case

Auto Provisioning modes

Auto provision attributes