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.

  • Worker

    An administrator application that can interact with platform APIs. Access to platform APIs is determined by the user’s or application’s role assignments.

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.

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

Authorization requests for application types

The application type determines the authorization and authentication 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 applications

For web applications, the default grant type to request access to protected resources is authorization_code. 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.

https://auth.pingone.com/{environmentID}/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:

  • 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} request. This parameter is required.

  • redirect_uri

    Provides a URL that specifies the return entry point of the application. This parameter is required.

    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

    An optional parameter that designates whether the authentication request includes specified sign-on policies. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. For more information, see Sign-on policies.

  • prompt

    An optional parameter that 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 request returns a URL and session token 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 /{environmentId}/as/resume endpoint continues processing the authorization request.

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

After restarting the authorization flow, the authorization code is submitted 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, code, and redirect_uri parameter values are required in the request body.

Note: The authorization server can issue refresh tokens to web applications that use an authorization_code grant type.

Native and single-page applications

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

Note: Native applications also use the authorization_code grant type. For more information about the authorization_code grant type and its authentication flow, see Web applications.

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

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

https://auth.pingone.com/{environmentID}/as/authorize?client_id={applicationID}&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 /{environmentId}/as/authorize operation to return a 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&nonce=12345&scope=openid profile p1:read:user&acr_values=Single_Factor&max_age=86400'

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

  • 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 (or both). This parameter is required.

  • client_id

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

  • redirect_uri

    Provides a URL that specifies the return entry point of the application. This parameter is required.

    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.

  • nonce

    A string that is used to associate a client session with a token to mitigate replay attacks. The value is passed through unmodified from the authentication request to the token. This is a required property for authorization requests that return a token. It is not required for requests that return only an id_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

    An optional parameter that designates whether the authentication request includes specified sign-on policies. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. For more information, see Sign-on policies.

  • max_age

    An optional parameter that 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 is called to continue processing the authorization request.

https://auth.pingone.com/{environmentID}/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 /{environmentId}/as/token endpoint.

Note: The authorization server can issue refresh tokens to native applications. However, when a native application uses the implicit grant type flow, a refresh token is not returned.

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, see Web applications and Native and single-page applications.

Note: When configuring an internal application, the grant type must be a client_credentials grant. Internal applications using a client_credentials grant 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.

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

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 '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 /{environmentID}/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/{environmentID}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data 'grant_type=client_credentials&client_id={applicationID}&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
}