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.

Issuer

From RFC 7519:

The "iss" (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The "iss" value is a case-sensitive string containing a StringOrURI value.

In BoB, use of this claim is MANDATORY and it MUST be set to the PID (string) of the token issuer.

"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.

In BoB, use of this claim is MANDATORY and it MUST be set to the entity ID (string) of the subject requesting the JWT. The entity ID must be unique within each participant (PID).

"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.

In BoB, use of this claim is MANDATORY.

"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.

In BoB, use of this claim is OPTIONAL.

"nbf": 108932429

Issued At

From RFC 7519:

The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a number containing a NumericDate value.

In BoB, use of this claim is OPTIONAL.

"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.

"bobAuthZ": "val"

Holder of Key

The "bobHok" (holder of key) claim identifies the certificate used when acquiring the JWT. Its value MUST be a string containing the SHA1 hash of the TLS client certificate. Use of this claim is OPTIONAL.

"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 should just accept the certificate and present a hash of the certificate to the application server. It should not check expiration date. It is recommended to use a very long expiration date to avoid problems when technical limitations make it hard to disable the expiration date check.

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.