Application authorization and authentication


Application types and authorization

PingOne supports several application types. When you make a POST /environments/{environmentId}/applications request to define a new application, you must specify the type property that best describes the application. PingOne supports the following application types:

  • Web application

    A browser-based application with a server-side component, such as ASP, CGI, JSP/Java, Node.js, or Ruby on Rails. Web applications typically have functions similar to desktop applications.

    • Supported authorization grant types:

      • authorization_code
      • refresh_token
    • Supported response types:

      • code
    • Supported token endpoint authentication method:

      • client_secret_basic (default)
      • client_secret_post
      • none
  • Native application

    An application that is installed and run directly on the local operating system, like Java, Objective-C, Swift, or React. Native applications are typically intended for mobile devices.

    • Supported authorization grant types:

      • authorization_code
      • implicit
      • refresh_token
    • Supported response types:

      • code
      • token
      • id_token
    • Supported token endpoint authentication method:

      • client_secret_basic
      • client_secret_post
      • none (default)
  • Single page application

    A browser-based application that runs on the front-end with no server-side component, such as Sencha Touch, AngularJS, and React. A single page application runs on the client side after it loads, so it cannot keep a client secret.

    • Supported authorization grant types:

      • implicit
    • Supported response types:

      • token
      • id_token
    • Supported token endpoint authentication method:

      • client_secret_basic
      • client_secret_post
      • none (default)
  • Non-interactive

    A web application that does not require user interaction through the web browser, like a command line interface, a service, or a daemon.

    • Supported authorization grant types:

      • client_credentials
    • Supported response types:

      • token
    • Supported token endpoint authentication method:

      • client_secret_basic (default)
      • client_secret_post

For more information, see Overview.

Authorization flow steps

An authorization grant gives applications the capability to authenticate users and access secure resources. The following steps describe the application authorization flow:

  1. The application initiates the authorization flow through a GET or POST request to the authorize endpoint.

  2. After the authorization service validates the request, it creates an authentication flow using the PingOne flow orchestration service. The flow orchestration service creates a new session and session token. The newly created flow is associated with this session.

  3. The authorization service redirects the browser to the PingOne authentication flow UI (or the configured URL of a custom UI), passing in the environmentId and flowSessionId parameters.

  4. The authorization flow UI calls the flow orchestration and action services to complete the authentication flow. This step includes password validation and optional multi-factor authentication actions.

  5. When finished, the authentication flow UI redirects to the /{environmentId}/as/resume endpoint to continue the authorization flow.

  6. The authorization service generates the access token for the implicit and refresh_token grants.

  7. For authorization_code and client_credentials grants, the application calls the /{environmentId}/as/token endpoint to acquire the access token.

Authorization requests for application types

The authorization flow steps needed to acquire an access token from the authorization service are determined by the application type. The following examples describe common authorization flows for the designated application type.

Web and native applications

Web applications and native applications support the authorization_code grant type to request access to protected resources. The /{environmentId}/as/authorize endpoint supports GET and POST methods and returns the authorization code needed to acquire an access token. After an authorization code is returned successfully, the code is used to get the access token.

The following sample shows the GET /{environmentId}/as/authorize operation.

curl --request GET \
  --url'https://auth.pingone.com/v1/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:env:population&acr_values=Single_Factor'

The request URL contains the following parameter values:

  • response type

    Specifies the response type for the authorization request. If the grant type is AUTHORIZATION_CODE, the response_type parameter must have a value of CODE. This parameter is required.

  • client_id

    Specifies the application’s UUID, returned from a GET /environments/{environmentId}/applications/{applicationId}/client request. This parameter is required.

  • redirect_uri

    Provides a URL that specifies the return entry point of the application.

  • scope

    Specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.

  • acr_values

    Designates whether the authentication request includes steps for a single-factor or multi-factor authentication flow.

The authentication code flow includes steps to initiate login actions. This flow uses the GET /environments/{environmentId}/flows/{flowId}/steps/{stepId} endpoint to retrieve the login action steps, and the POST /environments/{environmentId}/flows/{flowId}/steps/{stepId}/password endpoint to validate the username and password required by the login action. After all login action steps in the flow are completed, the GET /{environmentId}/as/resume endpoint continues processing the authorization request.

curl --request GET \
  --url 'https://auth.pingone.com/v1/{environmentID}/as/resume?flowId={flowID}'

After restarting the authorization flow, you can submit the authorization code through a request to the POST /{environmentId}/as/token endpoint to create the access token.

curl --request POST \
  --url 'https://auth.pingone.com/v1/{envID}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code={authCode}&redirect_uri=https%3A%2F%2Fexample.com'

The grant_type and code parameter values are required in the request body. The redirect_uri is a required parameter only if it was included in the original GET /{environmentId}/as/authorize request.

Native and single-page applications

Native and single-page applications support the implicit grant type. For this authorization flow, the application is issued an access token without requiring an authorization code exchange. When the request is made to the /{environmentId}/as/authorize endpoint for an implicit grant, the value of the response_type parameter is set to token or id_token.

Note: If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. The ID token includes the ID of the user; this request can also include the profile scope to add additional user claims to the ID token.

The following sample shows the GET /{environmentId}/as/authorize operation to return an id_token.

curl --request GET \
  --url 'https://auth.pingone.com/v1/{environmentID}/as/authorize?client_id={applicationID}&redirect_uri=https://example.com&response_type=id_token&scope=openid profile email&acr_values=Single_Factor'

The request can also specify both the token and id_token response types. The following sample shows the GET /{environmentId}/as/authorize operation to return an access token and an ID token:

curl --request GET \
  --url 'https://auth.pingone.com/v1/{environmentID}/as/authorize?client_id={applicationID}&redirect_uri=https://example.com&response_type=token id_token&scope=openid profile p1:read:env:population&acr_values=Single_Factor'

Note: In this request, the p1:read:env:population scope is included in the access token but not in the ID token.

The request URL contains the following parameter values:

  • response type

    Specifies the response type for the authorization request. The implicit grant type requires a response_type parameter value of token or id_token. This parameter is required.

  • client_id

    Specifies the application’s UUID, returned from a GET /environments/{environmentId}/applications/{applicationId}/client request. This parameter is required.

  • redirect_uri

    Provides a URL that specifies the return entry point of the application.

  • scope

    Specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.

  • acr_values

    Designates whether the authentication request includes steps for a single-factor or multi-factor authentication flow.

After all login action steps in the flow are completed successfully, the GET /{environmentId}/as/resume endpoint continues processing the authorization request.

curl --request GET \
  --url 'https://auth.pingone.com/v1/{environmentID}/as/resume?flowId={flowID}'

The authorization service generates the access token for the application after restarting the authorization flow; it does not require a step to call the /{environmentId}/as/token endpoint.

Non-interactive applications

Non-interactive applications support the client_credentials grant type to obtain an access token. These applications do not call /{environmentId}/as/authorize to initiate an authorization request. They bypass the authentication flow steps and call the /{environmentId}/as/token endpoint directly to acquire an access token.

Note: When configuring an internal application, the grant type must be a client_credentials grant, and the response_type must have a value of token.

The following sample shows the POST request to the /{environmentId}/as/token endpoint to acquire the access token. This request must have the tokenEndpointAuthMethod attribute value set to client_secret_post.

curl --request POST \
  --url 'https://auth.pingone.com/v1/{environmentID}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'scope=p1:create:env:population p1:read:env:population&grant_type=client_credentials&client_id={applicationID}&client_secret={secret}'

The request URL contains the following parameter values:

  • grant_type

    Specifies the grant type for the authorization request, which for non-interactive applications must be a client_credentials grant. This parameter is required.

  • client_id

    Specifies the application’s UUID, returned from a GET /environments/{environmentId}/applications/{applicationId}/client request. This parameter is required.

  • client_secret

    Specifies the application’s client secret, returned from a GET /environments/{environmentId}/applications/{applicationId}/secret request. This parameter is required.

  • scope

    Specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.

Note: For client_credentials requests in which the tokenEndpointAuthMethod attribute value is set to client_secret_basic, the client_id and client_secret attributes cannot be part of the request body. In these cases, the client_id and client_secret are passed in as a Base64 encoded authorization header in the request:

curl --request POST \
 --url 'https://auth.pingone.com/v1/{environmentID}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --user 'client_id:client_secret' \
 --data 'scope=p1:create:env:population p1:read:env:population&grant_type=client_credentials'

The --user 'client_id:client_secret' option tells curl to use a BASIC authentication header with the specified credentials in the request, which is similar to this:

Authorization: Basic <base64 encoded "client_id:client_secret">