Customize the Konnect Dev Portal

Appearance

To customize Dev Portal, you have two options:

Basic customization using the Dev Portal Appearance settings in the UI
Complete customization using the open source Dev Portal client

Basic customization

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, 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.

Complete customization using the open source Dev Portal

You can completely customize the Dev Portal using the open source Dev Portal client. To enable the self-hosted Dev Portal, navigate to Dev Portal > Settings, then set up a custom hosted domain and a custom self-hosted UI domain in the Portal Domain tab. They must share a common top-level and second-level domain for security purposes (e.g. api-developer.company.com and developer.company.com)

This self-hosted portal provides the following benefits:

Fully customizable: Use the example frontend Dev Portal application as a starting point and then customize Dev Portal for your needs using the Portal API and Portal SDK. You can also integrate the API specs with workflows tailored to your organization’s own processes.
Hosting service choice: When you self-host, you also get to choose which hosting service you use to deploy your Dev Portal.
Range of customization options: With the self-hosted Dev Portal, you determine how much you want to customize. You can choose to use the example application right out of the box, or you can use the Portal API and Portal SDK for more fine-grained control.

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.

You can also choose to self-host the Dev Portal with Netlify or any other static hosting service that supports single page applications.

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, click Settings, then follow these steps:

Open the Portal Domain tab.
Enter the fully qualified domain name (FQDN) including the subdomain, if applicable, into the Custom Hosted Domain field. Don’t include a path or protocol (e.g. https://).
Click Save Custom Domain.
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.

In Konnect, open Dev Portal, then click Settings.
Open the Portal Domain tab.
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, click Settings, then follow these steps:

Open the Identity tab.
Copy the callback URL and enter it in your identity provider.
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.
Enter the unique identifier provided by the IdP into the Client ID field.
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.