Dev Portal team mapping

Uses: Dev Portal

Prerequisites

A test developer account in your IdP
An application for Konnect configured in your IdP:
- Okta
- Azure AD
- Auth0

Set up developer teams and group claims in your IdP

In Okta, assign people to a group, including your test developer account. Alternatively, you can use group rules to automatically add people to a group.
Configure any other group settings and attributes as needed.
Enable group push for Kong Gateway to push existing Okta groups and their memberships to Konnect.
Add a groups claim for the org authorization server.

Map IdP developer teams in Konnect

You can configure more than one IdP for a Dev Portal, but only one IdP can be enabled at a time.

In the Konnect sidebar, click Dev Portal > Portals.
Click your Dev Portal.
Click the Settings tab.
Click the Security tab.
Enable Role-based access control (RBAC).

Enabling RBAC allows you to create teams in Konnect. You can disable RBAC after you map teams from your IdP if you don’t want to use it.
Click the Developers tab.
Click the Teams tab.
Click New Team and configure the team.
From the IdP team you just created, click the APIs tab and click Add Roles. This allows you to assign APIs and the role for the APIs to members of your IdP team.
Navigate back to your Dev Portal overview and click the Settings tab.
Click the Security tab.
In the User authentication settings, click Configure next to OIDC.
Configure the IdP settings using the following mappings:
- Issuer URI: The value stored in the issuer variable from your application in your IdP.
- Client ID: The application ID from your application in your IdP.
- Client Secret: The client secret from your application in your IdP.
- Scopes: The scopes to be requested from your application in your IdP.
- Claim Mappings - Name: name
- Claim Mappings - Email: email
- Claim Mappings - Groups: groups
Click the Team Mapping tab, and then select IdP Mapping Enabled.
Enter the exact name of your team from your IdP next to the name of the Konnect team you want to map it to.
Optional: In the team’s settings, disable Sync with external identity provider (IdP) for any team you don’t want IdP logins to overwrite.

This setting is enabled by default for every new and existing team, even before IdP mapping is configured for the Dev Portal. When enabled, developers are added to or removed from the team automatically at login, based on their groups claim. When disabled, the admin can manage the team manually in Konnect.

Disable this setting when a Dev Portal admin needs to create or manage a team manually without IdP access, or to keep an old IdP’s teams and a new IdP’s teams side by side temporarily during a migration.

If IdP mapping is enabled and this setting is enabled for a Konnect-managed team, Konnect treats the team as an empty IdP group. Developers are removed from the team at their next login, even if they were added manually.

The team you’re mapping to must already exist before you create the mapping. Create it by sending a POST request to the /portals/{portalId}/teams endpoint:
curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/teams" \ --no-progress-meter --fail-with-body \ -H "Authorization: Bearer $KONNECT_TOKEN" \ --json '{ "name": "IDM - Developers", "description": "The Identity Management (IDM) team" }'
Copied!
The team object includes a konnect_managed field. konnect_managed: true means the team is managed manually in Konnect. konnect_managed: false means the team is synced from the IdP. You can change this by sending a PATCH request to the /portals/{portalId}/teams/{teamId} endpoint. If the team is currently mapped to an IdP group, remove the mapping first by sending a DELETE request to the /portals/{portalId}/identity-providers/{id}/team-group-mappings/{mappingId} endpoint.

Configure the IdP by sending a POST request to the /portals/{portalId}/identity-providers endpoint:

curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/identity-providers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "type": "oidc",
       "enabled": true,
       "config": {
         "issuer_url": "https://konghq.okta.com/oauth2/default",
         "client_id": "YOUR_CLIENT_ID",
         "client_secret": "YOUR_CLIENT_SECRET",
         "scopes": [
           "openid",
           "email",
           "profile"
         ],
         "claim_mappings": {
           "name": "name",
           "email": "email",
           "groups": "groups"
         }
       }
     }'

Copied!

Map an IdP group to the team by sending a POST request to the /portals/{portalId}/identity-providers/{id}/team-group-mappings endpoint:

curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/identity-providers/$IDP_ID/team-group-mappings" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "team_id": "'$TEAM_ID'",
       "group": "IDM - Developers"
     }'

Copied!

Test developer team mappings

Now that you’ve configured the IdP team mappings in Konnect for the Dev Portal, you can test the team mappings.

Find your Dev Portal URL in the Dev Portal settings in the Portal Domain, navigate to that URL, and log in as a test developer that is assigned to the team in your IdP.

Migrate developer teams to a new IdP

If you’re moving from one IdP to another, you can freeze your existing teams so they aren’t affected while you set up and test the new IdP.

For each team currently mapped to your old IdP, disable Sync with external identity provider (IdP) in the team’s settings. This excludes the team from synchronization so its membership stays as-is.
Configure and test the new IdP by following Set up developer teams and group claims in your IdP and Map IdP developer teams in Konnect.
After the new IdP’s teams are mapped and verified, delete the old, frozen teams.