Commit 4a910771 authored by Jacob Priddy's avatar Jacob Priddy 👌

Authentication api docs

parent f06aeb3f
......@@ -13,6 +13,12 @@ use Source\UseCases\Users\Authenticate\APIPresenter;
use Source\UseCases\Users\Authenticate\AuthenticateUseCase;
use Source\UseCases\Users\Authenticate\UserCreationException;
/**
* @group Authentication
*
* This set of routes deals with authentication with the application through SAML and application login.
*/
class AuthController extends ApiController
{
protected CookieJar $cookieJar;
......@@ -30,15 +36,31 @@ class AuthController extends ApiController
}
/**
* Login request to application
*
* This endpoint returns a token that can be used in other endpoints as well as setting a cookie.
* One does not need to make a request to this if they have a valid token.
*
* @bodyParam email string required The email of the login user. Example: sithL0rd@senate.com
* @bodyParam password string required The password of the user to login as. Example: I am the senate
*
* @response 422 {"message":"The given data was invalid.","errors":{"email":["The email field is required."],"password":["The password field is required."]}}
*
* @param AuthenticateUseCase $authenticateUseCase
* @return JsonResponse
* @throws AuthenticationException
* @throws EntityNotFoundException
* @throws \Illuminate\Validation\ValidationException
*/
public function login(AuthenticateUseCase $authenticateUseCase): JsonResponse
{
$presenter = new APIPresenter();
$this->validate($this->request, [
'email' => 'required|string|email',
'password' => 'required|string',
]);
$authenticateUseCase->attempt($presenter, $this->request->all());
return $this->respondWithData($presenter->getViewModel())->withCookie(
......@@ -51,6 +73,10 @@ class AuthController extends ApiController
}
/**
* Start a saml login request
*
* This route redirects the user to the running SAML authentication instance to start authentication with SAML
*
* @param \Source\UseCases\Users\Authenticate\AuthenticateUseCase $authenticateUseCase
* @return \Illuminate\Http\RedirectResponse
*/
......@@ -60,9 +86,14 @@ class AuthController extends ApiController
}
/**
* Handle SAML login
*
* This API is only meant to be used by SAML after a login.
*
* @param AuthenticateUseCase $authenticateUseCase
* @return mixed
* @throws EntityNotFoundException
* @throws \Source\Exceptions\EntityExistsException
*/
public function handle(AuthenticateUseCase $authenticateUseCase)
{
......@@ -86,6 +117,10 @@ class AuthController extends ApiController
}
/**
* Log out
*
* This endpoint logs out of saml and expires the associated api/login token and cookie.
*
* @param AuthenticateUseCase $authenticateUseCase
* @return RedirectResponse
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment