---
metadata:
  - name: generator
    content: Diplodoc Platform v5.63.0
alternate:
  - en/concepts/sync-IdP
  - href: en/concepts/sync-IdP.md
    type: text/markdown
    title: Markdown version
csp:
  - script-src:
      - https://mc.yandex.ru
    img-src:
      - https://mc.yandex.ru
    connect-src:
      - https://mc.yandex.ru
      - wss://mc.yandex.ru
    child-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-ancestors:
      - 'blob:'
      - https://mc.yandex.ru
canonical: en/concepts/sync-IdP.html
title: Synchronization with an external IdP
description: Follow this guide to run a script for synchronization with an external IdP.
vcsPath: en/concepts/sync-IdP.md
---

# Synchronization with an external IdP

The script performs synchronization with an external identity provider (IdP). Current script version:

* Creates new IdP users.
* Creates new IdP groups.
* Updates user membership in IdP groups.
* Updates group headers.
* Updates user roles.
* Updates user profile data.

## Script execution requirements {#requirements}

* To run the synchronization script, you need Node.js version 20 or higher. If Node.js is not installed or you need a newer version, select the suitable installation option on the [Node.js website](https://nodejs.org/en/download/package-manager).
* Set up a configuration for Auth using the `AUTH_PROVIDERS_CONFIG` environment variable.
* Disable `syncUserGroups` in `AUTH_PROVIDERS_CONFIG` for your IdP if you have used this script to set up regular synchronization.

## Example of running the script {#example}

```bash
node ./idp-sync.js \
     usEndpoint=https://us.domain.org \
     authEndpoint=https://auth.domain.org \
     usMasterToken=usmastertoken \
     authMasterToken=authmastertoken \
     idpSlug=someidpslug \
     idpData=./idp-data.json
```

Where:

* `idpSlug`: Slug from the IdP configuration in Auth.
* `usEndpoint`: United Storage endpoint.
* `authEndpoint`: Auth endpoint.
* `usMasterToken`: `US_MASTER_TOKEN` master token for United Storage.
* `authMasterToken`: `AUTH_MASTER_TOKEN` master token for Auth.
* `idpData`: Path to data from IdP, in JSON format.

## IdP data from source {#idp-data-source}

Prepare data from IdP, in JSON format, as per `AUTH_PROVIDERS_CONFIG` for auth:

```typescript
type JsonData = {
    users: {
        idpUserId: string, // internal ID of user from IdP
        login: string,
        email : string | null,
        firstName: string | null,
        lastName: string | null,
        roles: string[], // datalens.admin, datalens.creator, datalens.visitor
    }[];
    groups: {
        groupId: string, // internal ID of group from IdP
        title: string,
        memberIds: string[], // internal IDs of users from IdP, idpUserId
    }[];
}
```

### Example of idp-data.json for OpenLDAP {#example-ldap}

```json
{
    "users": [
        {
            "idpUserId": "id-bob",
            "login": "bob",
            "email" : "bob@example.org",
            "firstName": "Bob",
            "lastName": "Smith",
            "roles": ["datalens.visitor"]
        },
        {
            "idpUserId": "id-carl",
            "login": "carl",
            "email" : "carl@example.com",
            "firstName": "Carl",
            "lastName": "Snow",
            "roles": ["datalens.creator"]
        }
        ...
    ],
    "groups": [
        {
            "groupId": "id-datalensadmins",
            "title": "DataLens admins",
            "memberIds": ["id-bob", "id-carl"]
        },
        ...
    ]
}
```