The Secrets of the OCPI Credentials module
Photo by Karolina Grabowska / Pexels
Before implementing the OCPI Credentials module, I would recommend you to take a look at Implementing OCPI – Tips and Tricks.
The OCPI Credentials exchange forms the basis for authentication and authorization between OCPI Platforms. The OCPI Platform uses the Credentials module both to establish and maintain communication with other OCPI Platforms.
The phases of the OCPI Credentials exchange
The exchange starts with the admins of two or more OCPI Platforms contacting each other offline. The first shared secret, the token_a, is transmitted between admins over a secure channel with the Versions endpoint URL (which is publicly accessible). Generally, this channel should preferably not be email or a chat app.
After the initial contact, the Credentials registration process takes places between the OCPI Platforms over two HTTPS connections. If you look at the OCPI Credentials registration flow chart, it may look daunting at first. What is actually happening is that the same sequence is mirrored so that each party initiates their own exchange.
The exchange consist of these steps:
1) Platform GETs the version info from the other platform
2) Platform GETs the endpoints list from the other platform
3) Platform generates a token and POSTs its Credentials record to the other party
4) Before responding to the POST in 3), the other platform in turn performs the steps 1) and 2)
The token generated in part 3 will be used until a new token may be generated at a later time.
IMPORTANT: Generating a new Credentials Token and pushing it to the other Platform does not undo a security breach. If your security has been compromised, you need to start the exchange again with a new token_a communicated offline between admins.
Do not allow the other party to change their country_code and party_id after verifying their identity during the initial Credentials registration process.
After the exchange is finished, the platforms are able to share information about Locations, Tariffs, Tokens and other OCPI objects in a secure way. What is essentially happening is that any changes to OCPI objects are reflected in connected systems near real time. Smaller changes, such as charger status change, are distributed to others using HTTP PATCH. Bigger changes like a new Location or Token are sent using HTTP PUT.
NOTE: Token_a is used as a shared secret only during the Credentials registration and its use must be limited to the versions endpoint, endpoints list and POST Credentials. After tokens have been exchanged, token_a should be ignored.
Consider Also Implementing the HubClientInfo module
When implementing the Credentials module, it is useful to know if you are going to implement also the HubClientInfo module. The HubClientInfo module provides knowledge about the connection status of known parties. Due to overlapping data between Credentials and HubClientInfo, we recommend that the data required for HubClientInfo would be incorporated into the Credentials data structures. In practice, this includes two fields; status (the connection status) and last_updated (which you could call ”last_connection” internally, not to overlap with Credentials.last_updated).
Why implement HubClientInfo?
With the HubClientInfo we can communicate system wide status to the EV driver. In case an OCPI Platform drops momentarily off the network, the chargers without Token whitelists are inoperable. When the e-Mobility Service Provider shows charging stations on the map, the operational status of an individual charge point should reflect the following:
– The charge point has sent some data, a status change or a “still alive” message within a few minutes and it is available to start a session
– The OCPI Platform which manages the roaming for the charge point has sent data or answered a GET versions request during the past few minutes
Using the HubClientInfo, you can provide better service to the EV driver and work towards earning their trust.
What to do next?
To test your OCPI implementation, try the OCPI Connector. You can learn more by booking a meeting with our specialist.
Erkki Tapola is a multi-faceted IT professional with a background in technology, leadership and products. Since 2020 he has focused on EV roaming and the OCPI protocol. Erkki founded SolidRoam in 2023 to continue the work of ChargerHub.EU, and he acts as CEO. His passion is to improve the reliability and ease of use in electric mobility. In his spare time he’s into electric road trips, couples dancing, bicycling and photography.
