Repository navigation
2.3 Authentication
Authentication happens through the User Data Base (UDB) in the manner described below. The UDB has its own API endpoints, that tie in with the performance database API.
The API can be accessed via HTTPS only.
-
This API uses the OAuth2 standard for authentication. OAuth2 enables users to log on to a client (website, server) without sharing username and password with the client. When login info is correctly provided, the authentication server returns a ‘token’ to the user that can be used to access the targeted application or website.
-
OAuth2 is a comprehensive standard. The original standard is found through this link. Note that OAuth2 has been extended and complemented with other documents and standards such as OpenID and JWT. It is expected that best current practices will be followed by the maintainers of the PDB and UDB authorization servers.
-
The tokens will be sent in JWT format. Each token will be signed using a public private key pair owned by the UDB so that the PDB can easily check the authenticity and origin of the token. UDBs will be required to publish their public key on an open end point. The algorithm may be RSA (faster processing) or ECDSA (smaller token). The header of the token provides algorithm and type of token (JWT). The token also contains a body described below and the footer. The footer will contain the signature of the token that is used to determine the authenticity of the token. The body of the token contains some limited information called claims. These will include the following registered (standard) claims defined in the JWT standard:
o iss – the issuer (UDB authentication server url)
o sub – the subject (user) in the form of the user_id
o aud – the audience (an array of urls of the PDBs and UDB resource servers)
o exp – the token expiration time (in NumericDate format)
o iat – the token issue time (in NumericDate format) -
Future extensions of this standard may include JWT tokens with scope claims to further limit access of an APP to specific API endpoints and/or Resource Server resources.
-
APPs are expected to follow the Authorization Code Flow for Single Page Apps (SPA) and the Authorization Code with PKCE Flow for Native Apps. These flows are both required to be supported by UDB Authentication Servers. Optional flows that are not generally recommended at this moment include the Client Credential Flow (for example for microservers) and the Resource Owner Flow (for internal trusted environments). The Implicit Flow is explicitly disallowed under this standard.
-
Each request to the PDB and UDB Resource Servers will contain the JWT token in the authorization header. The content of the header is “Authorization: Bearer {token}”.
-
The Resource Server will check the signature of the JWT token and that the issuer (UDB Authentication Server) is in the Resource Server’s list of trusted UDB Authentication Servers. If it is a trusted UDB, then PDB Resource Servers will contact the UDB Resource Server to request the contracts and subsequently the access rights associated with the JWT token. After this, the rights (per contract - role, connection, being date, end date) may be cached together with the JWT signature and the token exp claim in the PDB Resource Server’s internal tables to reduce redundant calls to the UDB server and additional processing.
-
After the Resource Server has verified the token and determined the access rights associated with the token, it may respond to the API endpoint request as defined in this API specification. It must reject tokens that have passed their expiration date and subsequently remove these claims and roles from the cache.
-
The Stroomversnelling may create a central registry of trusted UDB and PDB servers to support server administrators in verifying new additions.