Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
    • Overview of Konnect
    • Architecture
    • Network Resiliency and Availability
    • Port and Network Requirements
    • Compatibility
    • Stages of Software Availability
    • Release Notes
      • Control Plane Upgrades FAQ
      • Supported Installation Options
    • Overview
    • Access a Konnect Account
    • Set up a Runtime
    • Configure a Service
    • Implement and Test the Service
      • Publish and Consume Services
      • Register Applications
    • Import Kong Gateway Entities into Konnect
    • Overview
      • Overview
      • Dashboard
      • Manage Runtime Groups with UI
      • Manage Runtime Groups with decK
      • Installation Options
      • Install with Docker
      • Install on Kubernetes
      • Install on Linux
      • Install on AWS
      • Install on Azure
      • Upgrade a Runtime Instance to a New Version
      • Renew Certificates
      • Runtime Parameter Reference
    • Create Consumer Groups
      • Overview
      • Set Up and Use a Vault in Konnect
    • Kong Gateway Configuration in Konnect
    • Plugin Ordering Reference
    • Troubleshoot
    • Overview
    • Manage Service Documentation
      • Overview
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
    • Overview
    • Access the Dev Portal
    • Sign Up for a Dev Portal Account
      • Manage Developer Access
      • Manage Application Registration Requests
      • Manage Application Connections
      • Auto Approve Dev and App Registrations
      • Azure OIDC
      • Application Overview
      • Enable and Disable App Registration
        • Overview
        • Okta
        • Curity
        • Auth0
      • Create, Edit, and Delete an Application
      • Register an Application with a Service
      • Generate Credentials for an Application
    • Customize Dev Portal
    • Troubleshoot
    • Introduction to Analytics
    • Analyze Services and Routes
    • Reports Use Cases
    • Reports Reference
    • Troubleshoot
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Overview
        • Overview
        • Manage Teams
        • Teams Reference
        • Roles Reference
      • Manage Users
      • Manage System Accounts
      • Set up SSO with OIDC
      • Set up SSO with Okta
      • Login Sessions Reference
    • Account and Org Deactivation
    • Troubleshoot
    • Overview
      • API Documentation
      • Identity Integration Guide
      • API Documentation
      • API Documentation
      • Portal RBAC Guide
      • Overview
      • Nodes
      • Data Plane Certificiates
        • Services
        • Routes
        • Consumers
        • Plugins
        • Upstreams
        • Certificates
        • CA Certificates
        • SNIs
        • Targets
        • Vaults
      • API Spec
      • Filtering
    • Labels

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Appearance
  • Custom Dev Portal URL
    • Configure DNS
    • Update Dev Portal URL settings
    • Domain name restrictions
    • Delete a custom URL
    • Troubleshoot DNS
  • Single sign-on
    • Configuration requirements
    • OIDC Details
Kong Konnect
  • Home
  • Kong Konnect
  • Dev Portal
  • Customize the Konnect Dev Portal

Customize the Konnect Dev Portal

Appearance

The Dev Portal can be customized by those with admin roles via the Appearance settings in the Konnect admin UI. To access the appearance settings, click dev-portal icon Dev Portal, then Appearance.

From the Appearance menu you have the ability to modify the following options:

  • Logos: default logo and favicon
  • Home Page Header: welcome message, primary header, and header image
  • Colors: background, text, and button colors
  • Themes: default theme and dark mode
  • Fonts

For details on the requirements for each customizable option, hover over the information (i) icon next to each item in the UI.

Custom Dev Portal URL

Every Dev Portal instance has an auto-generated default URL. You can also manage custom URLs within Konnect. This gives users the ability to access the Dev Portal from either the default URL, for example https://example.us.portal.konghq.com, or a custom URL like portal.example.com.

To add a custom URL to Dev Portal, you need:

  • A domain and access to configure the domain’s DNS CNAME records.
  • Your organization’s auto-generated default Dev Portal URL.

Configure DNS

In your DNS configuration, create a CNAME record for the domain you want to use using the automatically generated Dev Portal URL. The record will look like this:

Type Name Value
CNAME portal https://example.us.portal.konghq.com

Update Dev Portal URL settings

To add a custom URL to Dev Portal, open dev-portal icon Dev Portal, click Settings, then follow these steps:

  1. Open the Portal URL tab.

  2. Enter the fully qualified domain name (FQDN) including the subdomain, if applicable, into the Custom Portal URL field. Don’t include a path or protocol (e.g. https://).

  3. Click Save Custom Domain.

  4. Click Confirm to begin the domain verification process.

Domain name restrictions

Because of SSL certificate authority restrictions, Konnect can’t generate SSL certificates for the following domains:

  • TLDs containing a brand name: .aws, .microsoft, .ebay
  • Hosting provider subdomains: .amazonaws.com, .azurewebsites.net
  • TLDs restricted by US export laws:
    • .af Afghanistan
    • .by The Republic of Belarus
    • .cu Cuba
    • .er Eritrea
    • .gn Guinea
    • .ir Islamic Republic of Iran
    • .kp Democratic People’s Republic of Korea
    • .lr Liberia
    • .ru The Russian Federation
    • .ss South Sudan
    • .su Soviet Union
    • .sy Syrian Arab Republic
    • .zw Zimbabwe

If you have any questions, contact Support.

Delete a custom URL

Delete a custom Dev Portal URL through your organization’s Konnect admin UI.

  1. In Konnect, open dev-portal icon Dev Portal, then click Settings.

  2. Open the Portal URL tab.

  3. Click Delete Custom Domain

Troubleshoot DNS

After the DNS verification process is complete, Konnect will attempt to automatically generate an SSL certificate for your custom domain. This process can take several hours. If you attempt to access the custom URL from a browser before the certificate generation process is finished, you will receive an SSL certificate error. If this process takes more than 24 hours, please check if the new DNS record is correctly applied. You can use the dig tool to troubleshoot your DNS:

  • Run dig, replacing CUSTOM_DOMAIN with your custom domain and CUSTOM_DOMAIN_DNS with the DNS server for the custom domain:

     dig +nocmd @CUSTOM_DOMAIN_DNS cname CUSTOM_DOMAIN +noall +answer
    

    The output will look like this:

     portal.example.com.	172	IN	CNAME	example.us.portal.konghq.com.
    

where portal.example.com is your custom domain and example.us.portal.konghq.com is the default auto-generated URL for your Dev Portal.

Note: If the command returns no output, or the values are incorrect, check the custom domain DNS configuration or contact your DNS provider. You may need to reset your Dev Portal domain settings to fix your DNS records, you can do this by deleting the custom URL and setting the portal URL again.

Single sign-on

A Konnect admin can configure single sign-on (SSO) for the Dev Portal via the identity settings in the Konnect admin interface.

To configure single sign-on, open dev-portal icon Dev Portal, click Settings, then follow these steps:

  1. Open the Identity tab.

  2. Copy the callback URL and enter it in your identity provider.

  3. Enter the full domain, including the subdomain and protocol, into the Provider URL field (also known as Issuer). For example, https://accounts.google.com for Google IdP.

  4. Enter the unique identifier provided by the IdP into the Client ID field.

  5. Enter the secret used to verify ownership of your IdP client into the Client Secret field.

Configuration requirements

You must always have a form of authentication configured. Built-in and SSO can be used individually or in combination. Each state results in a different user experience, as represented in the following table:

State SSO registration SSO sign in Built-in registration Built-in sign in Information
SSO: Enabled
Built-in: Disabled
✅ ✅ ❌ ❌ - Developers can register and log in with SSO.

- Developers registered with built-in authentication are forced to use SSO.

- The built-in authentication window does not display from the Dev Portal.
SSO: Disabled
Built-in: Enabled
❌ ❌ ✅ ✅ - Developers can register and log in with a username and password.
SSO: Enabled
Built-in: Enabled
✅ ✅ ✅ ✅ - Developers can register and log in with either form of authentication.

OIDC Details

  • If a user account associated with a Konnect developer is removed from the IdP, the Konnect developer account is not deleted. A Konnect admin must delete it from the Konnect dashboard.
  • If a Konnect developer associated with an IdP user is deleted, the same IdP user can re-authenticate with the Dev Portal and a new Konnect developer account is created. To persistently revoke access for developers authenticating through your IdP, you must remove the ability for that user to authenticate with the IdP.
  • User information from the IdP is not synced with Konnect developers after the first login.
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023