> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Map external tool users and teams to Port accounts

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor
Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/map-external-users-and-teams-to-port-accounts/

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

This guide demonstrates how to map users from Git, Jira, HiBob, Slack, and ServiceNow to Port user accounts, and map GitHub teams and Okta groups to Port team accounts.

Common use cases​

  • Maintain a complete inventory of external user and team identities in Port.
  • Connect tool-specific identities to one Port account for each user or team.
  • Keep ownership and role-based access control aligned with external team structures.
  • Route self-service actions and automations to the correct users and teams.

Match external identities​

Port uses the _user and _team system blueprints as the canonical accounts for people and teams. Each integration also creates tool-specific entities, such as a GitHub user or an Okta group.

The user mappings in this guide use an email address as the _user identifier. If the email matches an existing Port user, the mapping connects that account to the external user entity. If no account matches, Port creates a disabled user account that an administrator can activate.

The team mappings use the GitHub team slug or Okta group name as the _team identifier. When that identifier matches an existing Port team, the mapping connects it to the external team entity. Adjust the identifier expression if your Port teams use a different naming convention to avoid creating duplicate teams.

Prerequisites​

Before you start, make sure:

  • You have a Port account and have completed the onboarding process.
  • You have permissions to create or update blueprints, integration mappings, self-service actions, and automations in Port.
  • You have installed the relevant integration or have admin/API access to the external tool you want to map.

Map users​

Choose the tab for the external tool you want to map. Each tab is an implementation path for the same outcome: linking external users to Port user accounts.

Git users

Use this option to map GitHub, GitLab, and Azure DevOps users to Port user accounts by matching email addresses.

Set up Git prerequisites

Install and configure the relevant Git integration:

Set up data model

The relations between Git users and Port users are created automatically when we install the relevant Git integrations. If you haven't installed them yet, please do so first.

Optional: Add mirror properties to the Port User blueprint

If you want to display some Git user attributes e.g. username, email, etc. in the Port User blueprint, you can add a mirror property to the Port User blueprint.

Follow the steps below to add a mirror property to the Port User blueprint:

  1. Go to the data model page in Port.

  2. Find the User blueprint and click on it.

  3. Click on the Edit JSON button in the top right corner.

  4. Add the following mirror properties to the mirrorProperties object to display Git user information:

    Port User blueprint mirror properties (Click to expand)
    "mirrorProperties": {
      "github_login": {
        "title": "GitHub login",
        "path": "githubUser.login"
      },
      "gitlab_username": {
        "title": "GitLab username",
        "path": "gitlabUser.username"
      },
      "azuredevops_display_name": {
        "title": "Azure DevOps display name",
        "path": "azureDevopsUser.displayName"
      }
    }

  5. Click on Save to update the blueprint.

Additional mirror properties

You can add more mirror properties to display other Git user attributes or customize which properties are most relevant for your organization. Only add the mirror properties for the Git platforms you're using.

Update integration mapping

Now we'll update the integration mapping to include the relation and create automations to sync Git users when a new Port user is added.

To update the GitHub Ocean integration mapping, follow the steps below:

  1. Go to the Data sources page.

  2. Under Exporters, click on your installed GitHub Ocean integration.

  3. In the mapping configuration, add a new mapping for Port User entities to establish the relation with GitHub users:

    Updated GitHub Ocean integration mapping (Click to expand)
    # Keep existing githubUser mapping
    - kind: user
      selector:
        query: 'true'
      port:
        entity:
          mappings:
            identifier: .login
            title: .login
            blueprint: '"githubUser"'
            properties:
              email: .email

    # Add new mapping for Port Users with relation to GitHub users
    - kind: user
      selector:
        query: '.email != null'
      port:
        entity:
          mappings:
            identifier: .email
            blueprint: '"_user"'
            relations:
              githubUser: .login

  4. Click on Save & Resync to apply the changes.

Set up automation

To ensure new Port users are automatically mapped to their corresponding Git user accounts when a new Port user is created, we'll create an automation that triggers when a new Port user is created.

  1. Go to the Automations page in Port.

  2. Click on + Automation.

  3. Click on the Edit JSON button in the top right corner.

  4. Copy and paste the following automation configuration:

    Automation to sync Port users to Git user accounts (Click to expand)
    {
      "identifier": "sync_port_user_for_git_users",
      "title": "Sync Port User for Git Users",
      "description": "Automatically maps Port users to their corresponding Git user accounts across all platforms",
      "icon": "Git",
      "trigger": {
        "type": "automation",
        "event": {
          "type": "ENTITY_CREATED",
          "blueprintIdentifier": "_user"
        },
        "condition": {
          "type": "JQ",
          "expressions": [],
          "combinator": "and"
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://api.port.io/v1/entities/_user/{{ .event.diff.after.identifier }}/relations",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "relations": {
            "githubUser": {
              "combinator": "and",
              "rules": [
                {
                  "property": "$identifier",
                  "operator": "=",
                  "value": "{{ .event.diff.after.identifier }}"
                }
              ]
            },
            "gitlabUser": {
              "combinator": "and",
              "rules": [
                {
                  "property": "$identifier",
                  "operator": "=",
                  "value": "{{ .event.diff.after.identifier }}"
                }
              ]
            },
            "azureDevopsUser": {
              "combinator": "and",
              "rules": [
                {
                  "property": "$identifier",
                  "operator": "=",
                  "value": "{{ .event.diff.after.identifier }}"
                }
              ]
            }
          }
        }
      },
      "publish": true
    }
    Select the relevant Git integration

    In this automation example, we show how to map Port users to all supported Git platforms (GitHub, GitLab, and Azure DevOps) at once. In practice, you should only configure the relation for the Git platform your organization actually uses. For example, if your users are only in GitHub, include the githubUser relation and remove the others. Adjust the configuration to match your organization's setup.

  5. Click Save to create the automation.

Let's test it!

  1. Go to your Context lake page

  2. Search for a Git user entity (e.g., GitHub User, GitLab User, or Azure DevOps User)

  3. Verify that the user has a relationship with the corresponding Port user account.

  4. Check that the relationship is established automatically for new Git users.

Map teams​

Choose the tab for the external team source you want to map. Each option links a tool-specific team entity to the corresponding Port _team entity.

Meet the GitHub prerequisites

  • You have installed and configured the GitHub integration.
  • Your Port team identifiers match the corresponding GitHub team slugs, or you know how to adapt the identifier mapping.
  • You have permission to update the Team blueprint and the GitHub integration mapping.

Add the GitHub team relation

The GitHub integration creates a githubTeam blueprint for GitHub team data. Add a relation from Port's Team blueprint to that blueprint so each Port team can reference its GitHub identity.

If the githubTeam relation already exists on your Team blueprint, skip these steps and continue to the GitHub integration mapping.

  1. Go to the data model page.

  2. Select the Team blueprint.

  3. Click Edit JSON.

  4. Add the following relation to the blueprint's relations object:

    GitHub team relation (Click to expand)
    "githubTeam": {
      "title": "GitHub team",
      "target": "githubTeam",
      "required": false,
      "many": false
    }

  5. Click Save to update the blueprint.

Update the GitHub mapping

Add a second team resource to the GitHub integration mapping. This resource uses the GitHub team slug as the Port team identifier and links the resulting _team entity to the existing githubTeam entity.

  1. Go to the data sources page.

  2. Select your GitHub integration.

  3. Add the following YAML block to the integration mapping:

    GitHub team-to-Port team mapping (Click to expand)
    - kind: team
      selector:
        query: 'true'
      port:
        entity:
          mappings:
            identifier: .slug
            title: .name
            blueprint: '"_team"'
            relations:
              githubTeam: .databaseId | tostring

  4. Click Save & Resync to apply the mapping.

Align team identifiers

This mapping expects each Port team identifier to match the GitHub team slug. If your identifiers use another convention, update the identifier expression before resyncing to prevent duplicate Port teams.

Test the GitHub team mapping

  1. Go to the Teams page.

  2. Select a team whose identifier matches a GitHub team slug.

  3. Verify that its GitHub team relation points to the corresponding githubTeam entity.

  4. Confirm that the resync did not create duplicate Port teams.

Extend identity mapping​

Add each future user or team mapping source, such as Microsoft Entra ID, Workday, or BambooHR, as another tab in the relevant section of this guide.