--- title: Reviewing an OAuth request and various OAuth settings description: To troubleshoot OAuth requests, inspect the parameters provided by the client in different stages of an OAuth transaction, and then compare the parameter values against the corresponding settings defined in the PingFederate administrative console. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_review_oauth_request_various_oauth_settings canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_review_oauth_request_various_oauth_settings.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: May 31, 2024 section_ids: about-this-task: About this task steps: Steps result: Result: result-2: Result: result-3: Result: result-4: Result: result-5: Result: result-6: Result: result-7: Result: result-8: Result: related-links: Related links --- # Reviewing an OAuth request and various OAuth settings To troubleshoot OAuth requests, inspect the parameters provided by the client in different stages of an OAuth transaction, and then compare the parameter values against the corresponding settings defined in the PingFederate administrative console. ## About this task A typical OAuth request looks like the following with the parameters that are submitted by a client. These are what you track as you go through the configuration during a troubleshooting task. Your requests could look very different depending on the specifics of your authorization server, resource server, and clients. ``` ?client_id=client&response_type=code&redirect_uri=uri&scope=scope1 scope2 ``` In this example request, the client is providing 4 parameters: * client\_id * response\_type * redirect\_uri * scope | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | | There are other optional parameters that can be included in the request but are at this time not of interest to you in troubleshooting a typical request. | ## Steps 1. Review OAuth request in the server log. PingFederate logs requests and responses to the server log. The details vary based on the log level set in `/pingfederate/server/default/conf/log4j2.xml` file. The following example shows a client making an Authorization Code grant type, as indicated by the `response_type` parameter of `code`. ``` 2015-11-29 22:11:35,795 tid:aUBgyTMjPfuSFp5BYtsK6Cb2McM DEBUG [org.sourceid.websso.servlet.ProtocolControllerServlet] ---REQUEST (GET)/as/authorization.oauth2 from 127.0.0.1: ---PARAMETERS--- scope: list_users response_type: code client_id: pa_web_session_9 ``` 2. Check if the client is valid. 1. Go to **Applications > OAuth > Clients** to open the **Clients** window. 2. Look for the client by its **Client ID**. ### Result: If the client is not found, PingFederate denies the request, returns a 400 error to the client, and logs an `Unknown or invalid client_id` message to the server log, similar to the following code. ``` 2015-11-29 22:11:35,812 tid:aUBgyTMjPfuSFp5BYtsK6Cb2McM DEBUG [org.sourceid.oauth20.handlers.HandleAuthorizationRequest] Normal exception being handled during OAuth request processing: org.sourceid.oauth20.handlers.AuthorizationRequestException: Unknown or invalid client_id ``` 3. Check if the `redirect_uri` parameter value is valid for the client. 1. Go to **Applications > OAuth > Clients** to open the **Clients** window. 2. Go to the **Clients** window. 3. Select the applicable client. 4. Compare the `redirect_uri` parameter value against the values defined in the **Redirect URIs** field. ### Result: If the request comes without a `redirect_uri` parameter and the **Redirect URIs** field contains multiple entries, PingFederate denies the request, returns a 400 error to the client, and logs an `Invalid redirect_uri` message to the server log, similar to the following code. ``` 2015-11-29 22:23:59,858 tid:aUBgyTMjPfuSFp5BYtsK6Cb2McM DEBUG [org.sourceid.oauth20.handlers.HandleAuthorizationRequest] Normal exception being handled during OAuth request processing: org.sourceid.oauth20.handlers.AuthorizationRequestException: Invalid redirect_uri ``` If the request comes with a `redirect_uri` parameter value that does not match any **Redirect URIs** values defined for the client, PingFederate denies the request, returns a 400 error to the client, and logs an `Invalid redirect_uri` message to the server log. 4. Check if the `response_type` parameter value is authorized for the client. 1. Go to **Applications > OAuth > Clients** to open the **Clients** window. 2. Select the applicable client. 3. In the **Allowed Grant Types** field, verify the `response_type` is selected. ### Result: If the `response_type` value is not one of the allowable grant types, PingFederate denies the request, returns a 403 error to the client, and logs an `unauthorized_client` message with an error description to the server log, similar to the following code. ``` 2015-11-29 22:25:51,212 tid:aUBgyTMjPfuSFp5BYtsK6Cb2McM DEBUG [org.sourceid.saml20.bindings.LoggingInterceptor] Transported Response. OutMessageContext: OutMessageContext entityId: pa_web_session_1 (null) virtualServerId: null Binding: oauth:authz params: {error=unauthorized_client, error_description=implicit grant not allowed for this client} Endpoint: https://servapp.ext.den-ping.com/pa/oidc/cb#error_description=implicit+grant+not+allowed+for+this+client&error=unauthorized_client SignaturePolicy: BINDING_DEFAULT ``` 5. Check if the scopes requested with the `scope` parameter are defined for the authorization server. 1. Go to **System > OAuth Settings > Authorization Server Settings**. 2. In the **Authorization Server Settings** window, compare the scopes requested against the values defined in the **Scope Value** or the **Scope Group Value** fields. ### Result: If the scopes requested are not defined, PingFederate denies the request, returns a 403 error to the client, and logs an `invalid_scope` message with an error description to the server log, similar to the following code. ``` 2015-11-29 22:24:52,588 tid:aUBgyTMjPfuSFp5BYtsK6Cb2McM DEBUG [org.sourceid.saml20.bindings.LoggingInterceptor] Transported Response. OutMessageContext: OutMessageContext entityId: pa_web_session_1 (null) virtualServerId: null Binding: oauth:authz params: {error=invalid_scope, error_description=The requested scope(s) must be blank or a subset of the provided scopes.} Endpoint: https://servapp.ext.den-ping.com/pa/oidc/cb?error_description=The+requested+scope%28s%29+must+be+blank+or+a+subset+of+the+provided+scopes.&error=invalid_scope#. SignaturePolicy: BINDING_DEFAULT ``` 6. Check if the scopes requested are valid for the client. 1. Go to **Applications > OAuth > Clients** to open the **Clients** window. 2. Select the applicable client. 3. If the client is limited to specific scopes, as indicated by the selection of the **Restrict Scopes** checkbox, verify the scopes requested are valid for the client. ### Result: If the scopes requested are not valid for the client, PingFederate denies the request, returns a 403 error to the client, and logs an `invalid_scope` message with an error description to the server log. 7. Review the authentication process. Suppose this OAuth request uses an identity provider (IdP) adapter for authentication. Check the IdP adapter mapping and the runtime selection made by the user. 1. Go to **Authentication > OAuth > IdP Adapter Grant Mapping**. 2. Verify an entry exists for the IdP adapter involved. ### Result: If more than one option is available, authentication policies can be used to select an authentication source. If no authentication policy is defined or applicable, the user is prompted with a list of all available authentication sources. The user can also save the preferred authentication source for later in the form of a `pfidpaid` cookie. If a selection was made and the authentication source is not defined for OAuth, an error is returned to the user. 8. Upon successful authentication, PingFederate presents to the user an authorization consent page or a redirection to a trusted web application that is responsible to prompt the user for authorization unless a bypass option is configured. Review the authorization approval settings. 1. Go to **System > OAuth Settings > Authorization Server Settings**. 2. Review the **Reuse Existing Persistent Access Grants for Grant Types** setting. ### Result: If the grant type is selected, the authorization consent page is bypassed for the same client, the same user and same, or lesser, scope. 3. Review the **Consent User Interface** setting. If PingFederate is configured to use an external consent user interface, verify that the associated settings are correctly configured and the web application is fulfilling its responsibilities. 4. Go to **Applications > OAuth > Clients** to open the **Clients** window. 5. Go to the **Clients** window. 6. Select the applicable client. 7. Review the **Bypass Authorization Approval** setting. ### Result: If the **Bypass Authorization Approval** checkbox is selected, the authorization consent page is bypassed as well. 9. Verify a mapping is configured. When authorization is obtained, PingFederate maps attribute values from the authentication source into the persistent grants, the `USER_KEY`, `USER_NAME`, and extended attributes defined in the **Authorization Server Settings** window. This is the first stage of the two-stage OAuth attribute mapping process. In this example, because the user authenticates through an IdP adapter, check the IdP adapter mapping. 1. Go to **Authentication > OAuth > IdP Adapter Grant Mapping**. 2. Verify an entry exists for the IdP adapter involved and review its configuration. 10. Review the request and the settings related to access token management. Finally, PingFederate selects the applicable access token management (ATM) instance and fulfill the access token by mapping values from the persistent grants, the authentication source, or both. This is the second stage of the two-stage OAuth attribute mapping process. At runtime, the PingFederate OAuth authorization server uses the following rules to determine which ATM instances to use: 11. PingFederate limits the eligible ATM instances to those that are available in the context of the request. For most requests, these are instances that have an attribute mapping defined in the **Access Token Mapping** window. For OAuth Assertion Grant requests, it is the set of instances for which a mapping is defined in the IdP connection. If configured, the ACL can also limit which ATM instances are eligible. 12. If the request comes with an `access_token_manager_id`, `aud`, or `resource` parameter, PingFederate uses the information to determine the applicable ATM instance. 13. If the request does not come with either parameter, for OAuth clients supporting the OpenID Connect protocol by including the `openid` scope value, PingFederate uses the ATM instance specified by the OpenID Connect policy associated with the client. For resource server clients, you can optionally configure PingFederate to use any eligible ATM instances for the purpose of token validation. 14. If the request comes with neither of the two parameters nor the `openid` scope, PingFederate uses the default ATM instance of the client if configured, or the default ATM instance defined for the installation if eligible. For token validation requests, if resource server clients do not provide either the `access_token_manager_id`, `aud`, or `resource` parameter in their requests and the resource server clients have not been configured to validate against any eligible ATM instances, the same logic applies. 1. Determine if the OAuth request is sent to the `/as/authorization.oauth2` authorization endpoint or the `/as/token.oauth2` token endpoint with an `access_token_manager_id`, `aud`, or `resource` parameter. 2. Go to **Applications > OAuth > Clients** to open the **Clients** window. 3. Select the applicable client. 4. Verify if a default access token is selected from the **Default Access Token Manager** list. 5. Go to **Applications > OAuth > Access Token Mapping**. 6. Review the attribute mapping configuration for the authentication source, if such mapping exists, or the `Default` mapping. ## Related links * [Configuring OAuth use cases](pf_config_oauth_use_cases.html)