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

  • Native application

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

  • 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 applications. A single page application runs on the client side after it loads, so it cannot keep a client secret.

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

For more information about application types and their supported grant types, see the Application types topic in the PingOne for Customers Admin Console online help.

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 /{environmentId}/as/token endpoint to acquire the access token.

Authorization requests for application types

The application type determines the authorization flow steps needed to acquire an access token from the authorization service. 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/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:env:population&acr_values=Single_Factor&prompt=login'

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.

    Note: To ensure proper redirect on some iOS and OSX browsers, the redirect_uri value must include a trailing slash. For example, a registered URI of https://www.pingidentity.com/ redirects properly to https://www.pingidentity.com/#access_token=eyJsdf, but a registered URI of https://www.pingidentity.com redirects incorrectly to https://www.pingidentity.com/en.html, and the client application would not receive the access token.

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

  • prompt

    Specifies whether the user is prompted to login for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session.

The authorization code flow includes steps to initiate login actions. This flow uses the GET /{environmentId}/flows/{flowId}/steps/{stepId} endpoint to retrieve the login action steps, and the POST /{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/{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/{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/{environmentID}/as/authorize?client_id={applicationID}&redirect_uri=https://example.com&response_type=id_token&scope=openid profile email&acr_values=Single_Factor&max_age=86400'

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/{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_Factormax_age=86400'

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.

    Note: To ensure proper redirect on some iOS and OSX browsers, the redirect_uri value must include a trailing slash. For example, a registered URI of https://www.pingidentity.com/ redirects properly to https://www.pingidentity.com/#access_token=eyJsdf, but a registered URI of https://www.pingidentity.com redirects incorrectly to https://www.pingidentity.com/en.html, and the client application would not receive the access token.

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

  • max_age

    Specifies the maximum amount of time allowed since the user last authenticated. If the max_age value is exceeded, the user must re-authenticate.

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/{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 the 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. Note that the application must have its tokenEndpointAuthMethod attribute value set to client_secret_post.

curl --request POST \
  --url 'https://auth.pingone.com/{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 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/{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">