Table of Contents | ||
---|---|---|
|
Securing communication between participants - Authentication keys
All requests to BoB APIs (except the Participant Metadata API that has another type and Authentication API that have other types of authentication) must include a X-BoB-AuthToken header containing the JWT (auth token). For extra security, the JWT should contain the Holder of Key claim (bobHok) which is the fingerprint of the TLS client certificate used in the communication.
Setup - Authentication keys and BoB Authentication Service
...
- A participant that wants to call a BoB service other than participant metadata service will have to implement it's own authentication service.
The authentication service shall have an API that fullfills the specification defined by the BoB Authentication API.
The role of the authentication service is to create JSON Web Tokens (JWT) that shall be included in the X-BoB-AuthToken header and validated for each request to other BoB services . - The communication with the authentication service must be perfomed using a client certificate. Such a certificate has to be set up by Participant-1 for any internal client that is a trusted client allowed to requesting a JWT from the authentication service. For more information please see BoB Authentication API.
- Auth token key pair will have to be created by Participant-1.
The private part of the key pair, in this example called P1-authtoken-private-key, will be used by the authentication service when creating JWTs. The public part of the key pair, in this example called P1-authtoken-public-key, will be used by other participants when authenticating Participant-1 access to BoB services. - Set up the P1-authtoken-private-key for use by Participant-1's authentication service
- Store the P1-authtoken-public-key in Participant Metadata Service by calling the authTokenPublicKey operation of that service using method POST. The processes for managing Participant Meta Data is descibed in Management of own Participant metadata section above.
- Response of the POST authTokenPublic is returned to Participant-1.
Mechanism - Use of Authentication keys and JWT
...
- This sequence starts with a call from the "Participant-1 BoB client" to the "Participant-1 authentication service".
The reason for that is that a JWT has to be created so that it can be included in the X-BoB-AuthToken header when the "Participant-1 BoB client" calls the "Participant-2 BoB service".
The call from Participant-1 to the authentication service is made using a TLS-client certificate. - The authentication service recievs the call This call requires a TLS client certificate and the authentication service will
- Retrieve the finger print of the TLS client certificate
- Create JWT (JSON Web Token) including the mandatory and optional attribues as described in API Authentication and Authorization. This includes logging as well as setting the TLS client certificate fingerprint as value of attribute bobHok if applicable. When creating the JWT the private key of the auth token key pair, called P1-authtoken-private-key in the example above, is used.
- The JWT is returned to the client
- The JWT is added to the X-BoB-AuthToken header of the request
- The request is sent från BoB client to BoB service. If bobHok was created in step 2 this call requires a TLS client certificate.
- The request is terminated by proxy, if there is a client certificate that is valid, a SHA1 fingerprint of that certificate is added to http header
- Response returned
- Response to client