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

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. The authorization service generates the access token for the implicit grant.

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

For more information about authorization, see OpenID Connect/OAuth 2.

Authorization requests for application types

The following examples describe common authorization requests for the designated application type.

Web applications

For web applications, the typical grant type to request access to protected resources is authorization_code. The /{{envID}}/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 /{{envID}}/as/authorize operation.

https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri=https%3A%2F%2Fexample.com&scope=openid%20profile%20email&acr_values=Single_Factor&prompt=login

The request URL contains the following parameter values:

The authorization request returns a URL to initiate login flow. This authentication flow presents appropriate login forms to an end user and submits data provided by the user for all required sign-on steps. After all login actions in the flow are completed, the GET /{{envID}}/as/resume endpoint continues processing the authorization request.

https://auth.pingone.com/{{envID}}/as/resume?flowId={{flowID}}

After restarting the authorization flow, the authorization code is submitted through a request to the POST /{{envID}}/as/token endpoint to create the access token.

curl --request POST \
  --url 'https://auth.pingone.com/{{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, code, and redirect_uri parameter values are required in the request body.

Native and single-page applications

For native applications and single-page applications, the default grant type to request access to protected resources is implicit.

For the implicit flow, the application is issued an access token without requiring an authorization code exchange. When the request is made to the /{{envID}}/as/authorize endpoint for an implicit grant type, the value of the response_type parameter is set to token or id_token.

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, email, address, and phone OIDC scopes to add additional user claims to the ID token.

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

https://auth.pingone.com/{{envID}}/as/authorize?client_id={{appID}}&redirect_uri=https:%3A%2F%2Fexample.com&response_type=id_token&scope=openid%20profile%20email&acr_values=Single_Factor&max_age=86400

The request can specify the token or id_token response types individually, or both. The following sample shows the GET /{{envID}}/as/authorize operation to return a token and an id_token:

curl --request GET \
  --url 'https://auth.pingone.com/{{envID}}/as/authorize?client_id={{appID}}&redirect_uri=https://example.com&response_type=token id_token&nonce=12345&scope=openid profile p1:read:user&acr_values=Single_Factor&max_age=86400'

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

The request URL contains the following parameter values:

After all login action steps in the flow are completed successfully, the GET /{{envID}}/as/resume endpoint is called to continue processing the authorization request.

https://auth.pingone.com/{{envID}}/as/resume?flowId={{flowID}}

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

Non-interactive applications

Non-interactive applications support the client_credentials, authorization_code, implicit, and refresh_token grant types to obtain an access token. For information about authentication flows for applications using the authorization_code and implicit grant types.

The following sample shows the POST request to the /{{envID}}/as/token endpoint to acquire the access token. Note that the application must have its tokenEndpointAuthMethod attribute value set to client_secret_post.

curl --request POST \
  --url 'https://auth.pingone.com/{{envID}}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&client_id={{appID}}&client_secret={{secret}}'

The request URL contains the following parameter values:

For client_credentials requests in which the application’s 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/{{envID}}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --user 'client_id:client_secret' \
 --data '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">

Worker applications

Worker applications are administrator applications that interact with platform APIs. This application type supports only the OPENID_CONNECT protocol. When creating a new worker application, the application inherits the same role assignments as the user or application that created the application. When getting a token using the client_credentials grant type, the application’s role assignments are used.

Worker applications that use a user-based grant type such as implicit or authorization_code let you assign only OIDC scopes to the application. When getting a token using a user-based grant type, the user’s role assignments are used.

The following sample shows the /{{envID}}/as/token request with a client_credentials grant to return an access token with no platform scopes.

curl --request POST \
 --url 'https://auth.pingone.com/{{envID}}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data 'grant_type=client_credentials&client_id={{appID}}&client_secret={{secret}}'

The response returns the access_token, the token_type, and the expires_in property values. It does not list any scopes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LW...",
  "token_type": "Bearer",
  "expires_in" : 3600
}