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

Check out Port for yourself ➜ 

Map external users 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-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 external users from Git, Jira, Slack, ServiceNow, and HiBob to existing Port user accounts.

Common use cases​

  • Maintain a complete inventory of external users in Port.
  • Link external tool users to Port user accounts based on email addresses.
  • Identify users who exist in external tools but do not have Port accounts.
  • Enrich Port user entities with context from Git, Jira, Slack, ServiceNow, and HiBob.

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, 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 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.

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.