Communication
All communication between UCloud and a provider is done via an HTTP(S) API, certain optional endpoints use a WebSocket
API. Note that the WebSocket protocol is an extension of HTTP, as a result the WebSocket API shares the same security
aspects as the HTTP API.
TLS is strictly required for all providers running in a production environment. The provider must use a valid
certificate, which hasn’t expired and signed by a commonly recognized Certificate Authority (CA). TLS for HTTPS
connections are handled internally in UCloud by OpenJDK11+. Notably, this means that TLSv1.3 is supported. We encourage
providers to follow best practices. For inspiration, Mozilla hosts an
online SSL configuration generator.
Additionally, this document from SSL
Labs can provide a good starting point.
Providers should treat UCloud similarly. An integration module should ensure that all certificates served by UCloud are
valid and signed by a commonly recognized CA.
For local development purposes only UCloud can communicate with a local provider using HTTP. It is not possible
to configure UCloud to use self-signed certificates, and as a result it is not possible to run a local provider with a
self-signed certificate + TLS. This design choice has been made to simplify the code and avoid poorly configured UCloud
deployments.
Authentication and Authorization
UCloud and the provider authenticates and authorizes all ingoing requests. Short-lived
JSON Web Tokens (JWT) protect these requests.
Token |
Type |
Description |
accessToken |
JWT |
A short-lived JWT token for authenticating regular requests |
refreshToken |
Opaque |
An opaque token, with no explicit expiration, used for requesting new accessToken s |
Table: The two token types used in UCloud ↔ Provider authentication
Because JWTs are short-lived, every provider must renew their JWT periodically. Providers do this by using an opaque
token called the refreshToken
. The diagram below shows how a provider can use their refreshToken
to generate a new
accessToken
.
![](../../../../../_images/access_token_request.svg)
Figure: A provider requesting a new accessToken
using their refreshToken
All calls use
the HTTP bearer authentication scheme
. As a result the refreshToken
will be passed in the Authorization
header like this:
HTTP/1.1 POST https://cloud.sdu.dk/auth/refresh
Authorization: Bearer $refreshToken
The accessToken
is passed similarly:
HTTP/1.1 POST https://cloud.sdu.dk/some/call
Authorization: Bearer $accessToken
Internals of accessToken
s
In this section we describe the internals of the accessToken
and how to verify an accessToken
from UCloud. It is
important that all providers authenticate every request they receive.
The payload of an accessToken
is follows the same schema for both UCloud and providers.
{
// Token properties
"iat": 1234,
"exp": 5678,
"iss": "cloud.sdu.dk",
// Authorization properties
"role": "<ROLE>", // "SERVICE" if the token authenticates UCloud. "PROVIDER" if the token authenticates a provider.
// User metadata
"sub": "<USERNAME>" // A unique identifier for the provider or "_UCloud" if the token authenticates UCloud.
}
All JWTs signed by UCloud will use the RS256
algorithm, internally this uses RSASSA-PKCS1-v1_5
with SHA-256
used
for the signature. UCloud uses a unique private & public keypair for every provider. The provider receives UCloud’s
public key when the refreshToken
of the provider is issued. UCloud will generate a new keypair if the provider’s
refreshToken
is revoked.
Verifying accessToken
s
As a provider, you must take the following steps to verify the authenticity of an accessToken
:
Verify that the accessToken
is signed with the RS256
algorithm (alg
field of the JWT header)
Verify that the sub
field is equal to "_UCloud"
(Note the ‘_’ prefix)
Verify that the iat
(issued at) field is valid by comparing to the current time
(See RFC7519 Section 4.1.6)
Verify that the exp
(expires at) field is valid by comparing to the current time
(See RFC7519 Section 4.1.4)
Verify that the iss
(issuer) field is equal to "cloud.sdu.dk"
Verify that the role
field is equal to SERVICE
It is absolutely critical that JWT verification is configured correctly. For example, some JWT verifiers are known for
having too relaxed defaults, which in the worst case will skip all verification. It is important that the verifier is
configured to only accept the parameters mentioned above.