Directory and Relationships

Database relationship mapping for users, groups, roles, applications, and application permission roles

Architecture Directory Relationships

Auth Users

We have a database table of Auth Users that are imported from Okta, our SSO identity provider and what we refer to as an Auth Provider. The Okta data is populated upstream from BambooHR (today) or Workday (near future), our Human Resources Information System ("HRIS") or Human Capital Management System ("HCMS").

FAQ: Why do you need a table of users? Shouldn't that only be in Okta? We maintain a cache database table of users that is routinely synced with Okta instead of directly using the API for each request so that we can use our relational database for mapping to groups, roles, and applications that is not possible when using API calls.

auth_providers

1{
2 "id": "591916f1-c16e-4637-9a34-cb4b418816eb",
3 "short_id": "591916f1",
4 "slug": "okta",
5 "base_url": "https://gitlab.okta.com",
6 "client_id": "(encrypted)",
7 "client_secret": "(encrypted)",
8 "flag_enabled": 1,
9 "enabled_at": "2020-11-17 01:49:33",
10 "created_at": "2020-11-17 01:49:30",
11 "updated_at": "2020-11-17 01:49:33",
12 "deleted_at": null,
13 "created_by": "0c621173-6062-46c1-a3b7-f9434b14e3e0",
14 "updated_by": "f6153b2e-e0aa-4697-a05f-ccea8ca882d9",
15 "deleted_by": null,
16 "state": "active"
17}

auth_users

1{
2 "id": "0c621173-6062-46c1-a3b7-f9434b14e3e0",
3 "short_id": "0c621173",
4 "auth_provider_id": "591916f1-c16e-4637-9a34-cb4b418816eb",
5 "full_name": "Milo Hoffman",
6 "email": "mhoffman@gitlab.com",
7 "provider_meta_data": {
8 "sub": "a1b2c3d4e5f7g7h8i9j0",
9 "updated_at": 1623315787,
10 "gl_entity": "Inc",
11 "locale": "US",
12 "gl_job_title": "Backend Engineer, Ecosystem",
13 "gl_division": "Engineering",
14 "gl_department": "Development",
15 "gl_manager_name": "Winston, Gary",
16 "gl_manager_id": "67890",
17 "gl_employee_id": "12345",
18 "gl_user_id": "1234567",
19 "gl_slack_id": "ABCDEFGHI",
20 "gl_username": "mhoffman-gl",
21 "preferred_username":"mhoffman@gitlab.com"
22 },
23 "provider_token": "(encrypted)",
24 "count_current_failed_logins": "0",
25 "last_successful_login_at": "2021-08-05 14:32:26",
26 "last_failed_login_at": null,
27 "last_activity_at": "2021-08-05 17:58:31",
28 "expires_at": null,
29 "locked_at": null,
30 "created_at": "2021-08-02 07:32:01",
31 "updated_at": "2021-08-02 07:32:01",
32 "deleted_at": null,
33 "state": "active"
34}

Auth Groups

We have a database table of Auth Groups that are defined based on the lists of entities, countries, divisions, departments, department groups (teams), job family, job specialty, working groups and cross-team functional groups, and custom security groups. We consider each of these lists of groups to be a different category for organization and least privilege purposes, however the functionality is the same regardless of the group category. We have the flexibility to add additional categories and custom groups as needed.

Each Auth Group has multiple Auth Users, and each Auth User can belong to multiple Auth Groups.

Iteration Opportunity: As of August 2021, the division and department are available in Okta, and the other meta data fields need to be parsed and imported from other data sources. This will be optimized in future iterations in alignment with our BambooHR to Workday HRIS migration. More information is available in enterprise-apps/intake#300 - Workday: Okta Analysis.

1"provider_meta_data": {
2 // (truncated existing values)
3 "gl_department_group": "Create Stage - Ecosystem Group",
4 "gl_job_family": "Backend Engineer",
5 "gl_job_specialty": "Backend Engineer - Ecosystem"
6}
id category name
b3218332 entity GitLab Inc.
aa1581d7 country US
a46b0a38 division Engineering
b47cc8c7 department Development
18bb382a department_group Create Stage - Ecosystem Group
45863438 job_family Backend Engineer
bed79162 job_specialty Backend Engineer - Ecosystem
d3bf5e33 functional_group Alliances Integrations
d3bf5e33 functional_group API Documentation Maintainers
6f526d04 security_group Ecosystem Integrations Infrastructure

auth_groups_users

1[
2 {
3 "id": "20129d53-90af-4c24-b0e1-88eac6b4713b",
4 "short_id": "20129d53",
5 "auth_group_id": "b47cc8c7-cdef-4886-9b18-635540e14dc9",
6 "auth_user_id": "0c621173-6062-46c1-a3b7-f9434b14e3e0",
7 "approval_flow_id": "f0bcc523-5b3e-4939-a544-31a8588ab9a9",
8 "created_at": "2021-08-02 07:32:02",
9 "updated_at": "2021-08-02 07:32:02",
10 "expires_at": null,
11 "deleted_at": null,
12 "state": "active"
13 },
14 {
15 "id": "6adb24ec-28e0-411a-ad96-7ecb411c7814",
16 "short_id": "6adb24ec",
17 "auth_group_id": "18bb382a-7c67-420d-a4c0-cce147725ee0",
18 "auth_user_id": "0c621173-6062-46c1-a3b7-f9434b14e3e0",
19 "approval_flow_id": "c76f87d9-75d4-47b8-b835-03a9b356168e",
20 "created_at": "2021-08-02 07:32:02",
21 "updated_at": "2021-08-02 07:32:02",
22 "expires_at": null,
23 "deleted_at": null,
24 "state": "active"
25 },
26 {
27 // ...
28 }
29]

Auth Roles

Auth Groups allow us to grant roles to a group that allows the roles to be inherited by users attached with that group instead of manually defining the roles for each user individually.

An Auth Role handles permissions in the Access Manager application. A SaaS Provider Role is mapped to each of the permission roles that a SaaS Provider User (tech stack application user) can be granted access to during the provisioning process.

At GitLab, this allows us to have an Auth Group for an entity (Ex. GitLab Inc.) that has SaaS Providers (Ex. 1Password, Google G-Suite/Workplace) and SaaS Provider Roles that all team members should have access to (ex. baseline entitlements). We have Auth Groups for job families (Ex. Backend Engineer), job specialties, etc. that allow us to provision roles for specific applications based on least privilege in additional to the baseline entitlements.

SaaS Providers

A SaaS Provider is a one-to-one mapping to a vendor that provides a SaaS application or service.

SaaS Provider Entities

A SaaS Provider may have child accounts, organizations, projects, resources, tenants, vaults, etc. that each have unique SaaS Provider Groups, SaaS Provider Roles, or SaaS Provider Users. For SaaS Providers with a simpler organizational structure, a Default Entity will be created that all SaaS Provider Groups, Roles, and Users will be associated with for architectural consistency.

A SaaS Provider Entity is a generic term that allows us to have the same model, view, controller, and service architecture and allows each entity to have an alias in the database for what each SaaS Provider calls it.

SaaS Provider Groups

A SaaS Provider Group is a one-to-one mapping to a user group that exists in the SaaS application or service and contains metadata that is used for mapping a SaaS Provider User to.

Each SaaS Provider Group has one or more Approval Policies attached that define how users can join the group.

For most SaaS applications, a user will be associated with a Group (that has inherited roles) or a Role, but not both. The Access Manager architecture allows us to universally adapt to different SaaS Providers.

SaaS Provider Roles

A SaaS Provider Role is a one-to-one mapping to a user role that exists in the SaaS application or service and contains metadata that is used for mapping a SaaS Provider user to.

Each SaaS Provider Role has one or more Approval Policies attached that define how users can be associated with the role.

For most SaaS applications, a user will be associated with a Group (that has inherited roles) or a Role, but not both. The Access Manager architecture allows us to universally adapt to different SaaS Providers.

SaaS Provider Users

A SaaS Provider User is a one-to-one mapping to a user's local authentication account, SSO federated user account, or IAM policy mapping in the SaaS application that Access Manager has provisioned and manages. A SaaS Provider User may be associated with one or more SaaS Provider Groups or SaaS Provider Roles depending on the architecture of the SaaS Provider's software.