Developer self-service and application registration

Konnect Dev Portal provides flexible options for controlling access to content and APIs. When combined with a Gateway Service, developers visiting a Dev Portal can sign up, create an application, register it with an API, and retrieve API keys without intervention from Dev Portal administrators.

Developer self-service consists of two main components:

• User authentication: Allows users to access your Dev Portal by logging in. You can further customize what logged in users can see using RBAC.
• Application registration: Allows developers to use your APIs using credentials and create applications for them.

To enable developer self-service, do the following:

1. Enable user authentication by navigating to Settings > Security in your Dev Portal.

   Developer sign ups and application creation require admin approval by default, which can also be configured in the Dev Portal security settings.

   For private Dev Portals, user authentication is enabled by default, and the default application auth strategy is key authentication.

2. Configure an application authentication strategy by navigating to Settings > Security.
3. Optional: Enable application sharing for developer teams by navigating to your Dev Portal in Konnect and going to Access and approvals > Teams. Click the team, go to Settings and enable Allow team to own applications.

4. Link an API to a Gateway Service.

   This is required to enforce auth strategies.

5. Publish an API to a Dev Portal.
6. Select an authentication strategy when publishing the API to a Dev Portal.
7. For public content with restricted access, use visibility settings to show public pages or APIs to anonymous users while restricting actions to logged-in users.

Enabling user authentication requires users to register with the Dev Portal. You can decide which pages remain public and which ones require authentication.

Dev Portal supports the following user authentication types:

• Basic authentication
• OIDC
• SAML

Additionally, you can enable RBAC from your Dev Portal’s security settings to control who can view or view and consume APIs in your Dev Portal. When RBAC is enabled, any Dev Portal teams and roles you apply to a developer will control their access.

To get started with user authentication, see the following how-tos:

• Configure Dev Portal SSO
• Dev Portal IdP team mappings
• Dev Portal RBAC

Application authentication allows developers to authenticate with your API using credentials. Developers use the credentials from the authentication strategy when they use an API from your Dev Portal. You can define and reuse multiple authentication strategies for different APIs and Dev Portals.

When you select an authentication strategy during API publication to a Dev Portal, Konnect automatically applies the strategy to the linked Gateway Service.

Dev Portal supports the following authentication strategies:

• Key authentication (key-auth)
• OpenID Connect (oidc)
• Dynamic Client Registration (DCR)

If a Gateway Service isn’t associated with the API when you choose an authentication strategy, the settings are saved and applied once a Service is linked. If a Service is later unlinked, the authentication strategy is applied to the next linked Service.

To automatically create and manage Dev Portal applications using Dynamic Client Registration, see the following guides:

Okta

Azure AD

Auth0

Curity

You can choose to auto approve developers and applications or require admin approval for developers and applications by navigating to Settings and the Security tab in your Dev Portal settings.

If your settings require developer or application approval, you can manage approvals by navigating to Access and approvals in the sidebar. You need the API Registration Approver and Portal Viewer role assigned to the Teams that control the APIs to approve these. Additionally, you can add developers to teams by clicking on the settings menu next to the name of the developer.

Once approved, developers can create applications and view APIs, and the application can generate credentials to use the APIs.

Applications and API keys are specific to a geographic region. When you enable application registration by selecting an authentication strategy during publication, the resulting applications and API keys are tied to the developers and traffic in that region.

Automate developer creation

You can pre-create developer accounts to provision their team association and API access before they access the Dev Portal.

1. To automatically create developers and send them an email to create a password, send a POST request to the /portals/{portalId}/developers endpoint:

   curl -X POST "https://us.api.konghq.com/v3/portals/$DEV_PORTAL_ID/developers" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "full_name": "Raina Sovani",
          "email": "raina.sovani@example.com",
          "status": "approved",
          "send_invitation_email": true
        }'

   Copied!
2. Copy and export the developer ID:

     export DEVELOPER_ID='YOUR DEVELOPER ID'

   Copied!

3. Add the developer to an existing team that has the correct roles for the APIs they need access to by sending a POST request to the /portals/{portalId}/teams/{teamId}/developers endpoint:

   curl -X POST "https://us.api.konghq.com/v3/portals/$DEV_PORTAL_ID/teams/$TEAM_ID/developers" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "id": "'$DEVELOPER_ID'"
        }'

   Copied!

Logging in to Dev Portals:

• SSO: If a developer is created in a Dev Portal with SSO configured, they must be able to use SSO to log in if their email address is configured in the identity provider. After they log in, they will automatically be approved. Both OIDC and SAML SSO are supported.
• Basic auth: If a developer is created in a Dev Portal with basic auth configured, they must be able to set their password. This can be done one of two ways:
  • send_invitation_email: true: Developers can use the link in the email to set their password.
  • Developers can click Forgot password in the Dev Portal UI to set a password, regardless of whether send_invitation_email is true or false.

Automate application creation

You can automate applications and application registrations on behalf of a developer or team using the Konnect API. The authentication strategy you want to use must be enabled on your Dev Portal and your published API. Key auth credentials can’t be automatically created or imported.

1. Create a developer application by sending a POST request to the /portals/{portalId}/applications endpoint:

   curl -X POST "https://us.api.konghq.com/v3/portals/$DEV_PORTAL_ID/applications" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "KongAir Application",
          "description": "A portal application provisioned for a developer by a Portal Admin.",
          "auth_strategy_id": "'$AUTH_STRATEGY_ID'",
          "owner": {
            "id": "'$DEVELOPER_ID'",
            "type": "developer"
          }
        }'

   Copied!

   If the application is for a team, configure owner.type: team and set owner.id to the team ID instead of $DEVELOPER_ID.

2. Copy and export the application ID:

     export APPLICATION_ID='YOUR APPLICATION ID'

   Copied!

3. Create an application registration by sending a POST request to the /portals/{portalId}/applications/{applicationId}/registrations endpoint:

   curl -X POST "https://us.api.konghq.com/v3/portals/$DEV_PORTAL_ID/applications/$APPLICATION_ID/registrations" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "api_id": "'$API_ID'",
          "status": "approved"
        }'

   Copied!

   DCR applications: If the application will be using a DCR provider with the given auth strategy, your configuration depends on your use case:

   • You want to create a new DCR application, where the IdP client will be created in the identity provider and assigned a client_id. This will be set as the client_id of the application and can’t be changed moving forward. Do not specify dcr_client_id or client_id in this case. client_id will be present in the response.
   • You want to create an application that is linked to an existing IdP client, but treated as if it was created via the DCR app creation process. This allows you to import existing IdP clients when onboarding your applications into Konnect. In this case, you must specify dcr_client_id and client_id will be present in the response.

Share applications with a team

You can assign an application to a team so that all members of that team share ownership of the application. Any team member can edit, manage, and use the application. Apps shared by a team appear in each member’s apps in the Dev Portal. Team membership and roles are managed via Dev Portal teams and roles.

This is useful in cases such as when a developer leaves your organization. With team application sharing, the team retains uninterrupted access to the application.

Important considerations:

• All members of the team that owns an application receive full ownership access.
• Applications can only be transferred to teams that have API Consumer access for every API currently registered by the application. Similarly, you can only register APIs to team-owned applications if everyone in the team has access to the API. This is true even if an individual team member has broader access through other teams.

To enable team application sharing, navigate to your Dev Portal in Konnect and click Access and approvals > Teams. Click the relevant team, go to Settings, and enable Allow team to own applications. To transfer ownership of an application to either a developer or team, navigate to the app and from the Actions dropdown menu, select “Transfer ownership”.

For more information about how to configure Dev Portal developer teams, see Dev Portal RBAC. For more information about the developer experience, see Dev Portal developer sign-up.

Limitations

Keep the following limitations in mind for developers and applications:

• Each developer can create a maximum of 500 applications.
• Each application can have a maximum of 20 API keys.
• Each API that uses the ACE plugin can have a maximum of 1,000 operations.
• API Packages have a per-request PATCH limit of 100.

You can apply Kong Gateway plugins to your Dev Portal applications. This lets you enforce business logic, such as rate limiting or IP restriction, on the credentials that an application uses to access your APIs.

The following table shows common use cases for applying plugins to applications:

Plugins can be applied to an application by either linking the application to an existing Consumer in Kong Gateway or applying the plugin via conditional execution logic to the associated principal. When a developer creates an application, Dev Portal automatically creates a Kong Identity principal for this application. This principal entity then helps link the application to an existing Consumer entity in Kong Gateway. Kong Identity doesn’t store any credentials for applications. It is only used for mapping an application to a Consumer.

Since application to Consumer linking uses Kong Identity in the backend, there may be some latency impact to the first request.

You can apply plugins to an application in two different ways:

Apply a plugin to an application using a Kong Identity principal

This method applies the plugin based on the application’s principal, without requiring you to map the application to a Gateway Consumer. The plugin runs whenever a request authenticates as that application, using a conditional plugin execution expression that references the application’s principal.id.

In this example, we’ll use the Rate Limiting Advanced plugin, but you can apply any plugin to an application’s principal with principal.id.

1. List the applications in your portal, filtering by the application’s name, and capture its ID as the PRINCIPAL_ID variable. Replace $PORTAL_ID with your portal ID and $APPLICATION_NAME with the name of your application:

   PRINCIPAL_ID=$(curl -X GET "https://us.api.konghq.com/v3/portals/$PORTAL_ID/applications?filter%5Bname%5D%5Beq%5D=$APPLICATION_NAME" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].id"
   )

   Copied!

   The principal ID is the same as the application’s ID.

2. Configure the Rate Limiting Advanced plugin and use a conditional plugin execution expression to apply it to the application’s principal. Replace $CONTROL_PLANE_ID with the ID of the control plane that your API is linked to:

   curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/plugins/" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "rate-limiting-advanced",
          "config": {
            "limit": [
              200
            ],
            "window_size": [
              1800
            ],
            "window_type": "fixed",
            "namespace": "my-namespace"
          },
          "condition": "principal.id == \"'$PRINCIPAL_ID'\""
        }'

   Copied!

   Any request that authenticates as this application is now rate limited to 200 requests every 30 minutes.

Map an application to a Consumer

Mapping an application to a Consumer requires either the Control Plane Admin or Consumer Admin roles, granted for each API instance registered by the application.

curl -X PUT "https://us.api.konghq.com/v3/portals/$PORTAL_ID/applications/$APPLICATION_ID/registrations/$REGISTRATION_ID/consumer" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "id": "'$CONSUMER_ID'"
     }'

Any plugins that were applied to the Consumer are now applied to the Dev Portal application.

Limitations

Keep the following in mind when you map applications to Consumers or principals:

• Both the KAA and ACE plugins look up principals to resolve the Consumer mapped to an application.
• An application maps to a single Consumer (a 1:1 mapping through one principal).
• If you’re mapping applications to Consumers, the Consumer must already exist. The Dev Portal validates that the Consumer exists on the Gateway before it will be mapped.
• Application registrations for APIs that are linked to the same Gateway Service will share the same effective Consumer mapping. Updating the mapping for one registration updates it for all registrations that resolve to the same Gateway context.
• Applying plugins to applications is only available on v3 Dev Portals.
• Since application to Consumer linking uses Kong Identity in the backend, there may be some latency impact to the first request.