> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/sync-identities.md).

# Sync Identities

Create or update user accounts in target systems by synchronizing identity attributes.

Synchronizes identity attributes between systems, with options to:

* Create new identities if they don't exist
* Update attributes of existing identities
* Enable continuous sync to keep attributes aligned with the source of truth

**Example Use Cases:**

* Create new user accounts in target systems when employees join
* Update user attributes when information changes in HR systems
* Ensure consistent user information across multiple platforms

| Setting                             | Description                                                                                                                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Entity Type                         | The data source and type of identity to sync (e.g., Okta User, Azure AD User)                                                                                                        |
| Don't create new users              | When on, identities that don't already exist are skipped. Leave it off (the default) to create a new identity when none is found.                                                    |
| Update only on create or reactivate | When enabled, existing active users aren't modified. Changes apply only when a user is newly created or reactivated. Disable to keep attributes in sync after initial creation.      |
| Common Synced Attributes            | Shared transformation rules across multiple sync actions                                                                                                                             |
| Action Synced Attributes            | Create, format, and modify the specified target attributes. See [Transformers](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/transformers.md) for more details                 |
| Action Unique Identifier            | The attribute Veza uses to locate an existing user when syncing. Defaults to the integration's primary identifier (for SCIM integrations, `userName`)                                |
| Enforce password change on login    | Force newly created users to change their password at first login. Availability varies by target system — see [Enforce password change on login](#enforce-password-change-on-login). |

**Password output (Early Access)**

When password output is enabled, the password generated during identity creation is available to subsequent workflow actions via transformer expressions. Use `{EntityType.password}` syntax to reference it, such as `{OktaUser.password}` in a Send REST Payload action.

This is useful in joiner workflows where Veza provisions a new account and needs to pass the generated password to a downstream system such as an HR portal or ticketing API.

{% hint style="warning" %}
Passwords are passed as plain text to downstream actions. Use this only when the workflow requires it, and ensure receiving endpoints use HTTPS. Passwords are never written to the Veza database. They are available in memory during workflow execution only and are redacted from stored job payloads before persistence.
{% endhint %}

{% hint style="info" %}
**Early Access:** Veza Support enables password output for your tenant on request.
{% endhint %}

## Write back to an identity source

A Sync Identities action can target one of the policy's own identity sources, updating the system of record instead of a downstream application. Use this to push a value the workflow produced, most often an email address, back into an HR system such as Workday.

When you select a target that is also an identity source on the policy, the action switches to write-back mode automatically and shows **Writing back to Identity Source**. In this mode:

* Creating new identities is disabled. A write-back action only updates records that already exist.
* Guest account creation and invitations are hidden.
* The attributes you can map are limited to those the identity source accepts as writable.

Which attributes are writable depends on the integration. Workday, for example, accepts `username` and `email` on the Workday Account entity, and applies the `email` value to the linked worker's primary work email. See [Workday provisioning](/4yItIzMvkpAvMVFAamTf/integrations/integrations/workday/provisioning.md#sync-identities).

To configure one, map the unique identifier plus each attribute you want to write. Veza uses the unique identifier to locate the record, and the action fails if the mapping omits it. For a Workday email write-back, the minimum mapping is `id` and `email`.

{% hint style="info" %}
Writing an email back to an HRIS this way is different from the [Write Back Email](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/write-back-email.md) action. Write Back Email pushes the address a previous action just created and takes no attribute mapping. A write-back Sync Identities action lets you set the attribute to any value with a transformer. See [Choosing between Write Back Email and Sync Identities](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/write-back-email.md#choosing-between-write-back-email-and-sync-identities).
{% endhint %}

### Example: write an Azure AD or Active Directory email to Workday

If a mailbox address is assigned outside Veza after the account exists, the address is available in Veza only after the next extraction of that system. This example writes that address to Workday without submitting an empty email for workers who have no mailbox.

#### Before you start

* Workday is the policy's source of identity, and Lifecycle Management is enabled on the Workday integration. See [Enabling provisioning](/4yItIzMvkpAvMVFAamTf/integrations/integrations/workday/provisioning.md#enabling-provisioning).
* Veza extracts the Azure AD or Active Directory integration that holds the mailbox address.
* You have reviewed the Workday [email update behavior](/4yItIzMvkpAvMVFAamTf/integrations/integrations/workday/provisioning.md#email-update-behavior).

#### Configure the action

1. In the policy workflow, select **Add New Action** > **Sync Identities**, and set **Entity Type** to **Workday Account**.
2. Disable **Update only on create or reactivate**. Otherwise, the action does not update existing workers.
3. In addition to the required `id` mapping, map `email` to this conditional transformer:

   ```txt
   IF sys_attr__would_be_value co "@"
     {employee_id | FROM_ENTITY_ATTRIBUTE, "AzureADUser", "employee_id", "email", ""}
   ELSE
     {email}
   ```
4. For `email`, select **Set for new and existing users**.
5. Test the policy with a [dry run](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/how-to/test-policies-with-dry-run.md) before you publish it.

Because the condition references [`sys_attr__would_be_value`](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/transformers/system-attributes.md#sys_attr__would_be_value), Veza evaluates the `IF` branch lookup first and tests its result. When the lookup finds no matching user, or a user with no email, it returns an empty value, the condition fails, and the `ELSE` branch maps the worker's current `email` value instead.

{% hint style="warning" %}
The `ELSE` branch can still write to Workday. Veza compares the mapped value with the Workday Account's email address, not the worker's, and the worker `email` attribute can hold the primary home email. When the values differ, the action writes the `ELSE` value as the worker's primary work email.
{% endhint %}

When you adapt the example:

* Keep the empty default (`""`). Without it, a lookup that finds no match is an error, and the action fails.
* For Active Directory, replace `"AzureADUser", "employee_id"` with `"ActiveDirectoryUser"` and an attribute that Veza extracts for Active Directory users, such as `"account_name"`. Veza does not extract `employee_id` for Active Directory users, so also replace the input before the `|` with a Workday attribute that holds the matching value.

To write a value produced earlier in the same workflow instead, see [Referencing attributes from earlier actions](#referencing-attributes-from-earlier-actions).

## Referencing attributes from earlier actions

A Sync Identities action makes the target account's attributes available to later actions in the same workflow. Reference them by qualifying the attribute with the entity type:

```
{ActiveDirectoryUser.email}
{AzureADUser.principal_name}
```

A bare placeholder such as `{email}` reads only the source-of-identity record that triggered the workflow, so it does not return values the workflow wrote to a target system. Use the qualified form for that. When several actions write the same entity type, the most recent value takes precedence.

This is what makes a two-step write-back possible: provision the account in the target system, then map the identity source's `email` attribute to the address the first action produced. After a [Create Email](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/create-email.md) action, the new address is also available to every later action as `{email_address}`.

Three limits apply:

* **Order matters, and Veza does not check it.** Unlike the [Write Back Email](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/write-back-email.md#required-upstream-action) action, a Sync Identities write-back action is not validated for ordering. Placed before the action that produces the value, it publishes without error and then writes an empty or stale value at run time. Structure the policy so that the write-back occurs after the action that creates the account.
* **A sync that changes nothing might not publish its mapped values.** When an action finds the target already up to date, later actions see only the attributes the target system itself returned, not every mapped field.
* **Available attributes vary by integration.** For example, Active Directory re-reads the account after writing, so `{ActiveDirectoryUser.email}` reflects the stored value. Azure AD returns the user principal name but not `mail` (use `{AzureADUser.principal_name}` to retrieve the address of a newly created Azure AD account).

## Enforce password change on login

**Enforce password change on login** forces a newly created user to change their password the first time they sign in. The checkbox appears on the Sync Identities action only for target systems that support it.

| Target system    | Sync Identities | Reset Password               |
| ---------------- | --------------- | ---------------------------- |
| Active Directory | ✅               | ✅                            |
| Azure AD         | ❌               | ✅                            |
| Google Workspace | ✅               | — (no Reset Password action) |
| ServiceNow       | ✅               | — (no Reset Password action) |

For Active Directory, this setting is part of a broader password policy that also controls password complexity and can deliver the generated password through an event notification — see [Active Directory provisioning](/4yItIzMvkpAvMVFAamTf/integrations/integrations/active-directory/provisioning.md#password-policy-for-new-identities). For Google Workspace, only the change-on-login behavior is configurable — see [Google Cloud provisioning](/4yItIzMvkpAvMVFAamTf/integrations/integrations/google/provisioning.md#password-policy-for-new-identities). For the Reset Password action, see [Reset Password](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/reset-password.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/sync-identities.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.