CMiC API and OAuth 2.0 Integration - OAuth 2.0 - Troubleshooting

Overview

This article describes OAuth security checks and troubleshooting. There are two steps in the workflow to get a valid response from a CMiC API. The first is the OAuth security checks and the second is the CMiC security checks.

Troubleshooting

Debugging

Enable the OAuth flow debugging by requesting DBAs to enable the dynamic logging:

Copy 
<logger name='cmic.oauth2.filter' level='FINE'/>

Requirements

  1. Server logs are required since the root error will be present, including the authorization bearer value used during processing.

  2. If available, the error reference is a part of the error message sent back to the client.

  3. Please provide the error response, which can include the error message/error reference that is a link to the error in logs, and the time which the error occurred.

Error Responses

500 - Failed to process request properly.

The reason could be one of the following:

  1. Application is not registered

  2. Failed to load JSON web key set

  3. Another unexpected processing error

401 - Unauthorized Access

The reason could be one of the following:

  1. No Authorization Bearer value

  2. Missing Authorization header

  3. Missing required claim

  4. Client validation failed (ip check)

  5. Token expired

  6. Unable to validate signature

Check to Perform

Depending on the error, one or more of the following checks could be required:

  1. Did the request have the Authorization header with the Bearer <token> value?

  2. The application is registered in the CMiC API Security.

    1. Application ID and issuer values must be present in the token.

  3. The token has the right set of claims.

    1. You may need to match the key claims with the application registered.

    2. Check the Token Validation section for more details.

  4. If the IP check failed,

    1. Was the ipaddr claim present?

    2. Was the ipaddr claim value not found in the request IP (x-forwarded-for)?

    3. The problem can be introduced because of the VPN, where the token has the real client IP, but the request has the VPN IP, and those would not match. The client's IT should verify why there’s a difference.

    4. It is not suggested to disable IP check, especially in production. There is ability to disable it by setting the cmic.oauth2.ipcheck.enabled property to "false" in cmicapp.properties.

Token Validation

The following are two sites where you can take a JWT token and it will convert to a readable set of claims present.

  1. https://jwt.io/

  2. https://jwt.ms/

The token to use is what is in the server logs noted with the error (it will start with "ey").

Azure Token

Version 1

Token must have claims:

  • appid

  • iss

  • ipaddr (not present for client credentials flow)

  • One of the following: cmicuser, email, or upn

Version 2

Token must have claims:

  • aud

  • iss

  • ipaddr (not present for client credentials flow)

  • One of the following: cmicuser, email, or upn

Verify Server is Configured Properly for OAuth

Test an API call from the browser (e.g. https://<your server>/<env>/cmic-field-rest-api/jersey/v1/login) and see if any of the following occurs:

  1. Does it prompt for username and password?

    If yes, then the setup is incorrect. This means it's protected by Basic Authentication and DBAs need to review the setup.

  2. Does it redirect to a sign-in page?

    If yes, then setup is incorrect. This means it's protected by Access Manager and DBAs need to review the setup.

  3. If you're still unsure, verify that the API request is hitting the API server by checking the access.log. If it is not, there could be a network routing issue that your IT should review.