providers
« Previous section Next section »
UCloud Developer Guide / Core / Users / Authentication / Provider Authentication
Provider Authentication
UCloud/Core and Providers authenticate each-other using short-lived JWTs and long-lived opaque refresh-tokens.
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 |
---|---|---|
| A short-lived JWT token for authenticating regular requests | |
| Opaque | An opaque token, with no explicit expiration, used for requesting new |
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
.
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:
The accessToken
is passed similarly:
Internals of accessToken
s
accessToken
sIn 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.
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
accessToken
sAs a provider, you must take the following steps to verify the authenticity of an accessToken
:
Verify that the
accessToken
is signed with theRS256
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 toSERVICE
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.
Table of Contents
Example: A Provider authenticating with UCloud/Core
Frequency of use | Common |
---|---|
Pre-conditions |
|
Actors |
|
Remote Procedure Calls
retrievePublicKey
retrievePublicKey
Request | Response | Error |
---|---|---|
claim
claim
Request | Response | Error |
---|---|---|
generateKeyPair
generateKeyPair
Generates an RSA key pair useful for JWT signatures
Request | Response | Error |
---|---|---|
Generates an RSA key pair and returns it to the client. The key pair is not stored or registered in any way by the authentication service.
refresh
refresh
Request | Response | Error |
---|---|---|
refreshAsOrchestrator
refreshAsOrchestrator
Signs an access-token to be used by a UCloud service
Request | Response | Error |
---|---|---|
This RPC signs an access-token which will be used by authorized UCloud services to act as an orchestrator of resources.
register
register
Request | Response | Error |
---|---|---|
renew
renew
Request | Response | Error |
---|---|---|
Data Models
PublicKeyAndRefreshToken
PublicKeyAndRefreshToken
RefreshToken
RefreshToken
AuthProvidersRefreshAsProviderRequestItem
AuthProvidersRefreshAsProviderRequestItem
AuthProvidersRegisterRequestItem
AuthProvidersRegisterRequestItem
AuthProvidersGenerateKeyPairResponse
AuthProvidersGenerateKeyPairResponse
AuthProvidersRegisterResponseItem
AuthProvidersRegisterResponseItem
AuthProvidersRetrievePublicKeyResponse
AuthProvidersRetrievePublicKeyResponse
Last updated