User Synchronization

TIS Plus has a teamsync component that will periodically connect to your Identity Provider (IdP) and sync user and team information into TIS Plus.

Currently teamsync supports LDAP and Azure AD, and will do The Right Thing for you automatically. However, if you are using another IdP, you will need to manually perform these tasks. This document will describe how to perform them.

Before you start, make sure that you have:

✓ Installed TIS Plus Management Plane
✓ Login to TIS Plus with tctl with administrator account
✓ Get your TIS Plus's organization name - Make sure to use organization name configured at installation time in the TIS Plus ManagementPlane CR.

Create Organization

Teamsync not only syncs your users and teams, but it also creates an organization when run for the first time after TIS Plus management plane components are installed.

Therefore if you are using an IdP that is not supported by teamsync, you will also need to perform this step manually.

To create an organization, create following organization.yaml and then apply with tctl

apiVersion: api.tsb.tetrate.io/v2
kind: Organization
metadata:
  name: <organization-name>

tctl apply -f organization.yaml

Synchronizing Users and Teams Manually

Synchronization entails fetching users and teams information from IdP and transforming them into a structure that TIS Plus sync API payload then send sync request to TIS Plus API Server. Once they are synchronized, you can assign roles to the users and teams to give them access to TIS Plus resources.

Fetch Users and Teams from IdP

Details of this step will vary depending on your IdP. You should check your IdP documentation on how to get users and teams. For example, If you are using Okta you may be able to use List users and List groups API. Similarly if you are using Keycloak, you may be able to use List users and List groups API.

Transform Data into TIS Plus sync API payload

Once you obtain the list of users and teams from your IdP, you need to transform them into TIS Plus sync API payload format. The exact details on how to perform this transformation depends on the payload format of your IdP API.

Following is an example of sync API payload. Refer to Sync Organization API for more details.

{
    "sourceType": "MANUAL",
    "users": [
        {
            "id": "user_1_id",
            "email": "user_1@email.com",
            "loginName": "user1",
            "displayName": "User 1"
        },
        {
            "id": "user_2_id",
            "email": "user_2@email.com",
            "loginName": "user2",
            "displayName": "User 2"
        },
    ],
    "teams": [
        {
            "id": "team_1_id",
            "description": "Team 1 description",
            "displayName": "Team 1",
            "memberUserIds": [
                "user_1_id"
            ]
        },
         {
            "id": "team_2_id",
            "description": "Team 2 description",
            "displayName": "Team 2",
            "memberUserIds": [
                "user_2_id"
            ]
        },
    ]
}

Send Sync API Request

After you have transformed the IdP payload into TIS Plus sync API payload, you can send requests to the TIS Plus API server to synchronize the data .

The following example uses curl to send a request to the TIS Plus API server running on <tsb-host>:8443, using the TIS Plus admin user credentials. The TIS Plus sync API payload is assumed to be stored in the file /path/to/data.json

curl --request POST \
  --url https://<tsb-host>:8443/v2/organizations/tetrate/sync \
  --header 'Authorization: Basic base64(<admin>:<admin-password>) \
  --header 'Content-Type: application/json' \
  --data-binary '@/path/to/data.json'

Automating the Process

Now that you know how teamsync works, you can create a service that runs periodically (e.g. as cron job) using your favorite programming language to automate the synchronization process.