Home / How-to Guides
Edit
Report

Enable key authentication for Dev Portal apps

Uses: Kong Gateway Dev Portal deck
Incompatible with
on-prem
Related Documentation
Gateway Documentation decK Documentation
Tags
#application-registration #key-auth #authentication
Related Resources
Application registration
Application authentication strategies
Dev Portal developer sign-up
Enable self-managed OIDC auth with Okta in Dev Portal
TL;DR

In Konnect, configure a key auth strategy with the authentication headers you want to allow and apply it to an API. Any developers who register an application for an API with this authentication strategy applied to it can authenticate by sending apikey: $CREDENTIAL as a header.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

     export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

     curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

     export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
 export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

decK   v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

  1. Run the following command:

    echo '
_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
' | deck gateway apply -

To learn more about entities, you can read our entities documentation.

Kong Konnect roles

To use this tutorial, you need the following Kong Konnect roles:

  • Portal Creator
  • Content Editor
  • Gateway Service Admin
  • API Creator
  • Auth Strategy Creator
  • API Publisher

Configure a Dev Portal

For this tutorial, you’ll need a Dev Portal and some Dev Portal settings pre-configured. These settings are essential for Dev Portal to function but configuring them isn’t the focus of this guide. If you don’t have these settings already configured, follow these steps to pre-configure them:

  1. Create a Dev Portal: 

    curl -X POST "https://us.api.konghq.com/v3/portals" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyDevPortal",
       "authentication_enabled": true,
       "auto_approve_applications": true,
       "auto_approve_developers": true,
       "default_api_visibility": "public",
       "default_page_visibility": "public"
     }'
  2. Export your Dev Portal ID and URL from the output: 
    export PORTAL_ID='YOUR-DEV-PORTAL-ID'
export PORTAL_URL='YOUR-DEV-PORTAL-DOMAIN'

  3. Create a page in your Dev Portal so published APIs will display: 

    curl -X POST "https://us.api.konghq.com/v3/portals/$PORTAL_ID/pages" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "title": "My Page",
       "slug": "/",
       "description": "A custom page about developer portals",
       "visibility": "public",
       "status": "published",
       "content": "# Welcome to My Dev Portal\nExplore the available APIs below:\n::apis-list\n---\npersist-page-number: true\ncta-text: \"View APIs\"\n---\n"
     }'

Register a Dev Portal developer account

Register a test developer account with your Dev Portal by navigating to your Dev Portal and clicking Sign up:

open https://$PORTAL_URL/

For the purpose of this tutorial, we’ve set our Dev Portal to automatically approve developer registrations.

Publish an API

  1. Create an API using the /v3/apis endpoint: 

    curl -X POST "https://us.api.konghq.com/v3/apis" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyAPI",
       "attributes": {
         "env": [
           "development"
         ],
         "domains": [
           "web",
           "mobile"
         ]
       }
     }'

    Export the ID of your API from the response:

    export API_ID='YOUR-API-ID'

  2. First, send a request to the /v2/control-planes endpoint to get the ID of the quickstart Control Plane: 

    curl -X GET "https://us.api.konghq.com/v2/control-planes?filter%5Bname%5D%5Bcontains%5D=quickstart" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

    Export your Control Plane ID:

    export CONTROL_PLANE_ID='YOUR-CONTROL-PLANE-ID'

  3. Next, list Services by using the /v2/control-planes/{controlPlaneId}/core-entities/services endpoint: 

    curl -X GET "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/services" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

    Export the ID of the example-service:

    export SERVICE_ID='YOUR-GATEWAY-SERVICE-ID'

  4. Associate the API with a Service using the /v3/apis/{apiId}/implementations endpoint: 

    curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/implementations" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "service": {
         "control_plane_id": "'$CONTROL_PLANE_ID'",
         "id": "'$SERVICE_ID'"
       }
     }'

  5. Now you can publish the API to your Dev Portal using the /v3/apis/{apiId}/publications/{portalId} endpoint: 

    curl -X PUT "https://us.api.konghq.com/v3/apis/$API_ID/publications/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Configure key auth application authentication in Dev Portal

Configure key auth application authentication using the /v2/application-auth-strategies endpoint:

curl -X POST "https://us.api.konghq.com/v2/application-auth-strategies" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "Key Auth",
       "display_name": "Key Auth",
       "strategy_type": "key_auth",
       "configs": {
         "key-auth": {
           "key_names": [
             "apikey",
             "x-api-key",
             "api-key"
           ]
         }
       }
     }'

Export the ID of the key auth strategy:

export AUTH_STRATEGY_ID='YOUR-AUTH-STRATEGY-ID'

Apply the key auth strategy to an API

Now that the application auth strategy is configured, you can apply it to an API using the /v3/apis/{apiId}/publications/{portalId} endpoint:

curl -X PUT "https://us.api.konghq.com/v3/apis/$API_ID/publications/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "auth_strategy_ids": [
         "'$AUTH_STRATEGY_ID'"
       ]
     }'

This request will also publish the API to the specified Dev Portal.

Create an app in Dev Portal

To use key auth credentials to authenticate with an app, you must first create an app in Dev Portal with the test developer account you created previously.

  1. Navigate to your Dev Portal and log in with the test developer account: 
    open https://$PORTAL_URL

    You should see MyAPI in the list of APIs.

  2. To register an app with the API, click View APIs.
  3. Click Use this API.
  4. In the pop-up dialog, enter a name for the app and your client ID for your application.
  5. Click Save.
  6. Copy, save, and export your key auth credential: 
    export CREDENTIALS='YOUR-KEY-AUTH-CREDENTIALS'
  7. Click Copy and close.

Validate the password grant

Now, validate the setup by accessing the example-route Route and passing the key auth credentials in the apikey: $CREDENTIALS format. You can use any of the headers that you specified when you configured the key auth strategy.

Validate that key authentication was successfully enabled by sending a request to the example-route Route with your key auth credentials:

curl -i -X GET "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "apikey: $CREDENTIALS"

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

FAQs

My published API is private in Dev Portal, how do I allow developers to see it?

If an API is published as private, you must enable Dev Portal RBAC and developers must sign in to see APIs.

Next Steps

Learn how to manage application registration requests
Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support