Manage authenticated clients who have access to the ProcessMaker Platform RESTful API.
Client Authentication uses OAuth 2.0 to delegate third-party client applications access to your instance's RESTful Application Program Interface (API), thereby allowing only authorized applications to call your API. OAuth 2.0 is an open standard for authorization authentication to authorize devices with access tokens rather than credentials.
As an Administrator, manage how client applications get their access tokens to authenticate to your instance, thereby providing better security for which applications can access your instance.
When creating or editing a client application authentication, configure how your ProcessMaker Platform instance obtains the token that grants access to your API. Use one or more of the following grant types:
Redirect URL when granting the client authorization: Use Authorization Code Flow, used by web and mobile applications, to specify the URI or URL where to send the authorized application after it is granted an access token to your API.
Enable password grant: Optionally, use Resource Owner Password Flow to authenticate legacy desktop applications which directly send a username and password to receive an access token to your API. If ProcessMaker Platform as the authorization server recognizes these credentials, the authorization server returns an access token to the client application. Resource Owner Password Flow is not as secure because it does not require a callback, so it is not best practice to use this authorization method unless granting the access token to a legacy desktop application. Furthermore, this authentication method typically does not support refresh tokens and assumes that the Resource Owner and Public Client are on the same device. Use Resource Owner Password Flow for when you have a client application that only authenticates with OAuth 1.0.
Enable personal access tokens: Optionally, use a personal access token (PAT) as an alternate password to authenticate the client application into your environment if that application supports its use. The third-party application developer is responsible for creating the PAT.
If necessary, delete an authenticated client to remove its access token. Created access tokens are not set to expire, so they should be deleted periodically, and then recreated. As a best practice, delete and then recreate application developer access tokens for the following reasons:
By revoking an application developer's access token, you require that developer to manage the application token.
Requiring application developers to manage their access tokens increases security to your environment's API.
Revoking access tokens ensures that application developers do not share them with others for whom they are not intended.
The Auth Clients page displays all authenticated clients in one table that Administrators throughout your organization have created. This makes it easy to manage authenticated clients to allow these users to access your RESTful API. The most recently created authenticated clients display at the top of the table.
Follow these steps to view all authenticated clients:
Log on to ProcessMaker Platform.
Click the Admin option from the top menu. The Users page displays.
The Auth Clients page displays the following information in tabular format about authenticated clients that can access your RESTful API:
Client ID: The Client ID column displays the Client ID for the authenticated client. The Auth Clients automatically generates the Client ID value when the client authentication is created and represents a sequential number of how many total authenticated clients have been created to that time.
Name: The Name column displays to whom the client authentication applies. See Create a New Client Authentication Key or Edit an Authentication Client.
Redirect: The Redirect column displays the URI or URL where to send the authorized application after it is granted an access token to your API if the the Enable Authorization Code Grant option is used to grant an access token for that client application. See Create a New Client Authentication Key or Edit an Authentication Client.
Create a new authenticated client that can access our RESTful API.
Follow these steps to create an authenticated client that allows that application to access our RESTful API in your instance:
View all authenticated clients. The Auth Clients page displays.
Click the +Auth Client button. The Create Auth-Client screen displays.
In the Name setting, enter to whom the client application is granted. This name must be unique from all other authenticated clients. This is a required setting.
Select at least one of the following options to indicate how the client application is being granted access to your RESTful API:
Enable Authorization Code Grant: Select the Enable Authorization Code Grant checkbox to display the Redirect URL setting in this screen to enter the URI or URL where to send the authorized application after it is granted an access token to your API. If this checkbox is not selected, the Redirect URL setting is hidden and that client application cannot access your instance via a redirected URL.
Enable Password Grant: Select the Enable Password Grant checkbox to authenticate legacy desktop applications which directly send a username and password to receive an access token to your API. If ProcessMaker Platform as the authorization server recognizes these credentials, the authorization server returns an access token to the client application. This authorization method is not as secure because it does not require a callback, so it is not best practice to use this authorization method unless granting the access token to a legacy desktop application.
Enable Personal Access Tokens: Select the Enable Personal Access Tokens checkbox to use a personal access token (PAT) as an alternate password to authenticate the client application into your environment if that application supports its use. The third-party application developer is responsible for creating the PAT.
Click Save. The new authenticated client information displays in the Auth Clients page.
Delete an authenticated client.
When authenticated client information is deleted, the application to whom the client authentication applied no longer can access our RESTful API in your instance.
Deleting an authenticated client from the Auth Clients page cannot be undone.
Follow these steps to delete authenticated client information:
View all authenticated clients. The Auth Clients page displays.
Click Confirm.
Click the Auth Clients icon from the left sidebar. The Auth Clients page displays Client Secrets for all authenticated client applications.
Client Secret: The Client Secret column displays the Client Secret for the authenticated client. The Auth Clients automatically generates the Client Secret when the key is created. Click the Copy Client Secret to Clipboard iconto copy the Client Secret. Paste the Client Secret into your authorization server.
Click the menu, and then select the Delete Auth Client option for the authenticated client to delete. The Caution screen displays to confirm the deletion of the authenticated client.
Edit an authenticated client.
In the Name setting, enter to whom the authenticated client application is granted. This name must be unique from all other authenticated clients. This is a required setting.
Edit any of the following options as necessary to indicate at least one method by which the client application is granted access to your RESTful API:
Enable Authorization Code Grant: Select the Enable Authorization Code Grant checkbox to display the Redirect URL setting in this screen to enter the URI or URL where to send the authorized application after it is granted an access token to your API. If this checkbox is not selected, the Redirect URL setting is hidden and that client application cannot access your instance via a redirected URL.
Enable Password Grant: Select the Enable Password Grant checkbox to authenticate legacy desktop applications which directly send a username and password to receive an access token to your API. If ProcessMaker Platform as the authorization server recognizes these credentials, the authorization server returns an access token to the client application. This authorization method is not as secure because it does not require a callback, so it is not best practice to use this authorization method unless granting the access token to a legacy desktop application.
Enable Personal Access Tokens: Select the Enable Personal Access Tokens checkbox to use a personal access token (PAT) as an alternate password to authenticate the client application into your environment if that application supports its use. The third-party application developer is responsible for creating the PAT.
Click Save.
See the permissions or ask your Administrator for assistance.
Follow these steps to edit authenticated client information that allows that application to access our in your instance:
The Auth Clients page displays.
Click the menu, and then select the Edit Auth Client option for the authenticated client to edit. The Edit Auth Client screen displays.