okta

This add-on is operated by Okta, Inc.

provision an okta org and set environment variables for access

okta

Last updated 26 September 2019

The okta add-on is currently in beta.

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:

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:

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:

Feedback

Log in to submit feedback.