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

Update auth-service's interface
This commit is contained in:
Finn Stutzenstein 2020-10-13 08:26:15 +02:00 committed by GitHub
commit eded14f066
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 80 additions and 31 deletions

View File

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

View File

@ -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 { Interface Token {
payload: { payload: {
// The lifetime of the Token. The date in unix seconds of the expiration. // The lifetime of the Token. The date in unix seconds of the expiration.
@ -13,14 +17,43 @@ Interface Token {
Interface Cookie { Interface Cookie {
// The id for the session corresponding to the client, who has signed in. // The id for the session corresponding to the client, who has signed in.
sessionId: string, sessionId: string,
// A signature created from the server. // The lifetime of a cookie. Date of expiration in unix seconds.
signature: string 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. * The credentials for login/authentication are not valid.
@ -28,6 +61,8 @@ Exception NoPermissions
Exception InvalidCredentials Exception InvalidCredentials
/** /**
* POST to /system/auth/login
*
* The client can login with its credentials for authentication. * 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. * 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 * @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 * 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. * 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 * @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 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. * 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 * @throws InvalidCredentials
*/ */
WhoAmI(cookie: Cookie): Token; api/authenticate (ticket: Ticket): Response<LoginInformation>;
/** /**
* Function to kill one specific session by its id. * DELETE to /system/auth/api/clear-session-by-id
* *
* An exception is thrown, if the client has not the necessary permissions to make this action. * Function to sign out one specific client from a user by its corresponding session-id.
* Also, if there is no session with the given id, an exception is thrown.
*
* @throws NoPermissions: Only users themselves can clear their own session and (super-) admins
* can do this, too.
*/ */
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. * Function to kill all current opened sessions from one user except the one, which is requesting.
*
* @throws NoPermissions: Only (super-) admins has the necessary permissions to logout and clear
* other user's session.
*/ */
ClearAllSessionsExceptThemselves (token: Token, cookie: Cookie): void publishes LogoutSessionEvent; api/clear-all-sessions-except-themselves (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;
Event LogoutSessionEvent on topic Logout {
sessionId: string;
}
/** /**
* POST to /system/auth/api/logout
*
* The service deletes the session depending on the given Token. * The service deletes the session depending on the given Token.
* *
* @throws InvalidCredentials * @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. * Returns all currently active sessions.
* *
* @throws NoPermissions: The users can only see their own session. Only (super-) admins can see sessions * @returns an array containing currently active sessions.
* of other users.
*/ */
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}>;