Control Access (Optional)

If you have set up a connection properly and retrieved data from Finch APIs, you may also want to confirm that you are only displaying or processing data relevant to the authenticated user. While this is option, it’s recommended to avoid mixing up data from different customers or employers.

For instance, only fetching specific customer data using their access token, then only displaying their data on their account dashboard.

If your application is deployed individually per customer (often called single-tenancy), there is natural isolation of employer data since each tenant is on a separate instance running on its own set of servers, databases, and other infrastructure.

However, if your application serves multiple customers in a single instance (often called multi-tenancy), each employer’s data should remain isolated from other employers either through authorization, database partitioning, separate schemas, or other techniques.

​

Application authorization

In order to control user’s access to the right data, you can apply role-based access control (RBAC) or another authorization permission systems in your application. We will specifically focus on multi-employer RBAC authorization.

Multi-employer RBAC involves 4 core elements:

• Users: A user is an individual who is trying to access their employment data which they granted you access to via Finch Connect. A user is assigned roles, which in turn grant them the permissions they need to access resources. In a multi-employer RBAC, users typically belong to a particular employer and their permissions and roles are scoped to that employer. A user in one employer should not, by default, have any permissions or roles in another employer unless explicitly granted.
• Roles - A role is a collection of permissions that define the actions a user can perform in your application. A role is assigned to a user, and a user can have multiple roles. In a multi-employer environment, roles are typically scoped to a particular employer so that an “Admin” role in Employer A might have different permissions than an “Admin” role in Employer B.
• Permissions - A permission is a right to perform a specific action or access a specific resource in your application. Permissions are assigned to roles. In a multi-employer context, permissions should be defined in a way that they are also scoped to specific employers. This ensures that granting a permission in one employer doesn’t inadvertently grant access to resources in another employer.
• Employers: An employer is the foundational element of multi-employer scenarios. Each employer represents an isolated unit or environment in your application, like a separate company or organization. Your application must be able to separate and manage data, configurations, and roles for each employer independently, ensuring there’s no overlap or unintended sharing.

The RBAC system follows a simple logic: A user requests access to a resource, and the system checks if the user has the necessary permissions to access that resource based on the roles assigned to them.

Cross-Employer Authorization

There may be scenarios where a user needs access across multiple employers (maybe they manage multiple employers for a PEO, or Professional Employer Organization. In such cases, your RBAC authorization system must support cross-employer roles and permissions without compromising the security or isolation of individual employers.

Building upon the database tables customers & finch_connections defined in the Manage Connections guide, in order to implement multi-employer RBAC, we need a few additional tables.

• customers: Represents the “entities” who use your system.
• finch_connections: Represents the different connections (i.e. employers) a customer might have in your system.
• users: Represents individual users within a particular employer. Each user is associated with a specific connection, which defines the context of their roles and permissions.
• roles: Represents different roles that can be assigned to users within an employer. Each role is associated with a particular connection, signifying the context in which the role exists.
• permissions: Represents the different actions or operations that can be performed within your system. Permissions are not directly linked to a connection as permissions are typically more generic and can be used across multiple connections.
• role_permissions: A junction (or associative) table that establishes a many-to-many relationship between roles and permissions. Allows you to assign multiple permissions to a single role and vice versa.
• user_roles: Another junction table, but this one links users and roles. It determines which roles are assigned to a user in the context of a connection. Each combination signifies the roles a user has within a particular connection, which in turn dictates what actions they can perform with their employment data.

Once the database is set up, to implement data access controls, you can use a combination of JOIN statements in your SQL queries to enforce access restrictions based on the user’s role or permissions.

At a minimum, your application should have an Admin role since it is the employer’s HR & Payroll admin who should only have the permissions to go through Finch Connect and establish a connection with their employment system. Since a regular employee does not have the permissions to see the whole company-wide details or payroll, they should not be shown the option to connect via Finch.

Wether you choose to maintain separate environments for each employer or a shared instance with secure access control, being able to minimize the risk of unauthorized data access or mixing up data from different customers or employers is highly valuable.

​

Checkpoint + Next Step

​

Learn more

• Manage Connections
• Reconcile Employees