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
-
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
<pf_install>/pingfederate/server/default/conf/log4j2.xml
file. The following example shows a client making an Authorization Code grant type, as indicated by theresponse_type
parameter ofcode
.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
-
Check if the client is valid.
-
Go to Applications → OAuth → Clients to open the Clients window.
-
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
-
-
Check if the
redirect_uri
parameter value is valid for the client.-
Go to Applications → OAuth → Clients to open the Clients window.
-
Go to the Clients window.
-
Select the applicable client.
-
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 anInvalid 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 anInvalid redirect_uri
message to the server log.
-
-
Check if the
response_type
parameter value is authorized for the client.-
Go to Applications → OAuth → Clients to open the Clients window.
-
Select the applicable client.
-
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 anunauthorized_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
-
-
Check if the scopes requested with the
scope
parameter are defined for the authorization server.-
Go to System → OAuth Settings → Authorization Server Settings.
-
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
-
-
Check if the scopes requested are valid for the client.
-
Go to Applications → OAuth → Clients to open the Clients window.
-
Select the applicable client.
-
If the client is limited to specific scopes, as indicated by the selection of the Restrict Scopes check box, 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.
-
-
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.
-
Go to Authentication → OAuth → IdP Adapter Grant Mapping.
-
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.
-
-
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.
-
Go to System → OAuth Settings → Authorization Server Settings.
-
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.
-
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.
-
Go to Applications → OAuth → Clients to open the Clients window.
-
Go to the Clients window.
-
Select the applicable client.
-
Review the Bypass Authorization Approval setting.
Result:
If the Bypass Authorization Approval check box is selected, the authorization consent page is bypassed as well.
-
-
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.-
Go to Authentication → OAuth → IdP Adapter Grant Mapping.
-
Verify an entry exists for the IdP adapter involved and review its configuration.
-
-
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:
-
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.
-
If the request comes with an
access_token_manager_id
oraud
parameter, PingFederate uses the information to determine the applicable ATM instance. -
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. -
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 theaccess_token_manager_id
oraud
parameter in their requests and the resource server clients have not been configured to validate against any eligible ATM instances, the same logic applies.-
Determine if the OAuth request is sent to the
/as/authorization.oauth2
authorization endpoint or the/as/token.oauth2
token endpoint with anaccess_token_manager_id
oraud
parameter. -
Go to Applications → OAuth → Clients to open the Clients window.
-
Select the applicable client.
-
Verify if a default access token is selected from the Default Access Token Manager list.
-
Go to Applications → OAuth → Access Token Mapping.
-
Review the attribute mapping configuration for the authentication source, if such mapping exists, or the
Default
mapping.
-