Authentication and Authorization (OAuth)
Authentication and autorization are required to protect data stored in PolyWorks|DataLoop. The system insures that the data accessed through the PolyWorks|DataLoop API remains at the same security level than PolyWorks|DataLoop Web Interface and PolyWorks|Inspector.
PolyWorks|DataLoop uses the OAuth 2.0 and OpenID Connect standard protocol to rely on proven techniques and to allow external provider integration in the future.
OAuth2 Overview for DataLoop API
Here is a presentation of the OAuth flow in general:
On the left hand side, we see the API client application. For OAuth2, there are two steps before calling the PolyWorks|DataLoop API: first, the user must be authorized; and second, the application must be authorized.
Here is a more detailed explanation of the steps in the diagram:
A. The API client requests authorization to access the PolyWorks|DataLoop API service from the user.
B. If the user is authenticated, the API client receives an authorization grant.
C. The API client requests an access token from the PolyWorks|DataLoop authorization server by presenting authentication of its own identity and the authorization grant (representing the user).
D. If the API client is authenticated and the authorization grant is valid, the PolyWorks|DataLoop authorization server issues an access token to the application.
E. The API client requests the endpoint from PolyWorks|DataLoop API server and presents the access token for authorization.
F. If the access token is valid, the PolyWorks|DataLoop API server gives the resource to the API client.
API client authorization
Before using OAuth with your API client, it must be registered with PolyWorks|DataLoop. This is not configurable for the moment.
However, two default redirect URIs are provided to use with your API client, depending on the type of client: com.innovmetric.DataLoopCore://oauth/redirect/public or http://127.0.0.1
The redirect URI is where PolyWorks|DataLoop authorization server will redirect the user after they authorize or deny the API client. It is therefore the part of your application that will handle authorization codes and access tokens.
OAuth2 Authorization Code Flow (interactive)
For increased security and to avoid man-in-the-middle-attack scenarios, each client application requesting access to the PolyWorks|DataLoop API must comply to the Authorization Code Flow standard of OAuth2.
The main difference here is that the web browser must be used to redirect the user to the secure login and post-login pages according to the server's configuration. It also allows the use of Windows session credentials or any other configured identity provider.
This is required for all interactive integration scenarios.
Personal access token (PAT)
2022 IR4 and later
Personal access token are available in 2022 IR4 and later.
Personal access tokens (PAT) can be used to get access tokens with OAuth, without requiring an interactive user flow to obtain the code. This is more suitable for scripts or recurring jobs that run in the background.
A. The steps that involve the user authentication and the application authorization must still be done using a web browser in an interactive manner.
However, once logged in and access validation is completed, it is possible to generate a PAT to be used in the non-interactive script to invoke the PolyWorks|DataLoop API server within a specified time limit (e.g., token expiration) and other usage conditions.
B. The PAT can be copy-pasted to the script/job so as gain access tokens which will grant limited access to perform API calls on behalf of the aforementioned user if usage conditions are respected.
Security concerns
For security reasons, even though the user is a PolyWorks|DataLoop administrator, the generated PAT will not use this administrator permission to access the PolyWorks|DataLoop API resources.
It is important to ensure that certain measures are put into place, a governance to ensure that the PAT is not used outside its usage scope:
- Store them securely
- Do not share them
- Keep a small scope usage for each generated PAT
- Renew the generated PATs periodically
- Use variables to store the PATs in scripts or applications code
Use a dedicated user for integrations
It is recommended that a specific user be created only to be used in automated integrations with PolyWorks|DataLoop API. This allows a better traceability for API requests and it mitigates security breaches, since it is possible to easily revoke user personal access tokens.
Other security grant types (non-interactive)
For scenarios where an interactive login is difficult, it is also possible to use other security grant types (or flows) to gain access tokens which will grant limited access to the desired resources. Depending on the grant type that is chosen, it is important to ensure that certain measures are put into place to remove possibilities of security breaches that can occur, for example, from someone sharing their credential with another person.
If assistance is needed in setting up a different grant type for such scenarios, please contact supportapi@innovmetric.com.
Password grant type
Password grant type is no longer supported in PolyWorks|DataLoop 2022 IR4 and later
Additional information
Updated almost 2 years ago