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

Check out Port for yourself ➜ 

Map external users to Port accounts

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 of your portal.

  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 of your portal.

  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 Software catalog 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.