okta
Last updated September 26, 2019
Table of Contents
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
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