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

      • 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 applications. 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 methods:

      • 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 applications. 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 methods:

      • 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 methods:

      • 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 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. For prompt=login, the user is always prompted to login to re-authenticate. For prompt=none, the user is never prompted to login to re-authenticate, which can result in an error if authentication is required. 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 authentication 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">

Userinfo authorization requests

The /{environmentId}/as/userinfo endpoint returns claims about the authenticated user resource. A userinfo authorization request is used with applications associated with the openid resource. This type of request takes an access token in the Authorization header to get the claims about the user. The following sample shows the request:

curl -X GET \
  https://auth.pingone.com/{environmentId}/as/userinfo \
  -H 'Authorization: Bearer TOKEN'

The value for the Authorization header is the bearer token returned by the following authorization request:

https://auth.pingone.com/{environmentId}/as/authorize?client_id={applicationId}&redirect_uri=https://example.com&response_type=token&scope=openid profile email address&acr_values=Single_Factor

In the authorization request, the scope attribute must specify the openid value, which includes the sub claim (the user ID) in the response data. Additional OpenID Connect scopes such as profile, address, phone and email can also be included to add more user claims to the response.

The response data for a request that includes the openid, profile, email, and address scopes looks like this:

{
    "family_name": "Doe",
    "address": {
        "country": "US",
        "postal_code": "78750",
        "region": "TX",
        "locality": "Austin",
        "street_address": "123 Happy Street"
    },
    "given_name": "John",
    "email": "jdoe@example.com",
    "preferred_username": "jdoe",
    "updated_at": 1535377850,
    "name": "John Doe",
    "middle_name": "J",
    "sub": "0986b513-ae1f-4312-8d8d-a31eb79133ad"
}

Grants and scopes with userinfo

The access token used with the /{environmentId}/as/userinfo endpoint must be generated by an implicit or authorization_code grant type. In addition, the authorization request used to generate the access token must include the openid scope. The authorization request can also include any other OpenID Connect scopes (as shown in the sample above) to return additional user claims. PingOne user scopes such as p1:reset:self:userPassword are not applicable to userinfo authorization requests and applications associated with the openid resource.

Note: Access tokens generated from a client_credentials grant type return an ACCESS_FAILED message when used with the /{environmentId}/as/userinfo endpoint. Tokens from a client_credentials grant take administrator scopes such as p1:read:env:population. These scopes are not applicable to applications associated with the openid resource.