diff --git a/docs/example-data.json b/docs/example-data.json index 977fc444a..e7073a46f 100644 --- a/docs/example-data.json +++ b/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": "", diff --git a/docs/interfaces/auth-service.txt b/docs/interfaces/auth-service.txt index 8d78ffac2..e6a852b23 100644 --- a/docs/interfaces/auth-service.txt +++ b/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 { + // 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; /** +* 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; /** +* 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; /** -* 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 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 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 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[]; \ No newline at end of file +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}>;