{{% alert title="Not Live Yet" color="warning" %}}
You are viewing a preview of documentation for the future state of GitLab Identity v3 (mid 2024). See the <ahref="https://handbook.gitlab.com/handbook/security/access-management-policy">Access Management Policy</a> for the GitLab Identity v2 current state with baseline entitlements and access requests. See the roadmap in the <ahref="https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/roadmap?state=all&sort=start_date_asc&layout=QUARTERS&timeframe_range_type=THREE_YEARS&group_path=gitlab-com/gl-security/identity/eng&progress=WEIGHT&show_progress=true&show_milestones=false&milestones_type=ALL&show_labels=true">epics gantt chart</a>.
{{% /alert %}}
{{% alert title="Quick Reference User Guides" color="info" %}}
This page focuses on the architecture and documentation of our Identity Platform and Security Program. If you are looking to get access an application or infrastructure, see the <ahref="/handbook/security/identity/guide/user">Team Member User Guide</a>. To manage access for team members that report to you, see the <ahref="/handbook/security/identity/guide/manager">Manager User Guide</a>. You can scroll to the bottom of this page to see the other user guides.
{{% /alert %}}
## Identity Team Functions
The [Identity Engineering](/handbook/security/threat-management/identity) team was formed in the [Security Threat Management](/handbook/security/threat-management) sub-department with a cross-department realignment on 2023-12-01 to lead the design and implementation of our next-generation of identity and access management framework and program at GitLab that has been branded as [Identity v3](#gitlab-identity-v3) that will be released [iteratively throughout 2024](https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/roadmap?state=all&sort=start_date_asc&layout=QUARTERS&timeframe_range_type=THREE_YEARS&group_path=gitlab-com/gl-security/identity/eng&progress=WEIGHT&show_progress=true&show_milestones=false&milestones_type=ALL&show_labels=true).
The Identity Team has three functional specialties and collaborates cross-functionally with our stable counterparts.
GitLab is one of the stewards of the world’s source code and intellectual property. Our mission is to secure access to GitLab's internal systems to ensure that customer and product data is protected and industry trust is preserved.
We work cross-functionally to define infrastructure architecture, IAM/RBAC standards, and build automation to streamline access management across all internal control plane kingdoms.
### Open Source
Although the risks that we need to solve are confidential, we believe in open sourcing the best practice documentation and tools to solve those risks after we have mitigated the risk to give back to the community and inspire other companies.
**We are stronger and more secure together.**
All of our open source projects can be explored at [https://gitlab.com/gitlab-identity](https://gitlab.com/gitlab-identity).
## Tech Stack Kingdoms
We have refactored our tech stack into **Identity Kingdoms** (analogous to a realm) to provide separation of concerns between Business, Cloud, and Product (SaaS and Dedicated) unique needs, particularly with administrative control planes and least privilege configuration. This allows us to create automation and policies specific to each kingdom's compliance requirements to enable the respective teams to operate efficiently within our top-level architecture and guardrails.
Learn more on the [kingdoms](/handbook/security/identity/kingdoms) handbook page.
## Trust Landscape DRIs
The Security team focuses on customer, compliance, and product trust, while the Business Technology and IT team focuses on corporate and financial trust.
-**Administrator Trust:** Security Department - Identity Ops
-**Automation Trust:** Security Department - Identity Engineering
-**Boundary Trust:** Security Department - Identity Engineering
-**Compliance Trust:** Security Department - Commercial Compliance Team
-**Customer Trust:** Engineering, Product, and Security division
-**Financial Trust:** Business Technology/IT Department
-**Product Feature Trust:** Development Department and Product Management
-**Product Reliability Trust:** Infrastructure Department
## Technological Trust
In addition to maintaining human confidence, we also need to ensure supply chain confidence and that no single vendor breach can compromise the integrity of our architecture, particularly the boundaries that we refer to as castle walls. By using a defense-in-depth approach, we are able to minimize the external attack surface.
See our [boundaries](/handbook/security/identity/boundaries) to learn more.
## Roadmap
As any company grows, they go through phases of growth with many organic iterations throughout the journey. GitLab is currently outgrowing Identity v2 and is building our Identity v3 program.
### GitLab Identity v1
GitLab Identity v1 was managed using Tech Ops practices by the Infrastructure and People Operations team prior to 2018.
### GitLab Identity v2
GitLab Identity v2 is what we do today and have been doing since 2018 with [baseline entitlements](/handbook/business-technology/end-user-services/onboarding-access-requests/access-requests/baseline-entitlements/) and [access requests](/handbook/business-technology/end-user-services/onboarding-access-requests/access-requests/). See the [Access Management Policy](/handbook/security/access-management-policy/) to learn more.
The processes that we do today meets audit and compliance requirements, however the processes are mostly manual that results in internal inefficiency. It takes a lot of labor hours to manage onboarding, access requests, access reviews, and offboarding processes.
See the [FY24-Q4 State of Identity](https://internal.gitlab.com/handbook/security/identity/state/fy24-q4) in the internal handbook to get more context and valuable insights into the current architecture, challenges, and risks that we are mitigating. All of the documentation on the public handbook has been sanitized with an ideal future state that we are building.
We are in the architecture and early engineering incubation phase. Please continue to use existing Identity v2 processes (business as usual) for all requests through mid-2024.
{{% /alert %}}
As we look ahead, we want to focus on a North Star vision that systems are provisioned automatically by systems, not manually by people. With the introduction of Identity Roles and Identity Groups, we can reduce the number of ad-hoc access requests by using predefined policies and automated provisioning based on role-based access control rather than named user access control.
GitLab Identity v3 is where we want to be in FY25-2H (mid-late 2024) with a pseudo-greenfield approach to automate all of our policies and as much of our approvals, provisioning, and access reviews as possible.
Since GitLab is now a public company and the security threat landscape has evolved, the Security department is investing in in-house infrastructure and software engineering to build the automation and tools that we need to meet the challenges of the future, make GitLab easier to do business with internally, and unilaterally address our IAM and RBAC risks with a holistic approach instead of small iterations.
## Platform Engineering
The GitLab Identity Security team has CI/CD script and fullstack development skills to build our own open source policy and provisioning automation for our IAM and RBAC needs.
You may already use [GitLab Sandbox Cloud](/handbook/infrastructure-standards/realms/sandbox) that is powered by HackyStack. We are refactoring HackyStack to become a component of the Identity Platform.
We are in the early incubation stage of building the [Identity Platform](/handbook/security/identity/platform) that is powered by [accessctl](https://gitlab.com/gitlab-identity/accessctl), a new open source project. As our Identity Platform matures throughout 2024, we will add documentation for the community to adopt our platform and best practices.
The Identity Infrastructure team is focused on our top-level cloud provider infrastructure organization-level management for AWS and GCP in collaboration with the [Infrastructure Security](/handbook/security/security-engineering/infrastructure-security) team.
We build self-service tools for users to create their own AWS accounts and GCP projects and provide castle wall hardening.
Each team that deploys infrastructure resources is responsible for managing their own infrastructure workloads and DevOps operations using industry best practices. In other words, the Security team creates the scaffolding for your castle and provides hardened castle walls, while your team is responsible for anything you build inside the castle walls.
See the [Identity Infrastructure](/handbook/security/identity/infrastructure) handbook page to learn more.
-**Escalation DRI:** Jeff Martin or Vlad Stoianovici
## Identity Operations
When we operationalize GitLab Identity v3 in mid-2024, we will have cross-functional team members from IT Operations, People Operations, and Security Operations teams that will perform day-to-day administration of the Identity Platform and handle business and user requests.
In the interim, the Identity Platform Engineering and Identity Infrastructure team members provide coverage in collaboration with our [counterparts](/handbook/security/identity/counterparts).
Due to the nature of the risks that we mitigate, our roadmap is only visible to internal team members in our [epics roadmap](https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/roadmap?state=all&sort=start_date_asc&layout=QUARTERS&timeframe_range_type=THREE_YEARS&group_path=gitlab-com/gl-security/identity/eng&progress=WEIGHT&show_progress=true&show_milestones=false&milestones_type=ALL&show_labels=true).
You can learn more about our progress in our [Identity Engineering epics](https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/epics) and [Identity Engineering issues](https://gitlab.com/gitlab-com/gl-security/identity/eng/issue-tracker/-/issues).
We use public issue trackers for platform feature requests, however all issues related to GitLab's business, data, infrastructure, and risks are created and managed in the [Identity Engineering (internal) issue tracker](https://gitlab.com/gitlab-com/gl-security/identity/eng/issue-tracker/-/issues) and are linked in open source project merge requests (without disclosing title or contents) after the risk has been mitigated and merged.
After a risk has been mitigated and we believe that we have the latest best practices in place, we publish the documentation in our public handbook, internal handbook, and/or in the Access Control documentation.
{{% alert title="Not Live Yet" color="warning" %}}
You are viewing a preview of documentation for the future state of GitLab Identity v3 (mid 2024). See the <ahref="https://handbook.gitlab.com/handbook/security/access-management-policy">Access Management Policy</a> for the GitLab Identity v2 current state with baseline entitlements and access requests. See the roadmap in the <ahref="https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/roadmap?state=all&sort=start_date_asc&layout=QUARTERS&timeframe_range_type=THREE_YEARS&group_path=gitlab-com/gl-security/identity/eng&progress=WEIGHT&show_progress=true&show_milestones=false&milestones_type=ALL&show_labels=true">epics gantt chart</a>.
{{% /alert %}}
## Access Requests
If a user needs access to an application, there are several approaches:
1. The user's attributes **match the existing criteria** of a role or organization unit that has already been attached to the Okta application. Access is automatically granted without a request.
1. The **organization unit group** policy `CODEOWNER` (ex. division leader or department manager or Executive Business Assistant) can update the policy in `accessctl` to include the additional role. The manifest of users for the organization unit is automatically recalculated and the users will be added to the organization unit Okta group that has already been attached to the application.
1. The application CODEOWNER can add the additional **role group** to the application using Terraform.
This provides improved maintenance since the division and department leaders or their delegate (ex. Executive Business Administrator) centrally manage the policies for organization unit groups and which roles are members.
Since the *users* that are attached to each group are managed by `accessctl` policies and REST API calls (not Terraform), the changes to Terraform state management are far and few between which simplifies auditability.
{{% alert title="Not Live Yet" color="warning" %}}
You are viewing a preview of documentation for the future state of GitLab Identity v3 (mid 2024). See the <ahref="https://handbook.gitlab.com/handbook/security/access-management-policy">Access Management Policy</a> for the GitLab Identity v2 current state with baseline entitlements and access requests. See the roadmap in the <ahref="https://gitlab.com/groups/gitlab-com/gl-security/identity/eng/-/roadmap?state=all&sort=start_date_asc&layout=QUARTERS&timeframe_range_type=THREE_YEARS&group_path=gitlab-com/gl-security/identity/eng&progress=WEIGHT&show_progress=true&show_milestones=false&milestones_type=ALL&show_labels=true">epics gantt chart</a>.
{{% /alert %}}
## GitOps Workflow
```mermaid
gitGraph
commit id: "Change 1"
commit id: "Change 2"
branch change
checkout change
commit id:"Current Changes"
commit id:"CI/CD Validate and Plan Jobs" type: REVERSE
We have a GitLab repository for each vendor instance with a `.gitlab-ci.yml` file with CI/CD pipeline jobs for `terraform validate`, `checkov` (Iac SAST scanning), `terraform plan`, `terraform apply`, and `terraform destroy` jobs.
All changes are performed in GitLab branches that have a `terraform validate`, `checkov`, and `terraform plan` job. Merge requests are configured to require all jobs to succeed, all approvals to be obtained and are merged automatically after all approvals.
## Approval Rules
Each merge request requires a peer review and is configured with three (2) [GitLab approval rules](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/). The peer reviewer is allowed to add commits to make fixes or make suggestions in merge request review comments.
1. The **Identity Approval** approval requires review from the Identity Engineering or Identity Operations team to ensure technical accuracy. This can be performed by the Identity Peer Reviewer if they did not make commits. If the Peer Reviewer makes commits, then an additional person must provide approval for separation of duties.
1. The **System Owner** approval uses the [CODEOWNERS](https://docs.gitlab.com/ee/user/project/codeowners/) file that specifies the business owner and technical owner for each directory or file in the Terraform GitLab repository. We rely on GitLab's Tech Stack by default, however this can be updated by the Identity Operations team to be the domain subject matter expert (SME) for the specific configuration.
The merge request is automatically merged after all approvals are provided. **Approval should not be provided until changes are ready to go live.**
When the branch is merged into the `main` branch, the `terraform apply` job is included in the CI/CD pipeline and is run automatically if the `terraform plan` job passes and the changes go live automatically.
## Standardized Modules and Syntax
We have a library of pre-defined modules (configuration templates) that allow us to simply define a few variables in a module configuration block and all of the other syntax is handled within the module for standardization.
Each module can be used in the appropriate Terraform configuration file. See the respective vendor repository for more details.
As part of our transparency, we share this high level explanation of what we do, but do not publicly share the details of how we do it. By exposing this high-level overview, we tend to hear feedback from the community about shortcomings that we can remediate to improve our posture.
The world's source code is more secure when we collaborate on best practices together. If you are able to penetrate this, we'd love to talk to you about joining our team.
Please report any vulnerabilities using our bug bounty and responsible disclosure process.
## Castle Walls
### Administrative Kingdoms
```mermaid
graph TB
subgraph Jamf MDM Profile
subgraph SentinelOne EDM Monitoring
subgraph Separate BLACK 1Password User Account and Vault
subgraph Separate BLACK Okta User Account
subgraph Separate BLACK Google Workspace User Account
subgraph Okta Verify Device Trust
subgraph Okta Hardware 2FA with YubiKey
subgraph NordLayer VPN with Dedicated Gateway Static IPs
subgraph Read-Only Role by Default
subgraph Teleport Two Person Verification for JIT Role Assumption
direction TB
subgraph AWS Identity Center 2FA with YubiKey
BLACK_OPS_KINGDOM["Black Ops Kingdom"]
end
subgraph Google Account Hardware 2FA with YubiKey
PRODUCT_PRD_KINGDOM["Product Prd Kingdom"]
end
end
end
end
end
end
end
end
end
end
end
IDENTITY_USER["Identity Team Member<br />with BLACK Admin Account"]
INFRA_USER["Infrastructure Team Member<br />with BLACK Admin Account"]
BLACK_OPS_KINGDOM --> IDENTITY_USER
PRODUCT_PRD_KINGDOM --> INFRA_USER
```
## Insider Access Trust
The lateral movement controls in each kingdom are different and are not shared publicly. We have additional hidden monitoring controls in sensitive areas to ensure that all activities are monitored by cross-functional teams and actions are verified with the user and mapped to justification documentation (incidents/issues/tickets/etc).
As we iterate from GitLab Identity v2 to GitLab Identity v3, we will be refining our scoped access policies to prevent the potential for lateral movement.
