Merge pull request #5496 from GabrielInTheWorld/update-auth-service-interface

Update auth-service's interface

docs/example-data.json

@@ -22,7 +22,7 @@
         "last_name": "Administrator",
         "is_active": true,
         "is_committee": false,
-        "password": "1422e767c5e08bb7196844025a0f98e1x61Ey612Kl2gpFL56FT9weDnpSo4AV8j8+qx2AuTHdRyY036xxzTTrw10Wq3+4qQyB+XURPWx1ONxp3Y3pB37A==",
+        "password": "316af7b2ddc20ead599c38541fbe87e9a9e4e960d4017d6e59de188b41b2758flD5BVZAZ8jLy4nYW9iomHcnkXWkfk3PgBjeiTSxjGG7+fBjMBxsaS1vIiAMxYh+K38l0gDW4wcP+i8tgoc4UBg==",
         "default_password": "admin",
         "about_me": "",
         "gender": "",
@@ -74,7 +74,7 @@
         "last_name": "",
         "is_active": true,
         "is_committee": false,
-        "password": "7f0d953dadfddb2005da4c04037abf61H0D8ktokFpR1CXnubPWC8tXX0o4YM13gWrxU0FYOD1MChgxlK/CNVgJSql50IQVG82n7u86MEs/HlXsmUv6adQ==",
+        "password": "316af7b2ddc20ead599c38541fbe87e9a9e4e960d4017d6e59de188b41b2758fDB3tv5HcCtPRREt7bPGqerTf1AbmoKXt/fVFkLY4znDRh2Yy0m3ZjXD0nHI8oa6KrGlHH/cvysfvf8i2fWIzmw==",
         "default_password": "a",
         "about_me": "",
         "gender": "",
@@ -120,7 +120,7 @@
         "last_name": "",
         "is_active": true,
         "is_committee": false,
-        "password": "a7ba62036711bbd11163661547947f23Umd2iCLuYk1I/OFexcp5y9YCy39MIVelFlVpkfIu+Me173sY0f9BxZNw77CFhlHUSpNsEbexRMSP4E3zxqPo2g==",
+        "password": "316af7b2ddc20ead599c38541fbe87e9a9e4e960d4017d6e59de188b41b2758fIxDxvpkn6dDLRxT9DxJhZ/f04AL2oK2beICRFobSw53CI93U+dfN+w+NaL7BvrcR4JWuMj9NkH4dVjnnI0YTkg==",
         "default_password": "jKwSLGCk",
         "about_me": "",
         "gender": "",

docs/interfaces/auth-service.txt

@@ -1,3 +1,7 @@
+// Description of the authentication-service
+// It is listening on port '9004'
+// Routes with a prefix 'api' are protected routes, that can only accessed with a valid ticket.
+
 Interface Token {
     payload: {
         // The lifetime of the Token. The date in unix seconds of the expiration.
@@ -13,14 +17,43 @@ Interface Token {
 Interface Cookie {
     // The id for the session corresponding to the client, who has signed in.
     sessionId: string,
-    // A signature created from the server.
-    signature: string
+    // The lifetime of a cookie. Date of expiration in unix seconds.
+    exp: number,
+    // Date of creation of a token in unix seconds.
+    iat: number
+}
+
+// The properties of this interface have to be passed as HTTP-headers in a request. 
+Interface Ticket {
+    authentication: string,
+    cookies: {
+        refreshId: string,
+        [name: string]: string
+    }
 }
 
 /**
-* The client has not the necessary permissions for the requesting action.
+* Describes an http-response, which is sent back to any requesting service.
 */
-Exception NoPermissions
+Interface Response <T> {
+    // Optional headers, which are set in an http-response
+    httpHeaders: {
+        // Authentication is passed, if a new access-token is returned.
+        authentication?: string,
+        // Cookies, like one containing 'refreshId=(Cookie as string)', if a user signs in, are passed. 
+        // Lifetime of one cookie is about 24h. 
+        // Flags for the cookies are: HttpOnly, Secure
+        cookies: {
+            [name: string]: string
+        }
+    }
+    // This determines if a request was successful.
+    success: boolean,
+    // This sends back a describing message. For example, the reason of a failured request.
+    message: string,
+    // Optional data, which is appended, if a request was successful.
+    data?: T
+}
 
 /**
 * The credentials for login/authentication are not valid.
@@ -28,6 +61,8 @@ Exception NoPermissions
 Exception InvalidCredentials
 
 /**
+* POST to /system/auth/login
+*
 * The client can login with its credentials for authentication.
 * If they are correct, the service answers with a signed Token and sets a cookie, containing the sessionId of the client.
 *
@@ -35,9 +70,11 @@ Exception InvalidCredentials
 *
 * @throws InvalidCredentials
 */
-Login (username: string, password: string): (Token, Cookie);
+login (username: string, password: string): Response<void>;
 
 /**
+* POST to /system/auth/who-am-i
+*
 * An example for any protected route. If the client requests protected resources, it has to 
 * send the signed Token and the cookie, it receives from the service at login, to the server.
 *
@@ -49,9 +86,11 @@ Login (username: string, password: string): (Token, Cookie);
 *
 * @throws InvalidCredentials
 */
-Authenticate (token: Token, cookie: Cookie): {userId: number; sessionId: string;};
+who-am-i (ticket: Ticket): Response<void>;
 
 /**
+* POST to /internal/auth/api/authenticate
+*
 * A request to get knowledge about themselves. This information is contained in the payload of 
 * a Token. So, this function handles the refreshing of a Token.
 *
@@ -61,44 +100,54 @@ Authenticate (token: Token, cookie: Cookie): {userId: number; sessionId: string;
 *
 * @throws InvalidCredentials
 */
-WhoAmI(cookie: Cookie): Token;
+api/authenticate (ticket: Ticket): Response<LoginInformation>;
 
 /**
-* Function to kill one specific session by its id.
-* 
-* An exception is thrown, if the client has not the necessary permissions to make this action.
-* Also, if there is no session with the given id, an exception is thrown.
+* DELETE to /system/auth/api/clear-session-by-id
 *
-* @throws NoPermissions: Only users themselves can clear their own session and (super-) admins
-* can do this, too.
+* Function to sign out one specific client from a user by its corresponding session-id.
 */
-ClearSessionById (sessionId: string, cookie: Cookie, token: Token): void publishes LogoutSessionEvent;
+api/clear-session-by-id (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;
 
 /**
-* Function to kill all current opened sessions except the one, which is requesting.
+* POST to /system/auth/api/clear-all-session-except-themselves
 *
-* An exception is thrown, if the client has not the necessary permissions to make this action.
-* 
-* @throws NoPermissions: Only (super-) admins has the necessary permissions to logout and clear
-* other user's session.
+* Function to kill all current opened sessions from one user except the one, which is requesting.
 */ 
-ClearAllSessionsExceptThemselves (token: Token, cookie: Cookie): void publishes LogoutSessionEvent;
-
-Event LogoutSessionEvent on topic Logout {
-    sessionId: string;
-}
+api/clear-all-sessions-except-themselves (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;
 
 /**
+* POST to /system/auth/api/logout
+*
 * The service deletes the session depending on the given Token.
 *
 * @throws InvalidCredentials
 */
-Logout (token: Token, cookie: Cookie): void publishes LogoutSessionEvent;
+api/logout (ticket: Ticket): Response<void> publishes LogoutSessionEvent;
 
 /**
+* GET to system/auth/api/list-sessions
+*
 * Returns all currently active sessions.
 *
-* @throws NoPermissions: The users can only see their own session. Only (super-) admins can see sessions
-* of other users.
+* @returns an array containing currently active sessions.
 */
-ListSessions (token: Token, cookie: Cookie): string[];
+api/list-sessions (ticket: Ticket): Response<{sessions: string[]}>;
+
+/**
+* POST to /internal/auth/hash
+*
+* Hashes a given value. A random salt (64bit) is generated and added to the hashed value.
+*
+* @returns the hashed value. The hashed value is structured as follows: [salt + hash].
+*/
+hash (toHash: string): Response<{hash: string}>;
+
+/**
+* POST to /internal/auth/is-equals
+*
+* Compares a given value with an given hash.
+*
+* @returns a boolean, if the hashed value of the given value is equals to the passed hash.
+*/
+is-equals (toHash: string, toCompare: string): Response<{isEquals: boolean}>;