Example: Use “Password Grant Authentication” for Applications to Authenticate

Learn how to authenticate applications using password authentication.

Overview

Some client applications use Password Grant authentication, despite that this authentication type is deprecated in OAuth 2.1 specification. Use the following example to allow password authentication.

This example requires the following procedures and possibly two different roles to perform them in this order:

1. ProcessMaker Platform administrator: Configure password authentication for the client application.

2. Application developer:

   1. Prepare for the first API call.

   2. Use the bearer token to make future API calls.

   3. Use the refresh token to request a new bearer token.

Configure Password Authentication for the Client Application

Follow these steps to configure password authentication for the client application:

1. View authenticated clients. The Auth Clients page displays.

   

2. Click the +Auth Client button. The Create Auth-Client screen displays.

   

3. In the Name setting, enter a name for this client authentication. This examples uses Client Authentication for Client Application.

4. Select the Enable Password Grant setting.

   

5. Click Save. A new authenticated client is created.

6. Locate the authenticated client in the Auth Clients page, and then click the Copy Client Secret to Clipboard icon.

   

7. Provide the client secret to the application developer, and then provide instructions how to prepare the first API call.

Prepare the First API Call

After the ProcessMaker Platform administrator has granted the application permission to authenticate using a password, the application developer may then prepare for the first API call to the ProcessMaker Platform instance. The first call obtains a bearer token to be used for future API requests.

Follow these steps to prepare the first API call:

1. Prepare the body of your first request in JSON format. Replace the values in brackets below with the actual values from your environment.

   {
     "grant_type": "password",
     "client_id": "[Client ID]",
     "client_secret": "[Client Secret]",
     "username": "[Username]",
     "password": "[Password]"
   }

2. Send the prepared JSON body as a POST request to the endpoint /oauth/token in your ProcessMaker Platform instance. Below is an example using the test environment from the image above. Most notable is the client_id value, which is the row designated in the Client ID column of the Auth Clients page, and its client secret value.

   curl -X "POST" "https://processmaker.test/oauth/token" \
        -H 'Content-Type: application/json; charset=utf-8' \
        -d $'{
     "client_id": "6",
     "username": "admin",
     "password": "admin",
     "client_secret": "qA5ZRjXGGQYBrHPEj2frR0L8NSEd8yGOOmSJwVfd",
     "grant_type": "password"
   }'

3. Send the first request. Your ProcessMaker Platform instance responds in JSON format. This is the bearer token from which future API calls may be used. Below is an example of the bearer token.

   {
     "token_type": "Bearer",
     "expires_in": 31622400,
     "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiN2Q2ZTc3MDdhMDBkNzI1YjljMjk2ZDFhNTNiMTBlMGY1MDQ4NGZmNWIwZTE2M2NjMDRlNTEzNzUxOGZlMGNhZTE5NmE0NDhiMTVlMjUyNTQiLCJpYXQiOjE2ODIwMTA0NzIuNTM2MDkxLCJuYmYiOjE2ODIwMTA0NzIuNTM2MDkyLCJleHAiOjE3MTM2MzI4NzIuNTI2NjIxLCJzdWIiOiIxIiwic2NvcGVzIjpbXX0.TH7HSmMM3FtYzTFkRgMwcrZpPt_3ioGrJG-ZOxy8iYSrZHSBx6Fq_LUHudluAT63Sz3ZmxCRhFXiDDpRZUMrOPPB7-JN3_42JeJmGcivPg9w58pbaJG3n5we_IF_Ii7mjK2J6siv9KLBxEtwoDyxnYhZoZnVb4H6MfWOI-ZtNg-VjF9yJN9xl_zBoNUOFgfEcT7V-rDG_RzqCzO0QZgu81cwrpSyJ6IWMu6TJVZQL7W0h2a-b09pdIYBNzDUgcZ3GwOjPhQgFgd_XUoeVM2JKzOAKV6M2axm6aEnWf8jUyFHetySe8KDt62M9wCW9zAg8G_6X88lsMi8GWmDDpsY-c9iQkyox9vzlRrFTUXJjacSz532JsJcmwbbEyYZ20uMJ6fW3bg9fOQsuOBfRxjTVGnh54_brg3OJT23JhbrPR4bFMSfvCQImQNgZsiqAaZFtGwMFXIC92hnMfHmOh5G9H3XPjWVSDQ16dEVY9pfynSKkPCgFR9o71CBYoC76bgtdu7hrg9hyUO-7CSVP9EgdCiZFjEXMry3ptde8DHSzr8T1zizNI2_nJ-LllEnx_CxzH_FdXCweLynUpDZtII2AQmrma6SfJZSj5AY21NHgu3pnnw2RnK6Ds_i-bDR9T1-2mAC2VC8v8fsfep8_kY6V3MfXQuc3eU2i3Ld7ma4Umk",
     "refresh_token": "def50200564ed7ebfc328b1981b4604206eb22265d6e7d852428f0db31c0a3011eacc0e5624d7001e040329700578fb021fc5278b55f7dc95623f09af6380f43b158ab31ea0aaf15337ce7ef05aa628304b79670d778bb8425fc7e3d81f47d38437e2410efc27d450da3219297ac90baa44aacb4ebfa22ea22077c3b8fea509bc9ad4f8a43e793a90d32460805dd95e09c6ed3983d8f0620584ab27540e1114e8b95d6fdbfbe8052b9ead748677143a8b68eb22a0b8597a9cff320173332f7296cd53cc59055e41f0b926001b1fb943b98511628f55e46d5d87da3d99a3d5c37b1975550fb6909f00fb138ed3b0b7d170427467b32b0f42769e83e1af913464d330c55a5ea64f9c7ae07ac09c82d2e73c6b75458a235f9efabcff3aacb63f075ec85895ef100e29f381dc2c83b73e2f528012864aa59b9a0dde704e19f537f8e081f4b6ce397d80c9d7261f3306fba6b3d108f0060a4a653740a4aed624f19bf84"
   }

4. Use the bearer token to make future API requests.

Use the Bearer Token to Make Future API Calls

After successfully making the first API call to your ProcessMaker Platform instance with the application, use the bearer token to make future API calls.

Below is an example of using the bearer token to make a request that lists all users.

curl "https://processmaker.test/api/1.0/users" \
     -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIj

Use the Refresh Token to Request a New Bearer Token

Note that the response containing your bearer token also contains a time of expiration and a refresh token. The expiration time is the number of seconds until the bearer token expires. After that time, request a new bearer token using the refresh token. Below is an example API call that obtains a new bearer token using the refresh token.

curl -X "POST" "https://processmaker.test/oauth/token" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "client_id": "6",
  "refresh_token": "def50200564ed7ebfc328b1981b4604206eb22265d6e7d852428f0db31c0a3011eacc0e5624d7001e040329700578fb021fc5278b55f7dc95623f09af6380f43b158ab31ea0aaf15337ce7ef05aa628304b79670d778bb8425fc7e3d81f47d38437e2410efc27d450da3219297ac90baa44aacb4ebfa22ea22077c3b8fea509bc9ad4f8a43e793a90d32460805dd95e09c6ed3983d8f0620584ab27540e1114e8b95d6fdbfbe8052b9ead748677143a8b68eb22a0b8597a9cff320173332f7296cd53cc59055e41f0b926001b1fb943b98511628f55e46d5d87da3d99a3d5c37b1975550fb6909f00fb138ed3b0b7d170427467b32b0f42769e83e1af913464d330c55a5ea64f9c7ae07ac09c82d2e73c6b75458a235f9efabcff3aacb63f075ec85895ef100e29f381dc2c83b73e2f528012864aa59b9a0dde704e19f537f8e081f4b6ce397d80c9d7261f3306fba6b3d108f0060a4a653740a4aed624f19bf84",
  "client_secret": "qA5ZRjXGGQYBrHPEj2frR0L8NSEd8yGOOmSJwVfd",
  "grant_type": "refresh_token"
}'