132 lines
4.1 KiB
Plaintext
132 lines
4.1 KiB
Plaintext
// Description of the authentication-service
|
|
// It is listening on port '9004'
|
|
// Routes with a prefix 'secure' are protected routes, that can only accessed with a valid ticket.
|
|
// That are routes, that call internally 'authenticate'
|
|
|
|
|
|
// 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
|
|
}
|
|
}
|
|
|
|
// This describes, which information is received by requesting `secure/authenticate`.
|
|
Interface LoginInformation {
|
|
userId: number;
|
|
sessionId: string;
|
|
}
|
|
|
|
/**
|
|
* Describes an http-response, which is sent back to any requesting service.
|
|
*/
|
|
Interface Response <T> {
|
|
set-authentication-header: string // If an old access-token is expired and refreshed, it is set as authentication-header.
|
|
// 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.
|
|
*/
|
|
Exception InvalidCredentials {
|
|
success: false,
|
|
message: string
|
|
}
|
|
|
|
/**
|
|
* POST to /system/auth/login
|
|
*
|
|
* A user 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 aren't correct, the service throws an error.
|
|
*
|
|
* @throws InvalidCredentials
|
|
*/
|
|
login (username: string, password: string): Response<void>;
|
|
|
|
/**
|
|
* POST to /internal/auth/authenticate
|
|
*
|
|
* This will be a library to act as part of the auth-service. The other services have not to
|
|
* request the auth-service for authentication. Instead, they use this library-function in their own
|
|
* and receive knowledge about authentication without request.
|
|
*
|
|
* Throws an exception, if the token is not valid. E.g. if the signature is not valid.
|
|
*
|
|
* @throws InvalidCredentials
|
|
*/
|
|
authenticate (ticket: Ticket): Response<LoginInformation>;
|
|
|
|
/**
|
|
* POST to /system/auth/who-am-i
|
|
*
|
|
* 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.
|
|
* Expects a jwt as string in a cookie (called 'refreshId').
|
|
*
|
|
* Sends back a new Token (passed as http-header).
|
|
*
|
|
* Throws an exception, if the cookie is empty, the transmitted sessionId is wrong or the signature is wrong.
|
|
*
|
|
* @throws InvalidCredentials
|
|
*/
|
|
who-am-i (refreshId: string): Response<LoginInformation>;
|
|
|
|
/**
|
|
* POST to /system/auth/secure/clear-session-by-id
|
|
*
|
|
* Function to sign out one specific client from a user by its corresponding session-id.
|
|
*/
|
|
secure/clear-session-by-id (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;
|
|
|
|
/**
|
|
* POST to /system/auth/secure/clear-all-session-except-themselves
|
|
*
|
|
* Function to kill all current opened sessions from one user except the one, which is requesting.
|
|
*/
|
|
secure/clear-all-sessions-except-themselves (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;
|
|
|
|
/**
|
|
* POST to /system/auth/secure/logout
|
|
*
|
|
* The service deletes the session depending on the given Token.
|
|
*
|
|
* @throws InvalidCredentials
|
|
*/
|
|
secure/logout (ticket: Ticket): Response<void> publishes LogoutSessionEvent;
|
|
|
|
/**
|
|
* GET to system/auth/secure/list-sessions
|
|
*
|
|
* Returns all currently active sessions.
|
|
*
|
|
* @returns an array containing currently active sessions.
|
|
*/
|
|
secure/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}>;
|