GitLab access patterns in Identity Security

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

Identity Security is available only with Teleport Enterprise.

Gain insights into access patterns within your GitLab account using Identity Security with Access Graph. By scanning all permissions, users, groups, and projects, it provides a visual representation to help enhance the permission model within your GitLab environment. This functionality enables you to answer queries such as:

• What projects are accessible to users?
• Which users have write permissions to projects?

In this guide, you will set up the GitLab integration with Teleport Access Graph and analyze GitLab access patterns.

Access Graph is a feature of the Teleport Identity Security product available to Teleport Enterprise edition customers.

To verify that Access Graph is set up correctly for your cluster, sign in to the Teleport Web UI, click the Identity Security sidebar button, and then the Browse menu item. Identities, resources, etc. should be listed.

How it works

Access Graph synchronizes various GitLab resources, including users, projects, and groups. These resources are then visualized using the graph representation detailed in the Access Graph page.

The importing process involves two primary steps:

Polling GitLab APIs

The Teleport cluster continuously scans the configured GitLab accounts and retrieves the following resources:

• Users
• Groups
• Projects
• Group memberships
• Project memberships

Once all the necessary resources are fetched, Teleport pushes them to Access Graph, ensuring that it remains updated with the latest information from your GitLab instance.

Importing resources

Identity Security's Access Graph feature analyzes the imported resources and their relationships, building a graphical representation of them.

Prerequisites

• A running Teleport Enterprise cluster v15.3.1 or later.
• Identity Security enabled for your account.
• A GitLab instance running GitLab v13.0 or later. GitLab introduced the read_api personal access token scope that this guide requires in v12.10, so any actively maintained GitLab release meets this requirement.
• For self-hosted clusters:
  • Ensure that an up-to-date license.pem is used in the Auth Service configuration.
  • A running Access Graph node v1.21.4 or later. Check the Identity Security page for details on how to set up Access Graph.
  • The node running the Access Graph service must be reachable from the Teleport Auth Service.

Step 1/3. Create a GitLab token

To set up the GitLab integration, create a GitLab personal access token with the following scope:

• read_api

In GitLab, select your avatar, then Edit profile, then Access, then Personal access tokens. Create a new token with the read_api scope and copy the generated token. For more information, see the GitLab documentation.

The importer uses this token to fetch the necessary resources from your GitLab instance.

warning

The GitLab importer only fetches resources that the token has access to. Ensure that the user associated with the token has the necessary permissions to access or view the resources you want to import.

If you're using a GitLab.com account, the importer only fetches the users who are part of the organization or have access to the projects that the token can access.

If you're using a self-hosted GitLab instance, the importer fetches all resources that the token has access to, including all users who are part of the instance.

You will use this token in the next step to configure the GitLab Sync integration.

Step 2/3. Set up Access Graph GitLab sync

To start the setup wizard for configuring GitLab Sync, open the Teleport Web UI, select the Identity Security sidebar button, then select Integrations.

Select Setup new integration, then select GitLab. You'll be prompted to create a new Teleport GitLab integration if you haven't configured one already. Alternatively, you can select a previously established integration.

You'll be prompted to provide the GitLab token you created in Step 1 and your GitLab instance domain. Once the token is validated, you can see the resources imported in Access Graph.

Step 3/3. View GitLab resources in Access Graph

After the GitLab resources are imported, you can view them on the Access Graph page. The graph representation shows the relationships between users, groups, and projects within your GitLab instance.

Users can have permissions to access a group or project. When a user has access to a group, they inherit permissions to all projects and sub-projects within that group.

You can view the permissions granted to users, groups, and projects by selecting the respective nodes in the graph.

For example, to view the permissions granted to a user, select the user node and select View Access from the context menu. This displays the permissions granted to the user and the resources they have access to.

You can also run queries to fetch specific information from Access Graph, such as:

Fetch all projects accessible to a user

The following query fetches all projects accessible to a user user:

SELECT * FROM access_path WHERE "identity" = 'user' AND source='Gitlab'

You can also filter projects by the user's access level, owner, maintainer, developer, guest, or reporter, by running the following query:

SELECT * FROM access_path WHERE "identity" = 'user' AND source='Gitlab' AND action='owner'

Change the action parameter to maintainer, developer, guest, or reporter to fetch the respective projects.

Fetch all users with write access to a project

The following query fetches all users with read and write access to a project named project:

SELECT * FROM access_path WHERE "resource" = 'project' AND source='Gitlab'

Troubleshooting

After setting up the GitLab integration, you can monitor the import process status on the Access Graph Integrations page. If the import fails, an error message helps identify the issue.

You can also check whether the import process is currently running or has completed successfully by viewing the status.

If you encounter Unauthorized errors, ensure that the GitLab token has the necessary permissions to access the resources and that the token is valid. If the token has expired, create a new token and update the integration settings.

If you encounter other issues, ensure that the Teleport cluster can reach the GitLab instance and that the GitLab APIs are accessible.

If you're still facing issues, inspect the error log on the Access Graph Integrations page for more details.