Provisioning

Provisioning creates users, groups, roles, ACLs and nodes reproducibly from declarative YAML descriptors. It runs as part of Session.deploy() at each workspace's startup and is idempotent (re-applying produces the same result).

Directory layout

<workspace>/etc/jcr/
├── jcr.yml         # repository bootstrap (defaultNodes, security)
├── deploy/         # file content mirrored into the repository
└── provisioning/   # declarative identity & ACL descriptors
    ├── commerce.yml   # one file per application
    └── ...

All *.yml / *.yaml files in provisioning/ are loaded in lexical order. Each application can ship its own file, so you add things independently without editing a shared file.

Order & idempotency

Sections are applied in phases so cross-references resolve:

namespaces → roles → groups → users → nodes

• namespaces — registered only when absent; a prefix/URI already bound differently is reported as a conflict rather than remapped
• principals (users/groups/roles) — created only when absent. Passwords are never reset; existing principals are not modified
• ACEs — added only when an equivalent entry is not already present

Target workspace per section

Descriptor examples

namespaces

namespaces:
  - prefix: acme
    uri: http://www.example.com/acme/1.0

roles / groups

roles:
  - id: administrator
    displayName: Administrators
    description: Built-in administrators

groups:
  - id: commerce-operators
    displayName: Commerce Operators

id can be hierarchical (e.g. ops/readonly); declare parents before children.

users

users:
  - id: alice
    password: changeit
    displayName: Alice Smith
    mail: alice@example.com
    enabled: true
    roles: [administrator]
    memberOf: [commerce-operators]

  - id: commerce-service-user
    service: true
    displayName: Commerce Service
    memberOf: [commerce-service-group]

service: true marks a service account — it has no password and cannot sign in (used by integrations via runAs).

nodes & acl

nodes:
  - path: /content/commerce
    primaryType: nt:folder
    acl:
      - group: commerce-operators
        privileges: jcr:read, jcr:write
        effect: allow
      - user: anonymous
        privileges: [jcr:all]
        effect: deny

Each ACL entry names exactly one grantee — group, user or principal — with privileges (comma-separated string or YAML list) and effect (allow / deny).

Cautions

• A redeploy does not change an existing user's password or attributes. Make those changes in Identity Manager.
• jcr.yml#defaultNodes only runs at first node creation and cannot create identity. Use provisioning descriptors for reproducible creation.