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:
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 native 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.
An authorization grant gives applications the capability to authenticate users and access secure resources. The following steps describe the application authorization flow:
The application initiates the authorization flow through a GET
or POST
request to the authorize
endpoint.
The authorization service generates the access token for the implicit
grant.
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.
The following examples describe common authorization requests for the designated application type.
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:
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/{{envID}}/applications/{{appID}}
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 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.
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:
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/{{envID}}/applications/{{appID}}
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 /{{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 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:
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/{{envID}}/applications/{{appID}}
request. This parameter is required.
client_secret
Specifies the application’s client secret, returned from a GET /environments/{{envID}}/applications/{{appID}}/secret
request. This parameter is required.
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 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
}