REST data interface - Authentication
This topic shows how to use the authentication service for protected resources on the PLCnext Engineer embedded HMI web server in order to use this service for making the REST data interface a protected service as well.
latest key.Concept
Authenticating at the REST data interface is a 2-step process:
- Requesting an authentication token
- Requesting a user authentication where the request body contains the above authentication token
After that, using the resulting access token gets you access to the GDS ports and variables.
The implementation of making the REST data interface a protected resource is based loosely on OAuth 2.0 as described in RFC 6749 (note: there are some differences!).
Procedure
This drawing shows the authentication procedure in the PLCnext Technology context:
(A) The client requests authorization for the REST data interface. This grants the client permission to authenticate to the pxc_api (Phoenix Contact API). The request includes a secret known to the client that must be echoed back in the response from the server.
(B) The server responds with an authorization token and with the secret the client provided.
(C) When the user attempts to log in, the client sends the user name and password in clear text over an encrypted channel (TLS).
(D) If the PLCnext Runtime System's security subsystem accepts the user and password, then the access token and roles for that user are returned in the response.
Once the access token has been received by the client, the following exchange occurs on each data request:
(E) The client includes the access token in the HTTP header pxc_api data request using an Authorization header and a Bearer token.
(F) On successful verification of the Bearer token in the request header, the request data is returned.
Errors
Authentication errors are returned in theWWW-Authenticate Response Header field using the framework described in HTTP/1.1 RFC 2617.
invalid_token in the error response indicates that the token is missing or invalid.
invalid_grant indicates that the user and password do not match any credentials on the server.
How to
Requesting an authentication token
Send a request with the following body to the request URI:
Request URI (HTTP method POST) |
https://192.168.225.78/_pxc_api/v1.2/auth/auth-token |
| Request body (.json) | {"scope":"variables"} |
| Response (.json) | {"code":"yourAuthToken","expires_in":600} |
The authentication token that is transmitted in response will be bound to the requesting IP address until expiration.
Requesting a user authentication
Insert the authentication token ("yourAuthToken"), a valid user name and the corresponding password into a new request body.
Send a request with the prepared body to the request URI:
Request URI (HTTP method POST): |
https://192.168.225.78/_pxc_api/v1.2/auth/access-token |
| Request body (.json): | {"code": "yourAuthToken", "grant_type": "authorization_code", "username": "admin", "password": "PLCpassword"} |
| Response (.json): | e.g. {"token_type":"Bearer","access_token":"df3b895e160a92f1","roles":[]} |
The access token that is transmitted in response grants access to the GDS ports and variables if put into an HTTP header. In the data request the user roles are transmitted which are associated with the user name. The user roles meet the EHmiLevels as set in the Web-based Management.
Requesting data
An example data request would contain in the header the following key-value pair:
{"Authorization": "Bearer xyz"}
Please refer to the regarding topics for details on the request commands and reading/writing variables.
Disabling the authentication
Note: With default settings, the access to the REST data interface requires user authentication via the PLCnext user management. Phoenix Contact recommends these default settings for security purposes.
In case you need direct access without authentication, the authentication can be deactivated in the HMI Webserver security settings as shown here:
