Creating Tenants, Teams and Users

Automatic team and user synchronization from LDAP

Starting TSB 0.6.5, users and teams are automatically synchronized from LDAP, so there is no longer the need to manually create tenant, users and teams, although it is still supported.

Therefore, if you are using TSB 0.6.5 and above, you can skip this section on creating tenants, teams, and users.

Tenants, teams, and users can be managed using the Organization API. In this document, we will describe an example onboarding use case where we will create a new tenant, an administrator for that tenant, and a set of users. Finally, we will assign those users permissions to access some of the resources in TSB.

In addition, you need the load balancer IP or host name of the TSB cluster. Refer to Tetrate Service Bridge Installation for details on how to obtain ${TSBIP}. Here and elsewhere in the document, if not explicitly said, it is assumed that TSB port is 8443.

Create a new tenant

First of all, we will create a new tenant that will contain the teams and users we will create in this example.

curl https://${TSBIP}:8443/v1/tenants \
    -u "<super-user>:<super-user pass>" \
    -X POST \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "id": "tenant1",
  "description": "Onboarding example tenant"
}
EOF

Create a tenant administration team

Now that we have a tenant, the next step is to create a team that defines the tenant administrators:

curl https://${TSBIP}:8443/v1/tenants/tenant1/teams \
    -u "<super-user>:<super-user pass>" \
    -X POST \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "id": "tenant-admins",
  "description": "Tenant administrators"
}
EOF

And configure the administrators team in the tenant access policy (see the Access Control docs for details), in order to grant all users in that team permissions to manage the tenant and create other users, teams, etc.

curl https://${TSBIP}:8443/v1/tenants/tenant1/policy \
    -u "<super-user>:<super-user pass>" \
    -X PUT \
    -H 'content-type: application/json' \
    -d @- <<EOF
{
  "bindings": [
    {
      "role": "Owner",
      "subjects": [
        "tenants/tenant1/teams/tenant-admins"
      ]
    }
  ]
}
EOF

Create the tenant administrator users

Once we have the tenant administrators team, we can add users to it. In the following example we will create a new user and assign it to the team.

curl https://${TSBIP}:8443/v1/tenants/tenant1/users \
    -u "<super-user>:<super-user pass>" \
    -X POST \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "id": "admin",
  "description": "Tenant administrator"
}
EOF

Next, we add members to the tenant administrators team.

Updating etag protected resources

Note that the team objects in TSB have an etag field to prevent concurrent modifications. This is a common pattern in all TSB objects that have collections. In order to modify an object that is protected by an etag, you need to make sure you send the right value for the etag.

# Get the team object to make sure we have the right value
# for the etag field
curl -u "<super-user>:<super-user pass>" \
  https://${TSBIP}:8443/v1/tenants/tenant1/teams/tenant-admins
# Output would be something like below
{
  "name": "tenants/tenant1/teams/tenant-admins",
  "tenant": "tenant1",
  "id": "tenant-admins",
  "etag": "W/\"8508289089459069748\""
}

# Update the list of members (none in this example) and send it back
curl https://${TSBIP}:8443/v1/tenants/tenant1/teams/tenant-admins \
    -u "<super-user>:<super-user pass>" \
    -X PUT \
    -H 'content-type: application/json' \
    -d @- <<EOF
{
  "name": "tenants/tenant1/teams/tenant-admins",
  "tenant": "tenant1",
  "id": "tenant-admins",
  "etag": "W/\"8508289089459069748\"",
  "members": [
    "tenants/tenant1/users/admin"
  ]
}
EOF

note

Only the super-user can create tenants, create an initial admin team for tenants and add users to that team.

Using the tenant admin to onboard users

Now the tenant administrator can continue onboarding the rest of users and assigning them to resources in the tenant.

The following example shows how to create a new user and team, and grant them access to a set of resources.

# Use the tenant admin to create new users
curl https://${TSBIP}:8443/v1/tenants/tenant1/users \
    -X POST \
    -u "admin:<credential>" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "id": "user",
  "description": "Regular tenant user"
}
EOF

Let us now create a set of teams that represent an organization structure.

Team hierarchy

TSB supports team hierarchy, so not only users but also teams can be added as members of the teams.

# Create the development team
curl https://${TSBIP}:8443/v1/tenants/tenant1/teams \
    -X POST \
    -u "admin:<credential>" \
    -H "content-type: application/json" \
    -d '{"id": "development"}'

# Create the QA team
curl https://${TSBIP}:8443/v1/tenants/tenant1/teams \
    -X POST \
    -u "admin:<credential>" \
    -H "content-type: application/json" \
    -d '{"id": "qa"}'

# Create the global engineering team. When assigning this team to a resource
# all members in this team (and the nested teams) will be granted access.
curl https://${TSBIP}:8443/v1/tenants/tenant1/teams \
    -X POST \
    -u "admin:<credential>" \
    -H "content-type: application/json" \
    -d @- <<EOF
{
  "id": "engineering",
  "members": [
    "tenants/tenant1/users/user",
    "tenants/tenant1/teams/development",
    "tenants/tenant1/teams/qa"
  ]
}
EOF

Finally, grant access to some resources within the tenant as follows.

# Grant access to the development environment to the development team
# Here we assume the relevant resources (environment, applications) already exist
curl https://${TSBIP}:8443/v1/tenants/tenant1/environments/dev/policy \
    -X PUT \
    -u "admin:<credential>" \
    -H 'content-type: application/json' \
    -d @- <<EOF
{
  "bindings": [
    {
      "role": "Owner",
      "subjects": [
        "tenants/tenant1/teams/dev",
      ]
    }
  ]
}
EOF

# Grant access to the QA environment to the qa team
curl https://${TSBIP}:8443/v1/tenants/tenant1/environments/qa/policy \
    -X PUT \
    -u "admin:<credential>" \
    -H 'content-type: application/json' \
    -d @- <<EOF
{
  "bindings": [
    {
      "role": "Owner",
      "subjects": [
        "tenants/tenant1/teams/qa",
      ]
    }
  ]
}
EOF

# Grant everyone in the engineering team access to application 'app'
# in the 'dev' environment
curl https://${TSBIP}:8443/v1/tenants/tenant1/environments/dev/applications/app/policy \
    -X PUT \
    -u "admin:<credential>" \
    -H 'content-type: application/json' \
    -d @- <<EOF
{
  "bindings": [
    {
      "role": "Owner",
      "subjects": [
        "tenants/tenant1/teams/engineering",
      ]
    }
  ]
}
EOF