Secure remote gRPC using grpcurl

WARNING: The procedure described in this blog uses features of the PLCnext Runtime that are currently not supported. Use these features at your own risk, and definitely do not use these features in production applications.

In an earlier article, we saw how to use the (still not officially released) remote gRPC server feature of the PLCnext Runtime.

In that article, gRPC calls were made using the -insecure option, so the server's X509 certificate was not checked. Some gRPC calls also require authenticaion (using a username and password), but this can also be bypassed by disabling authentication on the PLC's web-based management (WBM) page.

Bypassing security features may be handy while developing and troubleshooting an application, but security features should always be enabled for applications that are deployed in a production environment.

If you're wondering how to use grpcurl with security features enabled, this article is for you.

Procedure

• Complete the steps in the earlier article to set up the gRPC server on the PLC, and to set up grpcurl and install the protobuf files on the gRPC client.

• Open the Web-based management (WBM) page for the PLC, and on the User Authentication page (in the Security menu area), make sure User Authentication is enabled.

• If you have changed the IP address of the PLC from the default value, you may need to regenerate the HTTPS certificate to be sure it contains the correct IP address details. On the WBM site, open the Web Services page (in the Configuration menu area), and press the Re-generate HTTPS certificate button, and then the Apply button.

• The client needs a copy of the PLC's HTTPS certificate in order to trust the gRPC server. On the WBM site, open the Certificate Authentication page (in the Security menu area). Click on the Identity Stores tab. Download the Certificate from the HTTPS-self-signed Identity Store to the gRPC client machine.

• In order for the gRPC Server to use the latest HTTPS certificate, restart the PLCnext Runtime, e.g. with the command:

  sudo /etc/init.d/plcnext restart
  

Now try the following commands on the gRPC client machine:

1. Create a secure session (change the IP address and username/password for your device)

   grpcurl -cacert HTTPS-self-signed_certificate.crt -import-path Documents/plcnext-grpc/protobuf -proto System/Security/IAuthenticationService.proto -d '{"username":"admin","password":"00000000"}' 192.168.8.222:50051 Arp.System.Security.Services.Grpc.IAuthenticationService/CreateSession
   

   Response:

   {
      "sessionId": "ac3661ad8fd7d006cc46f1155590f072"
   }
   

2. Use the HTTPS certificate and the session ID to make other secure calls, like ReadSingle.

   $ grpcurl -cacert HTTPS-self-signed_certificate.crt -rpc-header 'sessionid:ac3661ad8fd7d006cc46f1155590f072' -import-path Documents/plcnext-grpc/protobuf -proto Plc/Gds/IDataAccessService.proto -d '{"portName":"Arp.Plc.Eclr/MainInstance.MyInt"}' 192.168.8.222:50051 Arp.Plc.Gds.Services.Grpc.IDataAccessService/ReadSingle
   

   Response:

   {
      "ReturnValue": {
    	 "Value": {
    	  "TypeCode": "CT_Int16",
    		"Int16Value": 0
    	 }
      }
   }
   

3. Close the session when you're done (or just let it time out)

   $ grpcurl -cacert HTTPS-self-signed_certificate.crt -rpc-header 'sessionid:ac3661ad8fd7d006cc46f1155590f072' -import-path Documents/plcnext-grpc/protobuf -proto System/Security/IAuthenticationService.proto 192.168.8.222:50051 Arp.System.Security.Services.Grpc.IAuthenticationService/CloseSession
   

   Response:

   {
      "result": true
   }
   

For more help ...

Use grpcurl -help to get more information on available options.

For questions about the gRPC Server in the PLCnext Runtime, please use the PLCnext Community Forum.