Authorization server service


Authorization server

The PingOne authorization server service configures the authorization grants that are used to authenticate users and provide access to resources. Access tokens are obtained from the authorization server’s /token endpoint (when using the client credentials grant type) or from the authorization endpoint (when using the implicit grant type).

Authorization server API operations

The authorization server service supports the following endpoint operations:

For hands-on experience with the authorization server API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Authorization server data model

Property Description
acr_values A string that designates whether the authentication request includes steps for a single-factor or multi-factor authentication flow. The value specified must be the name of a sign-on policy for which the application has a sign-on policy assignment.
client_id A string that specifies the application’s UUID.
client_secret A string that specifies the application’s client secret.
code A string that specifies the authorization code returned by the authorization server.
grant_type A string that specifies the grant type for the authorization request. Options are authorization_code, implicit, refresh_token, and client_credentials.
id_token_hint A string that specifies the ID token passed to the logout endpoint as a hint about the user’s current authenticated session.
max_age A string 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.
redirect_uri A string that specifies the a URL that specifies the return entry point of the application.
postLogoutRedirectUris A string that specifies an optional parameter that specifies the URL to which the browser is redirected after a logout has been performed.
prompt A string that 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.
response_type The list of the OAuth 2.0 response_type values that the application is restricted to using. Options are code, id_token, and token.
scope A string that specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.
state A string that specifies an optional parameter that is used to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.
tokenEndpointAuthMethod A string that specifies the token endpoint authentication method. Options are none, client_secret_basic, and client_secret_post.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get authorization

The following sample shows the GET /{environmentId}/as/authorize operation. The request URL includes the response_type parameter with a value of code, which designates that this authorization request, if successful, returns an authorization code that is exchanged for an access token.

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'

Create authorization requests

The following sample shows the POST /{environmentId}/as/authorize operation. The request includes a response_type parameter with a value of token, which designates that this authorization request, if successful, returns an access token.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/authorize' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'response_type=token&client_id=%7B%7BappID%7D%7D&redirect_uri=https%3A%2F%2Fexample.com&scope=openid%20profile%20p1%3Aread%3Aself%3Auser'

Get an OIDC authorization request

The following sample shows the GET /{environmentId}/as/authorize operation that enables verification of user identities based on the authentication performed by the authorization server.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/as/.well-known/openid-configuration' \
  -H 'Content-Type: application/x-www-form-urlencoded'

Get userinfo authorization requests

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.

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

Create userinfo authorization requests

You can use the POST /{environmentId}/as/userinfo operation to create a userinfo authorization request. The following sample shows the request:

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

Resume authorization

The authorization server calls the flow orchestration and action services to complete the authentication flow steps required to authenticate the user. When finished, the flow orchestration service redirects to the authorization server’s GET /{environmentId}/as/resume endpoint to continue the authorization flow.

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/resume?flowId={flowID}'

This operation specifies the authorization server’s flow ID as a parameter in the request URL to identify the authorization flow to resume.

Create token

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

For an authorization_code grant type, the request looks like this:

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=%7B%7BauthCode%7D%7D&redirect_uri=https%3A%2F%2Fexample.com'

The request body must provide values for the following required properties:

  • grant_type

    Specifies the grant type for the authorization request

  • code

    Specifies the authorization code returned by the authorization server.

  • redirect_uri

    Provides a URL that specifies the return entry point of the application.

For client_credentials grant type, the request looks like this:

curl -X POST \
  'https://auth.pingone.com//as/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=p1%3Acreate%3Aenv%3Apopulation%20p1%3Aread%3Aenv%3Apopulation'

The request body must provide values for the following required properties:

  • grant_type

    Specifies the grant type for the authorization request

  • client_id

    Specifies the application’s UUID.

  • client_secret

    Specifies the application’s client secret.

  • scope

    Specifies permissions that determine the resources that the application can access.

Get-jwks

The JSON Web Key (jwks) is a JSON representation of the cryptographic key. The GET /{environmentId}/as/jwks endpoint is called by external users to get information on how access tokens generated by the PingOne authorization server are encrypted.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/as/jwks'

Get signoff

Signoff actions specify the operations required to initiate the PingOne standard signoff flow. You can use GET /{environmentId}/as/signoff to call the end session endpoint used by the flow orchestration service to initiate the logout flow.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/as/signoff?id_token_hint='

The request URL includes the id_token_hint parameter, which is a required attribute that specifies the ID token passed to the logout endpoint as a hint about the user’s current authenticated session.

The request can also include the following optional attributes: