PingFederate Server

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 <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

  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 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.

  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 check box 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:

    1. 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.

    2. If the request comes with an access_token_manager_id or aud parameter, PingFederate uses the information to determine the applicable ATM instance.

    3. 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.

    4. 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 or aud 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 or aud 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.