Authentication
Description of concepts behind authentication system and how to prepare your own security.
Last updated
Was this helpful?
Description of concepts behind authentication system and how to prepare your own security.
Last updated
Was this helpful?
Requests between Ergonode and App are signed using tokens.
These tokens allow the safe exchange of custom data(claims) between two parties.
The token contains claims describing the context of the execution - what specific installation the token is referencing etc.
The token is always available in X-APP-TOKEN
HTTP header with a signature signed using HMAC SHA-256.
To authenticate the token firstly, on App installation, a handshake is exchanged.
Handshake is a request to [POST] /handshake
path of .
It contains two important pieces of information:
X-APP-TOKEN
HTTP header
shared secret in the request body
This secret should be persisted, i.e. the database of choice, and kept by your App safe with information about the app installation it belongs to and the Ergonode API URL retrieved from claims:
app_installation_id
api_url
All the following requests by Ergonode to an App should be authenticated using this secret.
You should also encrypt the shared secret within the persistent storage so it is not easily retrievable.
The response status has to be 2xx to process installation appropriately.
Steps to verify whether the request is coming for a specific App installation from Ergonode
obtain the token from X-APP-TOKEN
HTTP header of the request
extract the app_installation_id
claim from the JWT without signature verification
retrieve shared secret persisted on the handshake
verify JWTs signature using HMAC SHA-256 algorithm and the shared secret
Steps to create an appropriate token authenticating in Ergonode API
establish the App installation ID
create claims - at the very minimum the following claims are required: app_installation_id
, nbf
(not before), iat
(issued at), exp
(expiration time)
retrieve, persisted on the handshake, shared secret
create JWT with signature signed with HMAC SHA-256 algorithm and the shared secret
send the token as X-APP-TOKEN
HTTP header to Ergonode API URL from handshake
Alternatively, on the requests from the Ergonode, i.e. in synchronization context, you can reuse the token provided by the Ergonode.