> 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 if your tool supports it; otherwise present the plan below filled in and wait for my approval. Implement this Port guide in my org via MCP:

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

Read the raw markdown version at https://docs.port.io/guides/all/map-external-users-and-teams-to-port-accounts.md - it contains every tab and code block without page markup.

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. If the guide offers alternative implementation paths (tabs), pick the one matching my installed integrations and tools, confirm it with me, and implement only that path.
3. Diff the guide's data model (blueprints, properties, relations, workflows, actions, agents, automations, integrations, webhook data sources, secrets) against mine.
4. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
5. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out. If the guide has a "Set up via API" section, use it for anything MCP can't do before treating a step as UI-only.
6. 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.
- Never print secret values into the chat or logs; ask me to set them in Port, or write them via the secrets API without echoing them back.
- 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 and not covered by the guide's API sections, 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:
- Run the guide's "Let's test it" steps where possible (e.g. execute a workflow test run) and confirm the expected output exists in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

This guide demonstrates how to map external users from Git, Jira, Slack, ServiceNow, and HiBob to existing Port user accounts using Port Workflows.

Open Beta

Port workflows are currently in open beta and available to all users. Workflows may undergo changes without prior notice.

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 and workflows in Port.
  • You have installed the relevant integration or have admin/API access to the external tool you want to map.

How it works​

All five integration paths follow the same pattern, implemented with Port Workflows:

  • Git and Jira: the integration mapping links external users to Port users during every sync. A small workflow with an event trigger completes the mapping whenever a new Port user is created.
  • Slack, ServiceNow, and HiBob: a single workflow with three triggers does all the work:
    • A self-service trigger runs a bulk sync on demand. The workflow fetches all users from the external API and forwards them to a custom webhook data source, which creates the user entities and links matching Port users.
    • A schedule trigger runs the same bulk sync automatically every day.
    • An event trigger fires when a new Port user is created, looks up the matching external user by email, and links the two entities directly.

Every resource in this guide can be created from Port's UI or via Port's API. Each tab ends with a Set up via API section that scripts the entire setup, which is useful for automation or when implementing this guide with an AI agent.

Map users by integration​

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.

In this tab we will create the following resources:

ResourceNamePurpose
Integration mapping updateGitHub Ocean / GitLab / Azure DevOpsLinks Git users to Port users on every sync.
Workflowsync_port_user_for_git_usersMaps Git users when a new Port user is created.

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, so the workflow below has a Git user to link against 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.

Build the workflow

To ensure new Port users are automatically mapped to their corresponding Git user accounts when a new Port user is created, we'll build a workflow that triggers when a new Port user is created and links the relations via Port's API.

  1. Go to the Workflows page in Port.

  2. Click on the + Workflow button in the top-right corner.

  3. Click on the Skip to editor button.

  4. Copy and paste the workflow JSON below into the editor to replace the example workflow:

    Sync Port User for Git Users workflow JSON (Click to expand)
    {
      "identifier": "sync_port_user_for_git_users",
      "title": "Sync Port User for Git Users",
      "icon": "Git",
      "description": "Automatically maps Port users to their corresponding Git user accounts across all platforms",
      "nodes": [
        {
          "identifier": "trigger",
          "title": "On Port user created",
          "config": {
            "type": "EVENT_TRIGGER",
            "event": {
              "type": "ENTITY_CREATED",
              "blueprintIdentifier": "_user"
            }
          }
        },
        {
          "identifier": "map_git_relations",
          "title": "Map Git user relations",
          "config": {
            "type": "WEBHOOK",
            "url": "https://api.port.io/v1/entities/_user/{{ .outputs.trigger.diff.after.identifier }}/relations",
            "method": "POST",
            "headers": {
              "Content-Type": "application/json"
            },
            "body": {
              "relations": {
                "githubUser": {
                  "combinator": "and",
                  "rules": [
                    {
                      "property": "$identifier",
                      "operator": "=",
                      "value": "{{ .outputs.trigger.diff.after.identifier }}"
                    }
                  ]
                },
                "gitlabUser": {
                  "combinator": "and",
                  "rules": [
                    {
                      "property": "$identifier",
                      "operator": "=",
                      "value": "{{ .outputs.trigger.diff.after.identifier }}"
                    }
                  ]
                },
                "azureDevopsUser": {
                  "combinator": "and",
                  "rules": [
                    {
                      "property": "$identifier",
                      "operator": "=",
                      "value": "{{ .outputs.trigger.diff.after.identifier }}"
                    }
                  ]
                }
              }
            }
          }
        }
      ],
      "connections": [
        {
          "sourceIdentifier": "trigger",
          "targetIdentifier": "map_git_relations"
        }
      ]
    }
    Select the relevant Git integration

    In this workflow 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 save the workflow.

The workflow should look like this in the editor:

Git user mapping workflow canvas showing an event trigger for new Port users connected to a webhook node that maps Git user relations

Since this workflow calls https://api.port.io, it's automatically authenticated with your organization's credentials, so no secrets are needed.

Optional: Set up via API

Instead of using the UI, you can create the resources in this tab with Port's API. The integration mapping update is organization specific, so update it from the Data sources page as shown above.

API setup script (Click to expand)

Save the workflow JSON above to sync_port_user_for_git_users.json, then run:

# Get an API access token
PORT_TOKEN=$(curl -s -X POST "https://api.port.io/v1/auth/access_token" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "<YOUR_CLIENT_ID>", "clientSecret": "<YOUR_CLIENT_SECRET>"}' | jq -r '.accessToken')

# Optional: add the Git mirror properties to the Port User blueprint (merges with the existing blueprint)
curl -s "https://api.port.io/v1/blueprints/_user" -H "Authorization: Bearer $PORT_TOKEN" | jq '.blueprint
  | .mirrorProperties.github_login = {"title": "GitHub login", "path": "githubUser.login"}
  | .mirrorProperties.gitlab_username = {"title": "GitLab username", "path": "gitlabUser.username"}
  | .mirrorProperties.azuredevops_display_name = {"title": "Azure DevOps display name", "path": "azureDevopsUser.displayName"}' \
  | curl -s -X PUT "https://api.port.io/v1/blueprints/_user" \
      -H "Authorization: Bearer $PORT_TOKEN" -H "Content-Type: application/json" --data-binary @-

# Create the workflow
curl -s -X POST "https://api.port.io/v1/workflows" \
  -H "Authorization: Bearer $PORT_TOKEN" -H "Content-Type: application/json" \
  --data-binary @sync_port_user_for_git_users.json
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

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, and follow the run in the Workflow runs tab.

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.