Authentication and authorization for the BoB APIs is based on federated JSON Web Tokens (JWT) issued by each participants' authentication service, the BoB Authentication API. All requests to BoB APIs (except the Participant Metadata API that has another type of authentication) must include a X-BoB-AuthToken header containing the JWT. The request should also be authenticated via TLS client authentication using a certificate cryptographically bound to the JWT (the Holder of Key claim).
Authentication API
JWT Claims
BoB uses RFC 7519 JWTs and claims as described in the BoB Authentication API specification and below.
...
In BoB, use of this claim is MANDATORY and it MUST be set to the PID (string) of the token issuer.
| Code Block |
|---|
"iss": "1" |
Subject
From RFC 7519:
The "sub" (subject) claim identifies the principal that is the subject of the JWT. The claims in a JWT are normally statements about the subject. The subject value MUST either be scoped to be locally unique in the context of the issuer or be globally unique. The processing of this claim is generally application specific. The "sub" value is a case-sensitive string containing a StringOrURI value.
...
| Code Block |
|---|
"sub": "validator1337" |
Expiration Time
From RFC 7519:
The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the "exp" claim requires that the current date/time MUST be before the expiration date/time listed in the "exp" claim.
Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value.
...
| Code Block |
|---|
"exp": 1518468889 |
Not Before
From RFC 7519:
The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value.
...
| Code Block |
|---|
"iat": 441759649 |
Authorization Class
The "bobAuthZ" (authorization class) claim identifies that BoB AuthZ group of the JWT holder. Its value must be a string containting the Bob AuthZ group. Use of this claim is MANDATORY.
...
| Code Block |
|---|
"bobHok": "bf1091800d1221f9a35ec087a67e2d6209d6478e" |
Recommendations
It is strongly advised that authentication APIs set the bobHok claim in issued JWTs.
API server Processing
Since the TLS client certificate is self-signed, the entity terminating the TLS transport for API servers cannot do full certificate path validation. It can check some aspects of the certificate (like expire date), but other than that it just accepts the certificate blindly and presents a hash of the certificate it to the application server.
If a JWT contains a bobHok claim, the API server SHOULD verify that the TLS client certificate used for communications matches the claim.
API Client Processing
A BoB client that receives a JWT with a bobHok claim MUST use TLS client authentication when communicating with all BoB servers since the BoB server may require a correct channel binding when authenticating such JWTs.
Sequence Diagram
The following sequence diagram show the full authentication flow.
...