Integrating Jama Connect with OAuth 2.0 as the identity provider (IDP)

Author: Eric Houghland 

Date: November 7, 2024

Audience: Jama Connect Administrators and Engineers

Products Applicable: Jama Connect®

Use Case

Integrating Jama Connect with OAuth 2.0 as the identity provider (IDP)

Best Practice

Enable an integration that supports sending requests on behalf of specific users rather than on behalf of the integration user. This new method eliminates the need for users to first log into Jama Connect and populate credentials (better for integrations to tools where users consuming it aren't using Jama Connect).

Implementation

This guide provides instructions on setting up OAuth 2.0 for an Identity Provider (IdP) like Okta for Jama Connect and REST API integrations. 

1. Setting Up the Application in Okta

• Go to Applications in the side navigation.
• Select Applications in the submenu.
• Click the Create App Integration button.
• Sign-in method: Select OIDC - OpenID Connect.
• Application type: Select Web Application.

• App integration name: Give your application a name.
• Enable options:
  • Refresh Token
  • Allow wildcard * in sign-in URL redirect

• Callback URL:
  • This is needed later. Use: https://oauth.pstmn.io/v1/callback
• Assignments: Select Skip group assignment for now and select Save.

2. Accessing Application Details

• Once the application is created, open it.

• General tab: Save the following values for Postman:
  • Client ID
  • Client Secret

• Assignments tab:
  • Add a test user. Important: The test user's email and username must match what's in Jama Connect.

3. Setting Up API Authorization Server

• Go to Security -> API under the left-hand navigation.
• Select Add Authorization Server.
• Give your server a name and Audience (supply a placeholder value like "Example 2", it will be updated later).

• Select your newly created Authorization Server from the API list.
• Go to Access Policies and add a new access policy.
• Add a new rule for the created policy:
  • Select Client acting on behalf of a user:
    • Authorization code
    • Implicit (hybrid)
    • Resource Owner Password

4. Configuring Issuer and Metadata URL

• Go back to the API Navigation under Security on the left-hand side.
• Go to your authorization server.
• Settings tab: Select Edit.
• Change the Issuer to the Okta URL.

* Don't forget to save the metadata redirect

• On the same page, select the Metadata URL link and save the values for:
  • issuer (Issuer URL)
  • authorization endpoint (Auth URL)
  • token endpoint (Access Token URL)

5. Setup on Jama Connect

• Go to the Jama System Administration page and select the System Properties tab.
• Select the API Authentication Properties tab.
• Select the box to enable IdP-based OAuth 2.0 Authorization Code API Authentication.
• Issuer URL: Add the value copied from the Metadata URL link above.
• Audience:
  • You can either generate a new value or use the one you created earlier.

Exchange Client Credentials

The goal is to exchange OAuth credentials for an access token through an IDP with Okta.

Postman

Setup OAuth 2.0 Authorization configuration

Use OAuth 2.0 as the Authorization method for the request and select the generated token.

• On the Authorization tab:
  • Type = OAuth 2.0
  • Token = give it a name.
  • Grant Type = Authorization Code
  • Check Authorize using a browser
• Add values for:
  • Auth URL = Metadata URL link = "authorization_endpoint":
  • Access Token URL = Metadata URL link = "token_endpoint":
  • Client ID = saved earlier
  • Client Secret = saved earlier
  • Scope = openid
  • State = state

Create a new request on Postman to test the newly generated token:

The response body of the GET request should look something like this, but with your info:

You can verify OAuth 2.0 requests using Connect Log Viewer (login as the system admin and go to Logging > Log Viewer).

Repeat when the access token expires.

Note: The Jama Connect OAuth service currently doesn't support refresh tokens. When you exchange client credentials for an access token, you must observe the expiration time. The duration for which your access token is valid might differ between Jama Connect servers.

Additional Resources

• Jama Connect v9.17 - Cloud Release Notes

Please feel free to leave feedback in the comments below.