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.
-
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 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
-
Check if the client is valid.
- Go to the OAuth Server > Client Management screen.
- Look for the client by its ID.
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: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 the OAuth Server > Client Management screen.
- Select the applicable client.
- Compare the redirect_uri parameter value against the values defined in the Redirect URIs field.
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: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. -
Check if the response_type parameter value is authorized for
the client.
- Go to the OAuth Server > Client Management screen.
- Select the applicable client.
-
Verify the
response_type
is selected in the Allowed Grant Types field.
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: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 (via the scope parameter) are
defined for the authorization server.
- Go to the OAuth Server > Authorization Server Settings screen.
- Compare the scopes requested against the values defined in the Scope Value or the Scope Group Value fields.
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: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 the OAuth Server > Client Management screen.
- 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.
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 IdP adapter for authentication. Check the IdP adapter mapping and the runtime selection made by the user.
- Go to the OAuth Server > IdP Adapter Mapping screen.
- Verify an entry exists for the IdP adapter involved.
If more than one option is available, authentication policies may 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 also has the option to save the preferred authentication source for later (in the form of a
pfidpaid
cookie).If 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 the OAuth Server > Authorization Server Settings screen.
-
Review the Reuse Existing Persistent Access Grants for Grant
Types setting.
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 the OAuth Server > Client Management screen.
- Select the applicable client.
-
Review the Bypass Authorization Approval
setting.
If the Bypass Authorization Approval check box is selected, the authorization consent page is bypassed as well.
-
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 screen; this is the first
stage of the two-stage OAuth attribute mapping process. Verify a mapping is
configured.
In this example, because the user authenticates via an IdP adapter, check the IdP adapter mapping.
- Go to the OAuth Server > IdP Adapter Mappings screen.
- Verify an entry exists for the IdP adapter involved and review its configuration.
-
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 AS uses the following rules to determine which ATM instances it should use:
- Limit 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 screen. For OAuth Assertion Grant requests, it is the set of instances for which a mapping is defined in the IdP connection. Furthermore, the ACL (if configured) can also limits which ATM instances are eligible.
- If the request comes with an access_token_manager_id or aud 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 RS clients, you may 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 RS clients do not provide either the access_token_manager_id or aud parameter in their requests and the RS clients have not been configured to validate against any eligible ATM instances, the same logic applies.
Review the request and the settings related to access token management.
- 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 or aud parameter.
- Go to the OAuth Server > Client Management screen.
- Select the applicable client.
- Verify if a default access token is selected from the Default Access Token Manager list.
- Go to the OAuth Server > Access Token Mapping screen.
-
Review the attribute mapping configuration for the authentication
source (if such mapping exists) or the
Default
mapping.