Chapter 4. Securing Your APIs

Authenticating with Okta

Okta is a powerful and popular identity management solution used by thousands of businesses across the globe. Many developers wish to integrate Okta into their application authentication infrastructure, and DreamFactory offers a straightforward solution for doing so. In this tutorial we'll guide you through the configuration process.

Configuring OKTA

Begin by creating an Okta account at if you haven't already done so. Once logged-in, open the Admin section:

Next, you'll add a new application:

Be sure to select SAML 2.0:

Next, we'll configure the application:

Open Setup instructions, making sure you don't close the tab containing these instructions as we'll return to them later:

Configuring DreamFactory

Next, we'll configure DreamFactory to support the new OKTA application. Begin by signing into DreamFactory as an administrator, and then navigate to the Roles section and configure a role for the users who will sign in via Okta SSO. Here's an example of a role defining access to all APIs (not typical but nonetheless illustrative):

With the role defined, navigate to the Apps tab and create a new API key which will be associated with this role:

Creating the SAML 2.0 Service

With the role and API key defined, it's time to create the SAML 2.0 service that will connect your Okta application to DreamFactory. Navigate to Services > Create, choose SSO, and finally SAML 2.0:

Begin by configuring the Info tab:

Next, configure the Config tab, filling in the fields with the information found in Okta's Setup instructions page:

Save these changes, and navigate to the API Docs tab. Here you can see new Okta endpoints:

Adding Okta Users to the DreamFactory Application

With your Okta application created and DreamFactory configured, return to Okta, and in the Admin app navigate to the Application page:

Select our DreamFactory application in the list:

Assign this application to the People and Groups who will use it:

Go to the General tab and click the Edit button: =

Change Single sign on URL and Audience URI (SP Entity ID) to the values presented in DreamFactory's Okta API documentation, and then save the changes:

Application configuration

We're almost done! Now we can sign in via Okta by going to the service's /sso endpoint. In our example application we assign Sign in with OKTA button to this endpoint. Clicking this button, DreamFactory can return the X-DreamFactory-Session-Token, which we have to use for comunication with DreamFactory:

But how does DreamFactory know where send the token? We have to configure our Relay State for this purpose. Open the Services tab and select your OKTA SSO service. Navigate to the Config tab and update the Relay State field URL which will contain the token returned from DreamFactory. Our example site hosted on will pass token to the /hello.html page:

DreamFactory will replace the _token_ with a real X-DreamFactory-Session-Token. You might then use JavaScript to persist this token to local storage, or use server-side languages to do the same using cookies:

Now we can communicate with DreamFactory by including X-DreamFactory-Session-Token and X-DreamFactory-API-Key in the request header:

Don't forget add your application to the CORS interface via Config > CORS. Our example CORS configuration allows any requests to all DreamFactory endpoints with any headers. You can configure it to be more secure: