Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
2.6.x
  • Home icon
  • Kong Gateway
  • Developer Portal
  • Administration
  • Application Registration
  • Set Up External Portal Application Authentication with Okta and OIDC
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Define an authorization server and create a custom claim in Okta
  • Register an application in Okta
  • Associate the identity provider application with your Kong application
You are browsing documentation for an outdated version. See the latest documentation here.

Set Up External Portal Application Authentication with Okta and OIDC

These instructions help you set up Okta as your third-party identity provider for use with the Kong OIDC and Portal Application Registration plugins.

Define an authorization server and create a custom claim in Okta

Follow these steps to set up an authorization server in Okta for all authorization types.

  1. Sign in to the Developer Okta site.
  2. Click API > Authorization Servers.

    Okta Authorization Server

    Notice that you already have an authorization server set up named default. This example uses the default auth server. You can also create as many custom authorization servers as necessary to fulfill your requirements. For more information, refer to the Okta developer documentation.

  3. Click default to view the details for the default auth server. Take note of the Issuer URL, which you will use to associate Kong with your authorization server.

    Okta Issuer URL

  4. Click the Claims tab.

    Okta Issuer URL

  5. Click Add Claim. Add a custom claim called application_id that will attach any successfully authenticated application’s id to the access token.
    1. Enter application_id in the Name field.
    2. Ensure the Include in token type selection is Access Token.
    3. Enter app.clientId in the Value field.
    4. Click Create.

    Okta Claim

    Now that you have created a custom claim, you can associate the client_id with a Service via the Application Registration plugin. Start by creating a Service in Kong Manager.

  6. Create a Service and a Route and instantiate an OIDC plugin on that Service. You can allow most options to use their defaults.

    1. In the Config.Issuer field, enter the Issuer URL of the Authorization server from your identity provider.

      OIDC with Okta Issuer URL

    2. In the Config.Consumer Claim field, enter your <application_id>.

    Tip: Because Okta’s discovery document does not include all supported auth types by default, ensure the config.verify_parameters option is disabled.

    Clear Config Verify Parameters for OIDC with Okta

    The core configuration should be:

    {
      "issuer": "<auth_server_issuer_url>",
      "verify_credentials": false,
      "consumer_claim": "<application_id>",
    }
    
    
  7. Configure a Portal Application Registration plugin on the Service as well. See Application Registration.

Register an application in Okta

Follow these steps to register an application in Okta and associate the Okta application with an application in the Kong Dev Portal.

  1. Sign in to the Developer Okta site.
  2. Click Applications > + Add Application.
  3. Depending on which authentication flow you want to implement, the setup of your Okta application will vary:

    • Client Credentials: Select Machine-to-Machine when prompted for an application type.

    Okta Create New Application

    You will need your client_id and client_secret later on when you authenticate with the proxy.

    Okta Client Credentials

    • Implicit Grant: Select Single-Page App, Native, or Web when prompted for an application type. Make sure Implicit is selected for Allowed grant types. Enter the Login redirect URIs, Logout redirect URIs, and Initiate login URI fields with the correct values, depending on your application’s routing. The Implicit Grant flow is not recommended if the Authorization Code flow is possible.

    • Authorization Code: Select Single-Page App, Native, or Web when prompted for an application type. Make sure Authorization Code is selected for Allowed grant types. Enter the Login redirect URIs, Logout redirect URIs, and Initiate login URI fields with the correct values, depending on your application’s routing.

Associate the identity provider application with your Kong application

Now that the application has been configured in Okta, you need to associate the Okta application with the corresponding application in Kong’s Dev Portal.

Note: Each developer should have their own application in both Okta and Kong. Each Okta application has its own `client_id` that maps to its respective application in Kong. Essentially, this maps identity provider applications to portal applications.

This example assumes Client Credentials is the chosen OAuth flow.

  1. In the Kong Dev Portal, create an account if you haven’t already.
  2. After you’ve logged in, click My Apps.
  3. On the Applications page, click + New Application.
  4. Complete the Name and Description fields. Paste the client_id of your corresponding Okta (or other identity provider) application into the Reference Id field.

    Kong Create Application with Reference Id

Now that the application has been created, developers can authenticate with the endpoint using the supported and recommended third-party OAuth flows.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • 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