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
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Supported identity providers
    • Resources
  • Supported OAuth flows
    • Client Credentials Flow
    • Authorization Code Flow
    • Implicit Grant Flow
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Kong Enterprise
  • Dev Portal
  • Authentication
  • Third-party OAuth2 Support for Application Registration
You are browsing documentation for an outdated version. See the latest documentation here.

Third-party OAuth2 Support for Application Registration

Third-party OAuth2 support allows developers to centralize application credentials management with the supported Identity Provider of their choice. To use the external IdP feature, set the portal_app_auth configuration option to external-oauth2 in the kong.conf.default configuration file. For more information, see setting the Authorization Provider Strategy.

The Kong OIDC and Portal Application Registration plugins are used in conjunction with each other on a Service:

  • The OIDC plugin handles all aspects of the OAuth2 handshake, including looking up the Consumer via custom claim (the custom_id matches the identity provider client_id claim).

  • The Application Registration plugin is responsible for checking the mapped Consumer and ensuring the Consumer has the correct ACL (Access Control List) permissions to access the Route.

Supported identity providers

The Kong OIDC plugin supports many identity providers out of the box. The following providers have been tested for the current version of the Kong Portal Application Registration plugin used in tandem with the Kong OIDC plugin:

  • Okta. See the Okta setup example.
  • Azure. See the Azure setup example.
  • Ping Identity.

Resources

How you authenticate with a Service depends on its underlying OAuth2 implementation. For more information, reference the documentation below for your implemented identity provider and OAuth flow.

  • Okta
    • Authorization Code Flow
    • Authorization Code Flow (PKCE)
    • Client Credentials Flow
    • Implicit Grant Flow
  • Azure
    • Authorization Code Flow
    • Client Credentials Flow
    • Implicit Grant Flow
  • Ping Identity
    • Oauth2 Developers Guide

Supported OAuth flows

  • Client Credentials (RFC 6742 Section 4.4)
  • Authorization Code (RFC 6742 Section 4.1)
  • Implicit Grant (RFC 6742 Section 4.2)
  • Password Grant (RFC 6742 Section 4.3)

Password Grant and Implicit Grant flows are available but not recommended because they are less secure than the Authorization Code and Client Credentials flows.

Client Credentials Flow

The OIDC plugin makes authenticating using Client Credentials very straightforward. This flow should be used for server-side and secure machine-to-machine communication. The Client Credentials flow requires the authorizing party to store and send the application’s client_secret.

In this flow, a developer makes a request against the Service with the OIDC and Application Registration plugins applied. This request should contain the client_id and client_secret as a Basic Auth authentication header:

Authorization: Basic client_id:client_secret

The client_id:client_secret should be base64-encoded.

The following sequence diagram illustrates the Client Credentials flow through the OIDC and Application Registration plugins. Click on the image to expand its view.

Client Credentials Flow

Step Explanation
a Developer sends the Okta application’s client_id and client_secret to the Route. The OIDC plugin proxies this request to the Okta auth server’s endpoint.
b Okta reads the client_id and client_secret and generates an access token. The auth server is configured to insert a custom claim application_id, which is a key/value pair with the Okta application’s client_id.
c Okta returns the access token to Kong.
d The OIDC plugin reads the resulting access token and associates the request with the application via the application_id custom claim.
e If the resolved application has permission to consume the Service via its Portal Application Registration plugin, Kong forwards the request to the Upstream.

Authorization Code Flow

Due to limitations of the OIDC plugin, a single plugin instance cannot handle dynamic client_id's provisioned from multiple sources (applications). To circumvent this issue, the IdP Issuer URL is exposed to developers on the Dev Portal application show page when show_issuer is enabled in the Application Registration plugin. Developers can hit the Issuer URL directly to provision an access token. After getting the access token, requests can be made against the proxy.

  1. Set up the application to secure an access token against the IdP directly. For more information about implementing the Authorization Code flow with Okta, refer to the Okta developer guide.

  2. After the initial access token handshake has been completed, make subsequent requests to the Kong service using that access token as a bearer token. After the first successful request, the OIDC plugin will establish a session with the client so that the access token does not need to be continually passed with every request.

The following sequence diagram illustrates the Authorization Code flow through the OIDC and Application Registration plugins. Click on the image to expand its view.

Authorization Code Flow

Step Explanation
a A developer copies the target Service’s issuer_id, which can be exposed in the Dev Portal application view Service Details page. Developers can configure their application to make a request to this endpoint to authenticate the user and retrieve an access token.
b Okta redirects the user to a login page.
c The user inputs their Single Sign-On (SSO) information.
d The user submits the SSO form that contains their Okta username and password.
e Upon a successful login, the application is given an access token to make against calls for all subsequent requests.
f The user makes a request to the protected Service and Route.
g The OIDC plugin takes the access token and runs introspection, consulting the Okta authorization server if necessary. After the access token has been verified, the plugin matches the custom claim to find the associated application Consumer via its custom_id.
h The request is passed to the Application Registration plugin, which checks to make sure the Consumer has the appropriate ACL (Access Control List) permissions.
i The request is proxied to the Upstream.

Implicit Grant Flow

The Implicit Grant flow is not recommended if the Authorization Code flow is possible.

  1. Set up the application to secure an access token against the IdP directly. For more information about implementing the Implicit Grant flow with Okta, refer to the Okta developer guide.

  2. After the access token handshake has been completed, make subsequent requests to the Kong service using that access token as a bearer token. After the first successful request, the OIDC plugin will establish a session with the client so that the access token does not need to be passed continuously.

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