JWT Test Tokens¶

Generate JWT tokens to test your deployed APIs through Azure API Management.

On this page

📋 Overview
🎯 Why You Need This
🏛️ Choosing Corporate vs External
🔧 Prerequisites
🚀 Instructions
📝 Example Parameters (External Tokens Only)
✅ Verify It Worked
🔍 Troubleshooting
🚀 Next Steps

📋 Overview¶

Aspect	Details
Goal	Generate a valid JWT token for testing secured API endpoints
Prerequisites	Personal test tools repository, Okta access, Azure DevOps access
Time estimate	~10 minutes
Difficulty	Beginner

🎯 Why You Need This¶

When an API is deployed to Azure, API Management secures it by default. To test the deployed API with Postman, RestClient, or similar tools, you need an Authorization header with a valid JWT token.

Key concepts:

Scopes - Application-level permissions allowing the app to access API functionality
Corporate vs External - Forge uses dual identity providers: Entra ID (corporate) and Okta (external)
user-groups scope - Special scope for user-context access in Okta (external)
user_impersonation scope - Special scope for user-context access in Entra ID (corporate)

🏛️ Choosing Corporate vs External¶

Before generating a token, determine which identity provider and tool to use:

If you're testing as...	Identity Provider	Tool
Internal employee	Microsoft Entra ID	SAIF CLI (`saif token generate`)
External user (policyholder, provider, etc.)	Okta (External tenant)	Azure DevOps Pipeline

💡 Key Difference: Corporate tokens use Entra ID and are generated via the SAIF CLI. External tokens use Okta and are generated via an Azure DevOps pipeline.

🔧 Prerequisites¶

For Corporate (Entra ID) Tokens¶

✅ SAIF CLI installed (saif --version to verify)
✅ Know your application name (e.g., it-api-exp-brishe-test)

For External (Okta) Tokens¶

✅ Personal test tools repository created
✅ Access to Okta Apps
✅ Access to Azure DevOps pipelines
✅ Your project ID and scopes identified

🚀 Instructions¶

Option A: Generate Corporate Token (Entra ID) with SAIF CLI¶

Use this method for testing as an internal employee with Entra ID authentication.

1. Run the Token Generate Command¶

saif token generate --name <application-name>

Example:

# Generate token for brishe-test application
saif token generate --name it-api-exp-brishe-test

If you don't provide the --name parameter, the CLI will prompt you for the application name and show matching applications.

2. Select Your Application¶

The CLI will search for applications matching your name and display a list. Select the correct application from the menu.

Application naming pattern: {project-id}-{environment}

Examples:

it-api-exp-brishe-test
it-api-exp-brishe-qa
it-api-exp-brishe-uat

3. Copy the Token¶

The token will be displayed in the console. Copy the entire token output (no additional formatting).

4. Use in Testing Tools¶

Add the token as an Authorization header in your HTTP client:

Authorization: Bearer <token>

Example in Postman:

Header: Authorization
Value: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI...

Option B: Generate External Token (Okta) with Azure DevOps Pipeline¶

Use this method for testing as an external user (policyholder, provider, etc.) with Okta authentication.

1. Pipeline Prerequisite¶

You will need to add a secret variable on your pipeline to enter your password to be used in the token generation run. This is a one-time task after creating the pipeline that needs to be performed before the first run.

Click Edit
Click Variables
Click the plus button to add a variable
The variable name should be Password
Check the checkbox Keep this value secret
Check the checkbox Let users override this value when running the pipeline

This is the MS documentation for doing that

2. Finding the Auth Server ID¶

The Auth Server ID is printed in your API deployment pipeline outputs:

In Azure DevOps, navigate to your main API deployment pipeline
Find the most recent deployment run to the target environment (Test/QA/UAT)
Click the Deploy stage
Click the Deploy auth_ext_okta_client (terraform) job
Scroll to the bottom of the Terraform Apply step
Look for the Terraform Outputs section:

📄 Terraform Outputs:
====================
AuthServerAudience =
AuthServerId =
AuthServerUrl =
ClientId =
ClientSecret =
OpenIdConnectClientId =
OpenIdConnectClientSecret =
TenantOrigin =
====================

Copy the AuthServerId value

3. Generating a Token¶

In Azure DevOps, run the it-test-tools-[username]-gen-np-jwt pipeline in your personal test tools repository
In the parameters dialog pane that appears, enter the following (see table below for examples):
Project ID
Scopes (YAML array)
Auth Server ID
Okta Org: Select External
ExternalUsername (your external user email)
Click Variables
Click Password
Enter your AD password into the Value text box and click the Update button
Click run
Once the pipeline completes, navigate to the run summary
In the summary details, under the Related column, click the 1 published; 1 consumed link, this will navigate you to the artifacts page for the pipeline run
Expand the JWT list item
Click token.txt to download a text file containing the JWT
Copy/paste this into your testing tool as an Authorization request header, format: Authorization|Bearer [JWT]

📝 Example Parameters (External Tokens Only)¶

Pipeline Parameter - External Example¶

Parameter	Example
Project ID	it-api-sys-envsvc
Scopes	- read - write
Auth Server ID	aushpkatj89kOhK6Y1d7
Okta Org	External
ExternalUserName	wilbon@lincoln.com

✅ Verify It Worked¶

Confirm your token is valid:

Decode the token - Run saif token validate and paste the token when prompted, or use jwt.io to inspect the payload
Check scopes - Verify your requested scopes appear in the token
Test the API - Make a request to your API with the token

# Run without arguments and paste the token when prompted (recommended)
saif token validate

Success indicator: API returns data instead of 401 Unauthorized.

🔍 Troubleshooting¶

Word-wrapped tokens¶

Terminals interpret pasted newlines as command separators. If you paste a word-wrapped JWT directly on the command line (e.g. saif token validate <paste>), each wrapped line is treated as a separate command, causing errors like 'tOWM5...' is not recognized as a cmdlet.

Workarounds:

Use interactive mode (recommended): run saif token validate with no arguments, then paste when prompted.
Widen your terminal: make the terminal window wider than the token length before pasting so no wrapping occurs.

Store in a variable first (PowerShell):

$token = "eyJ0eXAiOiJKV1Qi..."
saif token validate $token

Token generation fails with authentication error¶

Cause: Password variable not configured or expired.

Solution: Reconfigure the Password variable in the pipeline (see Pipeline Prerequisite section).

Token rejected with "invalid_token" error¶

Cause: Token may be expired or scopes don't match API requirements.

Solution: Generate a new token and verify the scopes match what the API expects.

Cannot find Auth Server ID in Terraform Cloud¶

Cause: Okta workspace may not exist for this project.

Solution: Verify the Okta infrastructure is deployed. Check with your platform team if needed.

Token works for some users but not others¶

Cause: Using wrong tenant (Corp vs External) for the user type.

Solution:

Internal employees should use Corp tenant
External users (policyholders, providers) should use External tenant
Verify the user exists in the correct identity provider

Need to test with Entra ID token (corporate)¶

Cause: Using the wrong token generation method.

Solution: For corporate/Entra ID tokens, use the SAIF CLI:

saif token generate --name <application-name>

See Option A: Generate Corporate Token above for detailed instructions.

SAIF CLI not installed¶

Cause: SAIF CLI not installed.

Solution:

Install SAIF CLI: dotnet tool install -g SAIF.Platform.CLI
Verify SAIF CLI is working: saif --version

💡 Note: The SAIF CLI handles authentication on your behalf—no separate Azure login required.

🚀 Next Steps¶

Task	Guide
Set up a test tools repository	Test Tools Repository
Manage test users	External Test Users
Learn about security	Security Overview