Configuring OAuth 2.0 with Okta

Introduction

API Manager supports OAuth 2.0 authentication using Okta as the Identity Provider. This page shows how to set up Okta as an Identity Provider and obtain the OAuth Client ID and OAuth Client Secret needed for creating an OAuth 2.0 security profile. After OAuth 2.0 is configured in both Okta and the security profile, members of your Jitterbit org and invited developers will be able to use Okta authentication to access and consume your Harmony APIs.

Creating the Okta Client ID and Client Secret

1. Log in to your Okta Developer Console as an Admin. The Developer Console page displays as shown in the image below. Click on Applications in the toolbar at the top of the page. 
   
   
   
2. Click on the Add Application button.
   
   
   
3. Click on the Web application card and select the Next button at the bottom of the page.
   
   
   
4.  The Create New Application page displays as shown in the image below.
   
   
   • Name: Provide a name for the application.
   • Login redirect URIs: Add the three Harmony redirect URIs to provide access to Harmony APIs using a Harmony security profile. 
     • Remove "http://localhost:8080/authorization-code/callback" by selecting the delete icon  to the right of the URI.
     • To add a Harmony redirect URI, click the  button to open a new URI text box.
       • Paste one of the Harmony URIs for your region into the text box.
       • Repeat these steps for each Harmony redirect URI for your Harmony region. See Finding My Region.
         • NA region:
           • Copy these: 
             • https://apps.na-east.jitterbit.com/api-manager/oauthredirect/authcode
             • https://apps.na-east.jitterbit.com/api-manager/swagger-ui/oauthredirect
           • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Okta OAuth 2.0 authentication:

             • https://{org base URL}/_oauth/{oauth profile name}

               TIP:

               • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.net
               • You must enter "jitterbittrial" all in lower case.

         • EMEA region: 

           • Copy these:
             • https://apps.emea-west.jitterbit.com/api-manager/oauthredirect/authcode
             • https://apps.emea-west.jitterbit.com/api-manager/swagger-ui/oauthredirect 
           • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Okta 2.0 authentication: 

             • https://{org base URL}/_oauth/{oauth profile name}

               TIP:

               • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.eu
               • You must enter "jitterbittrial" all in lower case.
         • APAC region:
           
           • Copy these:
             • https://apps.apac-southeast.jitterbit.com/api-manager/oauthredirect/authcode
             • https://apps.apac-southeast.jitterbit.com/api-manager/swagger-ui/oauthredirect 
           • Construct the following URL substituting your Jitterbit org base URL and the name of the security profile you have created for Okta OAuth 2.0 authentication: 

             • https://{org base URL}/_oauth/{oauth profile name}


               TIP:

               • Your <org base URL> displays at the top of the My APIs page and is in the format of jitterbittrial#####.jitterbit.cc
               • You must enter "jitterbittrial" all in lower case.
       • The Login redirect URIs should appear similar to the image shown below once completed. 
         
         
5. Scroll down to the Grant type allowed section.
   
   
   • Click the Refresh Token checkbox. Authorization Code and Refresh Token should both be checked.
   • Select the Done button at the bottom of the page.
     
     
6. The General Settings page should display. Scroll down to the Client Credentials section as shown in the image below
   
   
   • Harmony sends the Okta Client ID and the Client Secret as part of the request for validation before allowing a user to consume the API. 
   • Leave this page open in a separate browser window. These two credentials will be required when Creating an Okta OAuth 2.0 Security Profile.
   • You can copy each credential to your clipboard by selecting the clipboard icon 

Creating an Okta OAuth 2.0 Security Profile

1. Log in to Harmony, select the API Manager application card and select Security Profiles from the dropdown menu.
2. On the Security Profiles page, click on the Create New Profile button in the upper right corner.
   
   
   
3. The View/Edit Security Profile page displays as shown below.
   
   
   • Name: Provide a name for the profile.
   • Environment: Select the environment the security profile will be assigned to from the dropdown list.
   • Description: Provide a description of the profile and assigned APIs.
     
     
4. Scroll down to Type.
   
   
   • Type: Select OAuth 2.0 in the dropdown list.
   • OAuth Provider: Select Okta in the dropdown list.
     
     
5. Scroll down to the OAuth Client ID.
   
   
   • OAuth Client ID: The Client ID is generated within the Okta Developer Console as described in Creating the Okta Client ID and Client Secret.
     • Return to the open browser window displaying the Okta Developer Console page. 
     • Copy the Client ID from Okta and paste into the OAuth Client ID field in the View/Edit Security Profile page as shown in the image above.
   • OAuth Client Secret: The Client Secret is generated within the Okta Developer Console as described in Creating the Okta Client ID and Client Secret.
     • Return to the open browser window displaying the Okta Developer Console page. 
     • Copy the Client Secret from Okta and paste into the OAuth Client Secret field in the View/Edit Security Profile page as shown in the image above.
       
       
6. Scroll down to the OAuth Authorization URL.
   
   
   • OAuth Authorization URL: Provide the custom URL required by Okta for authorization. This is a required field.
     • Construct the URL substituting your Okta Domain URL and your Okta Authorization Server ID: https://{yourOktaDomain}/oauth2/${authServerId}/v1/authorize 
   • OAuth Token URL: Provide the custom URL required by Okta for the token. This is a required field.
     • Construct the URL substituting your Okta Domain URL and your Okta Authorization Server ID: https://{yourOktaDomain}/oauth2/${authServerId}/v1/token
   • User Info URL: Provide the custom user information URL required by Okta for authentication. This is a required field.

     • Construct the URL substituting your Okta Domain URL and your Okta Authorization Server ID: https://{yourOktaDomain}/oauth2/${authServerId}/v1/userinfo

       TIP: The examples shown in the image above use "default" for the Okta Authorization Server ID. For instructions to set up your custom Okta Authorization Server, see these Okta documentation articles:

       • OAuth 2.0 and OpenID Connect Overview
       • Implementing OAuth for Okta
       • Authorization Servers
       • Create an Authorization Server

   • Test Client ID + Secret: Click the Test Client ID + Secret button to test communication between Harmony and Okta.
     
     

7. A popup window will display asking you to log in to Okta.
   
   • Enter your Email and Password.
     
     
8. A separate browser window displays a message in the upper left corner of the page indicating if the Client ID + Secret verified successfully. 
   
   
   • If the test fails:
     • Verify the Client ID and Client Secret are correct in the security profile. 
     • Verify the OAuth Authorization URL, OAuth Token URL, and User Info URL are correct in the security profile.
     • Verify the Login redirect URIs in the Okta web application are correct for your org base URL, security profile name, and region.
   • If the test is successful, close this page to return to the View/Edit Security Profile page.
     
     
9. Scroll down and complete the settings in the Authorized Domains, Logging, Trusted IP Ranges, and Rate Limit sections. See Security Profiles and Harmony API Security for additional information about these security settings.
   
10. Click on the Save button at the bottom of the page when all settings are complete.

Assign the Okta OAuth 2.0 Security Profile to an API

1. Log in to Harmony, select the API Manager application card and select My APIs from the dropdown menu.
2. Hover over the API card and select View/Edit.
   
   
   
3. Scroll down to the Security Profiles section and click on the Edit icon  .
   
   
   
4. The Assign Security Profile page displays as shown below.
   
   
   • Select the Okta OAuth 2.0 security profile from the dropdown list.
   • Click Assign Profile.
   • Click Save Changes.
   • Click Save Changes.
   • Click Save & Publish.
     
     
5. After selecting Save & Publish, the API is live and accessible. Select the Copy URL icon , and paste the link into your browser.
   
   
   
6. A popup window will display asking you to log in to Okta.
   
   • Enter your Email and Password. Sign into Okta.
     
     
7. If the authentication is successful, the expected payload will display in your browser.
   
   
   • If the API does not run successfully:
     • Verify the Client ID and Client Secret were copied correctly into the security profile.
     • Verify the OAuth Authorization URL, OAuth Token URL, and User Info URL are correct in the security profile.
     • Verify the Login redirect URIs in the Okta Application are correct for your org base URL, security profile name, and region.

Additional Okta OAuth 2.0 Resources

• Authorization Servers
• Create an Authorization Server