Tools to Trace OIDC Flows (OAuth flows)

Tools to Trace OIDC Artifacts and Flows

1. Browser Developer Tools:

   • The Network tab in your browser's developer tools (DevTools) is one of the easiest ways to trace HTTP requests, including those involved in OIDC authentication.
   • You can see:
     • The request to Okta's authorization endpoint (for the /authorize request).
     • The redirect back to your app with the code (authorization code).
     • The request to Okta's token endpoint (to exchange the authorization code for an access token and ID token).
     • The response that contains the tokens (JWTs).
   • If you look at the network activity during login, you'll see the various redirects, HTTP requests, and responses. This is helpful for understanding the different stages of the OIDC flow.

2. Postman:

   • Postman can be very useful for manually simulating the OIDC flow. You can configure requests for:
     • The /authorize endpoint to initiate the login flow.
     • The /token endpoint to exchange the authorization code for tokens.
   • This allows you to interact with Okta directly and inspect the responses to understand better how the tokens are issued and what information is exchanged.

3. Okta Developer Console:

   • The Okta Admin Dashboard has logs and monitoring features that allow you to trace authentication events. You can look at the logs to find information on login attempts, the OIDC flow, tokens issued, etc.
   • Go to Security > View Logs to see a detailed history of user activities, authentication events, and issued tokens.

4. JWT.io Debugger:

   • If you're dealing with JWTs (which is very common in OIDC flows), you can use the JWT.io Debugger to decode and inspect JWT tokens. Just paste the JWT token from Okta (like the id_token or access_token) into the debugger to see the claims and payload in a human-readable format.
   • The debugger also lets you verify the token’s signature if you provide the public key from Okta.

5. OIDC Debugger Tools:

   • There are some specialized online tools built specifically for debugging OIDC flows, such as:
     • OIDC Debugger – This site lets you simulate OIDC requests and view the results. It also shows what HTTP requests are being made under the hood.
     • Auth0 OIDC Debugger – Similar to the above, Auth0 provides a debugger for testing and tracing OIDC authentication flows.

6. Fiddler or Wireshark:

   • If you want to trace HTTP traffic more deeply, you can use tools like Fiddler (a web debugging proxy) or Wireshark (a network protocol analyzer).
     • Fiddler will capture all HTTP/HTTPS traffic and allow you to inspect the request/response headers, including things like Authorization headers, tokens, and more.
     • Wireshark gives you a lower-level network packet capture, but it’s more complex and may require decryption if you're using HTTPS.

7. Okta SDKs and Libraries:

   • If you're using Okta's SDKs (for example, @okta/okta-auth-js for client-side authentication), you can enable debug logging to print detailed information about the authentication process. This often includes the exact HTTP requests and responses, which can be very helpful for tracing.
   • Look into the documentation for your SDK to enable debug mode (e.g., debug: true).

8. OAuth2 Proxy or Reverse Proxy:

   • You can also use a reverse proxy like OAuth2 Proxy to sit between your application and Okta. OAuth2 Proxy can help you inspect the headers and parameters being passed in both directions, especially for token exchanges.
   • It also logs the OIDC process, which can give you valuable insights into how Okta is interacting with your app.

Understanding the OIDC Flow

1. Authorization Request:

   • Your Express.js app sends the user to Okta's /authorize endpoint.
   • Parameters like client_id, redirect_uri, response_type, and scope (e.g., openid profile email) are included in the URL.

2. Authorization Response:

   • After the user logs in, Okta redirects back to your app’s redirect_uri with an authorization_code.

3. Token Request:

   • Your Express app exchanges the authorization_code for tokens (access_token, id_token, and optionally refresh_token) by sending a request to Okta’s /token endpoint with the client_id, client_secret, and the authorization_code.

4. Token Response:

   • Okta responds with the tokens in JSON format.
   • The id_token is a JWT containing claims about the user (like their username and email).
   • The access_token is used to make authorized API requests.

What to Look for in the Flow

• Authorization Code Flow: If you're using the authorization code flow, inspect the URL after redirection from Okta. You should see the authorization code (code) as a query parameter.
• Tokens: Check the token response to ensure it contains the id_token, access_token, and refresh_token (if applicable).
• JWT Structure: If you're receiving JWTs, use tools like JWT.io to decode and inspect the claims inside (sub, email, exp, etc.).
• Scopes: Ensure the requested scopes match what your app requires (e.g., openid, profile, email).

By using these tools and techniques, to get clearer understanding of the artifacts exchanged in the OIDC flow and how they work under the hood. See the flow of protocol under the hood for increasing knowledge and also able to troubleshoot if required.