Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Add-ons
  • All Add-ons
  • okta
okta

This add-on is operated by Okta, Inc.

provision an okta org and set environment variables for access

okta

Last updated September 26, 2019

Table of Contents

  • Provisioning the add-on
  • Using the API token
  • Complete example
  • Try it out
  • Troubleshooting
  • Removing the add-on
  • Support

OKTA is an add-on for provisioning an Okta Developer tenant. Okta is a cloud based Identity and Access Management (IAM) service complete with support for Okta’s own management APIs as well as hosted OAuth 2.0 and OpenID Connect services.

Adding Okta to an application provides authentication and authorization flows for your application so that you don’t have to reinvent that wheel. You have your choice of using standards, like OAuth 2.0 and OpenID Connect as well as Okta’s own Authentication API with advanced support for multifactor authentication (MFA) and self-service features like password reset and account unlock.

As we say at Okta,

Friends don’t let friends build auth

okta is accessible via an API and has supported client libraries for:

  • Java
  • .NET
  • Node.js
  • Angular
  • React
  • and others

Provisioning the add-on

okta can be attached to a Heroku application via the CLI:

The only plan available for the okta add-on is free.

$ heroku addons:create okta
Creating okta on ⬢ okta-addon-demo... free
Provisioning Okta Org
okta-rectangular-38080 is being created in the background. The app will restart when complete...
Use heroku addons:info okta-rectangular-38080 to check creation progress
Use heroku addons:docs okta to view documentation

Provisioning is asynchronous. It can take up to 5 minutes to complete, but is usually done inside 1 minute. The output from the addon:create command includes an additional command that shows you the status of the add-on provisioning. In the above example its: heroku addons:info okta-rectangular-38080

After you provision okta, a number of environment variables are set related to your newly provisioned Okta Organization. You can confirm this via the heroku config command:

$ heroku config
=== okta-addon-demo Config Vars
OKTA_CLIENT_ORGURL:              https://dev-965632.okta.com
OKTA_CLIENT_TOKEN:               00TAJ69duKEnlqwdwCqtgsOCRxMyPo846oasVr5t71
OKTA_OAUTH2_CLIENT_ID:           0oa1fc9bsVQG17Aw357
OKTA_OAUTH2_CLIENT_SECRET:       yGw21GAoGAdQ3SN-0d5MUr8pYGlSfY2Y
OKTA_OAUTH2_ISSUER:              https://dev-965632.okta.com/oauth2/default

Using the API token

After you install okta, your application should be configured to fully integrate with the add-on.

The OKTA_API_TOKEN can be used with the Okta Platform API. For instance, here’s a curl command to list all the users in your org:

$ curl \
https://dev-965632.okta.com/api/v1/users \
-H "Authorization: SSWS 00TAJ69duKEnlqwdwCqtgsOCRxMyPo846oasVr5t71"

Here’s the response (formatted):

[
  {
    "id": "00u11lc6ngKllC448357",
    "status": "ACTIVE",
    "created": "2019-08-01T15:09:38.000Z",
    "activated": null,
    "statusChanged": "2019-08-01T15:09:43.000Z",
    "lastLogin": null,
    "lastUpdated": "2019-08-01T15:09:43.000Z",
    "passwordChanged": "2019-08-01T15:09:43.000Z",
    "profile": {
      "firstName": "Super",
      "lastName": "Admin",
      "mobilePhone": null,
      "secondEmail": null,
      "login": "abc16e0c-deda-4210-840f-053e430712c5@heroku.okta.com",
      "email": "abc16e0c-deda-4210-840f-053e430712c5@heroku.okta.com"
    },
    "credentials": {
      "password": {},
      "emails": [
        {
          "value": "abc16e0c-deda-4210-840f-053e430712c5@heroku.okta.com",
          "status": "VERIFIED",
          "type": "PRIMARY"
        }
      ],
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://dev-965632.okta.com/api/v1/users/00u11lc6ngKllC448357"
      }
    }
  }
]

Complete example

Quick version

A sample application is available at GitHub.
Browse the source code or Deploy

This app will provision an Okta org as well as deploy this example application to Heroku.

Jump down to the Try it out section below to start using it.

Manual version

Follow these steps to use the Okta add-on in the context of a functioning application. It happens to be a Java application, but you don’t need to know Java to test it out.

You’ll need to think of a unique name for your app on heroku. Use this name in place of okta-addon-demo below.

$ git clone https://github.com/oktadeveloper/okta-spring-boot-oidc-sso-example.git okta-addon-demo
$ cd okta-addon-demo
$ heroku apps:create okta-addon-demo
$ heroku addons:create okta

At this point, you’ll get a response like this:

Creating okta on ⬢ okta-addon-demo... free
Provisioning Okta Org
okta-rectangular-38080 is being created in the background. The app will restart when complete...
Use heroku addons:info okta-rectangular-38080 to check creation progress
Use heroku addons:docs okta to view documentation

Since provisioning the Okta org is async, you can monitor its progress with this command:

You’ll see the assigned name for the addon in the output from Heroku. Use that value in the following command.

$ heroku addons:info okta-rectangular-38080

You’ll get a response like this:

=== okta-rectangular-38080
Attachments:  okta-addon-demo::OKTA
Installed at: Fri Sep 06 2019 16:17:06 GMT-0500 (Central Daylight Time)
Owning app:   okta-addon-demo
Plan:         okta:test
Price:        free
State:        created

Once the value for State is created, you can proceed. Check out the environment variables set by the addon:

$ heroku config

You’ll see output like this:

=== okta-addon-demo Config Vars
OKTA_CLIENT_ORGURL:        https://dev-666747.okta.com
OKTA_CLIENT_TOKEN:         00_aencWo1Q-Zwy0HrpiOs8zBuPsycy9zOT55PAjFA
OKTA_OAUTH2_CLIENT_ID:     0oa1ax6x8qS5NPdhs357
OKTA_OAUTH2_CLIENT_SECRET: EnhYtxD2QK9TlyGNOxnYoDIJ2JUkgbARwDvd2Xpt
OKTA_OAUTH2_ISSUER:        https://dev-666747.okta.com/oauth2/default

The next step is to deploy the app to Heroku.

$ git push heroku master

It will take some time to deploy, build and start up the app. After the git command completes, you can monitor the status of the app by looking at the logs:

$ heroku logs -t

At some point, you should see output like:

2019-09-06T21:24:49.579376+00:00 heroku[web.1]: State changed from starting to up

Try it out

The Okta Admin Console allows you to access quick start guides, view logs, and configure various aspects of okta.

You can access the dashboard via the CLI:

$ heroku addons:open okta
Opening okta for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select okta from the Add-ons menu.

Navigate to Users > People on the top level menu. Click Add Person and fill in the form. Choose Set by admin for the Password field and set a password. Uncheck User must change password on first login. Click Save.

Now, you can browse to the app. In my example, it would be: https://okta-addon-demo.herokuapp.com. You should immediately see the Okta hosted login screen.

Use the credentials for the user you created above to log in. The first time you authenticate, you’ll need to provide a security question and answer as well as choose a security image. You only do this once.

After you finish authenticating, you’ll end up at a landing page that shows your full name as well as the JWT value for the ID Token returned by Okta.

Troubleshooting

If you run into any issues in provisioning the Okta add-on or interacting with your provisioned Okta org, you can reach us at:

  • email: devrel@okta.com
  • web: devforum.okta.com
  • twitter: @oktadev

Removing the add-on

You can remove okta via the CLI:

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy okta
-----> Removing okta from sharp-mountain-4005... done, v20 (free)

If you run heroku config, you’ll see that the environment variables previously set are no longer available.

Support

You can reach us at:

  • email: devrel@okta.com
  • web: devforum.okta.com
  • twitter: @oktadev

Keep reading

  • All Add-ons

Feedback

Log in to submit feedback.

Ziggeo One-off Dyno Metrics

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences