Skalio ID Integration

As TeamBeam is moving to use Skalio ID for authentication, users and adminunits can be in different stages, and clients need to adapt their use of API endpoints accordingly.

Mapping entities

In TeamBeam, the people using the service belong to exactly one organization. The organization is the business partner of Skalio, and the relationship is typically governed by a contract. All transfers belong to the organization of the person who sent it.

Adminunits

The backend uses entities adminunits and users to represent the people and how they are organized in their organization.

Constraints and noteworthy points:

• The adminunit to user relationship is 1:n: a user belongs to exactly one adminunit.
• A user has exactly one email address. The address is immutable.
• The user entity is used for multiple purposes. Only type employee is relevant here: regular persons, can authenticate against TeamBeam and use the service within the assigned rights.
• A user of type employee typically authenticates using email address and password against credentials stored in TeamBeam. In some cases, an adminunit may have integration with a remote directory server via LDAP. In those cases, TeamBeam stores no credentials and the authentication is proxied to the LDAP server.
• An adminunit represents a business customer of Skalio. Creation of an adminunit is a manual process by Skalio. An adminunit is managed by one or more users with admin privileges.
• A user has specific privileges, managed by the admin of the adminunit.
• A user can manage his own profile and settings.
• Some shared adminunits exist, where the users have individual contracts. These adminunits are managed by the Skalio cluster-admin. Administration by the customer is not allowed.
  • free.teambeam.de: Usage is not charged, but restricted in features and capacity. Users can sign up themselves.
  • pro.teambeam.de: Individuals sign a contract.

Organizations

Skalio ID is more flexible and does not face some of the restrictions:

• A person can be a member of zero, one or many organizations.
• A person can create any number of organizations.
• A person can have multiple email addresses, designating one as a primary address. Through the process of adding, verifying and removing addresses, a person can change their address themselves.

Mapping

To facilitate the integration of Skalio ID into TeamBeam, the following entity mapping is used:

TeamBeam	Skalio ID	Mapping by	Note
adminunit	organization	uid	An adminunit with a uid supports authentication from Skalio ID
storagehost	n/a	not mapped	The concept of storagehost is managed by TeamBeam only
user	person	uid	A person with a uid is managed by Skalio ID
email	primary address	uid of person / user	When a person changes his primary address, this is synced to TeamBeam
rights	n/a	not mapped	Privileges of a user are managed by TeamBeam only

• Before an adminunit can accept Skalio ID-authentiated persons, it must have been mapped to an organization.
  • Currently, this is achieved by migrating the adminunit to Skalio ID.
  • TODO: provide cluster-admin functionality to create a customer as both Skalio ID organization and TeamBeam adminunit.
• A person that is managed by Skalio ID cannot authenticate against TeamBeam.
• A person that is managed by Skalio ID cannot change his profile (realName, locale, timeZone) at TeamBeam. Instead TeamBeam will subscribe to Skalio ID changes and update the profile accordingly.
• A person must have a membership in an organization matching the adminunit that is processing the request.
  • Currently, the specific orgPrivilegeType is irrelevant.
  • TODO: map orgPrivilegeType#admin to TeamBeam contract owner or admin.
• Warning: Skalio ID allows a person to be member of multiple organizations, some of which might map to an adminunit. TeamBeam however requires a user belongs to exactly one adminunit. This must be resolved eventually!

Organization membership

TeamBeam requires that a Skalio ID person is a member of an organization that maps to the adminunit processing the request. The specific orgPrivilegeType is currently not evaluated.

Ways to get there:

• Migration from TeamBeam to Skalio ID: this is a process managed by Skalio operations engineers.
• Join the team of a Skalio ID organization by following an invitation (API).
• TODO: The administrator of an organization creates an invitation to join a team, sends it to the person.

Scenarios

This section describes scenarios and possible flows how to implement them.

User is managed by TeamBeam

Context:

• user exists in TeamBeam; type: employee; uid: null; passwordHash: not null

Flow:

1. Check if user is managed by TeamBeam: POST /auth/exists returns 204
   • use any hostname; the request is answered correctly on all storagehosts
2. Authenticate against TeamBeam: POST /auth/login
   • process response, check storagehost.hostname matches current URL
   • redirect to correct hostname if necessary
3. Access TeamBeam using session-based authentication

User has been migrated to Skalio ID

Context:

• an organization exists
• a person exists in Skalio ID; is member of this organization
• an adminunit has been migrated to Skalio ID; uid matches organization
• user exists in TeamBeam; type: employee; uid matches person ; passwordHash: null; belongs to the adminunit

Flow:

1. Check if user is managed by TeamBeam: POST /auth/exists returns 404
   • use any hostname; the request is answered correctly on all storagehosts
2. Check if user is managed by Skalio ID: POST /auth/exists returns 200
3. Authenticate against Skalio ID
   • successful authentication returns an ID token
4. Exchange ID token for access token at TeamBeam: POST /auth/access
   • Since at this point, the target hostname is not known, use a previously used hostname or a default hostname free.teambeam.de
   • process response, check if token is set
   • if token is null, retry request at adminunits.[0].hostname
5. Access TeamBeam using access-token-based authentication

Person wants to sign up to TeamBeam

Context:

• no person exists in Skalio ID matching the email address, OR a person exists in Skalio ID; is not member of any organization
• no user exists matching the email address
• an organization exists representing "free.teambeam.de"
• a public invitation exists for a team for this organization; is configured in the TeamBeam environment
  • TODO: investigate environment.self_signup_*; find a place for the invitiation
• adminunit "free.teambeam.de" has uid matching this organization

Flow:

1. Fetch environment from TeamBeam
   • check self_register_enabled and freemiumEnabled
   • extract invitiation TODO
2. Check if user is managed by TeamBeam: POST /auth/exists returns 404
   • use any hostname; the request is answered correctly on all storagehosts
3. Check if user is managed by Skalio ID: POST /auth/existsgit
   1. person does not exist, returns 404
      1. Offer "Signup to TeamBeam Free"
      2. Signup at Skalio ID: POST /signup
         • returns a short-lived ID token
         • notice: orgUnits claims
   2. person exists, returns 200
      1. login to Skalio ID
         • returns ID token
         • notice: orgunits might contain data
      2. Offer "Signup to TeamBeam Free"
4. Join the team by accepting the invitation at Skalio ID: POST /auth/join/{invitation} authenticated with the ID token
   • returns a new ID token
   • notice: orgUnits claim contains uid of the organization
5. Exchange ID token for access token at TeamBeam: POST /auth/access
   • Since at this point, the target hostname is not known, use the previously used hostname; or a default hostname free.teambeam.de
   • process response, check if token is set
   • if token is null, retry request at adminunits.[0].hostname
   • TeamBeam will auto-provision the user in the appropriate adminunit based on information from the ID token
6. Access TeamBeam using access-token-based authentication

Organization admin adds new person

Context:

• an organization exists
• a person does not yet exist in Skalio ID OR a person has a Skalio ID account, but is not member of the organization
• an adminunit has been migrated to (or created matching) Skalio ID; uid matches organization

Flow:

1. Organization admin creates an invitation to join a team of his organization.
2. Invitation is sent to new person
3. Similar as above: person signs up or logs in to Skalio ID, consumes invitation, uses ID token to access TeamBeam
4. TeamBeam auto-creates a user from information in the ID token

Note: it is unclear, how the invitation is consumed. This could be done within the TeamBeam app. However, a Skalio ID website is probably more likely, and reduces requirements for other apps.