From 4b0bc346ac3ab2ac34259ecf33a5406e831b59fc Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Fri, 16 Aug 2024 11:04:43 -0600 Subject: [PATCH 01/10] Added tags to AuthenticationResource --- .../AuthenticationResource.java | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 35b6b1c59a7f..b2c4a2f20127 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -26,6 +26,16 @@ import com.liferay.portal.model.User; import com.liferay.portal.util.WebKeys; import com.liferay.util.LocaleUtil; +import io.swagger.v3.oas.annotations.tags.Tag; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; +import io.swagger.v3.oas.annotations.ExternalDocumentation; import java.io.Serializable; import java.util.Date; import java.util.List; @@ -52,8 +62,15 @@ * @version 3.7 * @since Jul 7, 2016 */ + + @SuppressWarnings("serial") @Path("/v1/authentication") +@Tag(name = "Authentication", + description = "Endpoints that perform operations related to user authentication", + externalDocs = @ExternalDocumentation(description = "Additional Authentication API information", + url = "https://www.dotcms.com/docs/latest/rest-api-authentication")) + public class AuthenticationResource implements Serializable { static final String USER = "user"; @@ -90,6 +107,9 @@ protected AuthenticationResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Operation(operationId = "postAuthentication", + summary = "Verifies user or application authentication", + description = "") public final Response authentication(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final AuthenticationForm authenticationForm) { From a1fd2e7612172cfd2fbf8c817b1750e5e641a31a Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Fri, 16 Aug 2024 12:08:45 -0600 Subject: [PATCH 02/10] Added @operation and ResponseEntityUserMapView class for v1/authenticate --- .../api/v1/authentication/AuthenticationResource.java | 10 +++++++++- .../v1/authentication/ResponseEntityUserMapView.java | 9 +++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index b2c4a2f20127..1e793940e43d 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -109,7 +109,15 @@ protected AuthenticationResource(final LoginServiceAPI loginService, @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) @Operation(operationId = "postAuthentication", summary = "Verifies user or application authentication", - description = "") + description = "Takes a user ID and checks if the user has permissions in the system.\n\n" + + "If the user is authenticated they will be prompted to log in and a session is created.\n\n" + + "Otherwise the system will return an 'authentication failed' message.\n\n", + tags = {"Authentication"}, + responses = { + @ApiResponse(responseCode = "200", description = "User authentication successful", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseEntityUserMapView.class))) + }) public final Response authentication(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final AuthenticationForm authenticationForm) { diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java new file mode 100644 index 000000000000..296f8c8e00e3 --- /dev/null +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserMapView.java @@ -0,0 +1,9 @@ +package com.dotcms.rest.api.v1.authentication; + +import com.dotcms.rest.ResponseEntityView; + +public class ResponseEntityUserMapView extends ResponseEntityView { + public ResponseEntityUserMapView(AuthenticationForm entity) { + super(entity); + } +} From f4756870f54bf404d360ef9010f5a2d3bfa13084 Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Mon, 19 Aug 2024 12:10:26 -0600 Subject: [PATCH 03/10] Completed annotations for v1/authenticate --- .../authentication/AuthenticationResource.java | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 1e793940e43d..1280b6f4ad32 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -116,10 +116,19 @@ protected AuthenticationResource(final LoginServiceAPI loginService, responses = { @ApiResponse(responseCode = "200", description = "User authentication successful", content = @Content(mediaType = "application/json", - schema = @Schema(implementation = ResponseEntityUserMapView.class))) - }) - public final Response authentication(@Context final HttpServletRequest request, + schema = @Schema(implementation = ResponseEntityUserMapView.class))), + @ApiResponse(responseCode = "401", description = "User not authenticated"), + @ApiResponse(responseCode = "403", description = "Forbidden request"), + @ApiResponse(responseCode = "500", description = "Unexpected error") + } + ) + public final Response authentication( + @Context final HttpServletRequest request, @Context final HttpServletResponse response, + @RequestBody(description = "This method takes a user's ID and verifies if they are authenticated. " + + "Authenticated users will asked to input their credentials.", + required = true, + content = @Content()) final AuthenticationForm authenticationForm) { Response res = null; @@ -196,6 +205,8 @@ public final Response authentication(@Context final HttpServletRequest request, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Operation(operationId = "getLogInUser", + summary = " ") @Path("logInUser") public final Response getLoginUser(@Context final HttpServletRequest request){ Response res = null; From b7c77effb248266dee9eeb0879fa36a5db3047e6 Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Mon, 19 Aug 2024 13:00:37 -0600 Subject: [PATCH 04/10] Added ResponseEnityUserView.java and @Operation for logInUser --- .../AuthenticationResource.java | 24 +++++++++++++++---- .../ResponseEntityUserView.java | 9 +++++++ 2 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 1280b6f4ad32..15fab42d2f3f 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -125,10 +125,13 @@ protected AuthenticationResource(final LoginServiceAPI loginService, public final Response authentication( @Context final HttpServletRequest request, @Context final HttpServletResponse response, - @RequestBody(description = "This method takes a user's ID and verifies if they are authenticated. " + - "Authenticated users will asked to input their credentials.", + @RequestBody(description = "POST body returns a JSON object containing a user's\n\n" + + "authentication status. Authenticated users will asked \n\n" + + "to input their credentials.\n\n", required = true, - content = @Content()) + content = @Content( + schema = @Schema(implementation = AuthenticationForm.class) + )) final AuthenticationForm authenticationForm) { Response res = null; @@ -206,7 +209,20 @@ public final Response authentication( @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) @Operation(operationId = "getLogInUser", - summary = " ") + summary = "Retrieves user data", + description = "Provides information about any users that are currently " + + "in a session. This retrieved data will be formatted into " + + "a JSON response body.", + tags = {"Authentication"}, + responses = { + @ApiResponse(responseCode = "200", description = "User data successfully collected", + content = @Content( + schema = @Schema(implementation = ResponseEntityUserView.class) + )), + @ApiResponse(responseCode = "400", description = "Bad request"), + @ApiResponse(responseCode = "401", description = "Unauthorized request"), + @ApiResponse(responseCode = "404", description = "User not found") + }) @Path("logInUser") public final Response getLoginUser(@Context final HttpServletRequest request){ Response res = null; diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java new file mode 100644 index 000000000000..bf967536a7b3 --- /dev/null +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/ResponseEntityUserView.java @@ -0,0 +1,9 @@ +package com.dotcms.rest.api.v1.authentication; + +import com.dotcms.rest.ResponseEntityView; + +public class ResponseEntityUserView extends ResponseEntityView { + public ResponseEntityUserView(AuthenticationForm entity) { + super(entity); + } +} From 243b688599ae3d3c9b9231e5541ff3905dc1d855 Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Tue, 20 Aug 2024 10:07:11 -0600 Subject: [PATCH 05/10] Completed @Operation for /authenticate/api-token --- dotCMS/javac.20240820_083616.args | 1 + .../CreateJsonWebTokenResource.java | 23 +++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 dotCMS/javac.20240820_083616.args diff --git a/dotCMS/javac.20240820_083616.args b/dotCMS/javac.20240820_083616.args new file mode 100644 index 000000000000..58297f80e66d --- /dev/null +++ b/dotCMS/javac.20240820_083616.args @@ -0,0 +1 @@ +@/tmp/org.codehaus.plexus.compiler.javac.JavacCompiler14439678467023706055arguments diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java index 29b67bc1cb94..f66957e91df8 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java @@ -32,6 +32,16 @@ import com.liferay.portal.model.User; import com.liferay.portal.util.PortalUtil; import com.liferay.util.LocaleUtil; +import io.swagger.v3.oas.annotations.tags.Tag; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; +import io.swagger.v3.oas.annotations.ExternalDocumentation; import org.elasticsearch.common.collect.Map; import org.glassfish.jersey.server.JSONP; @@ -98,6 +108,19 @@ protected CreateJsonWebTokenResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Operation(operationId = "postAuthenticateApiToken", + summary = "Creates a JSON web token", + description = "Takes a user ID and verifies that user is authenticated.\n\n" + + "If user has proper permissions, a JSON web token will be created.\n\n" + + "The system will also notify the user when their token is set to expire.\n\n", + tags = {"Authentication"}, + responses = { + @ApiResponse(responseCode = "200", description = "JSON web token created", + content = @Content(mediaType = "application/JSON", + schema = @Schema(implementation = ResponseEntityView.class) + )) + } + ) public final Response getApiToken(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final CreateTokenForm createTokenForm) { From dfc5582d6a5010c1914d4b64d7acd1a21359efcc Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Wed, 21 Aug 2024 15:43:46 -0600 Subject: [PATCH 06/10] Added markdown table to /authenticate and finished log in endpoint --- .../authentication/AuthenticationResource.java | 17 ++++++++++++----- .../CreateJsonWebTokenResource.java | 14 +------------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 15fab42d2f3f..900051793a9e 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -44,6 +44,7 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.http.HttpSession; +import javax.ws.rs.Consumes; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; @@ -107,10 +108,11 @@ protected AuthenticationResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) + @Consumes({MediaType.APPLICATION_JSON}) @Operation(operationId = "postAuthentication", summary = "Verifies user or application authentication", - description = "Takes a user ID and checks if the user has permissions in the system.\n\n" + - "If the user is authenticated they will be prompted to log in and a session is created.\n\n" + + description = "Takes a user's login ID and password and checks them against the user rolls.\n\n" + + "If the user is found and authenticated, a session is created.\n\n" + "Otherwise the system will return an 'authentication failed' message.\n\n", tags = {"Authentication"}, responses = { @@ -125,9 +127,14 @@ protected AuthenticationResource(final LoginServiceAPI loginService, public final Response authentication( @Context final HttpServletRequest request, @Context final HttpServletResponse response, - @RequestBody(description = "POST body returns a JSON object containing a user's\n\n" + - "authentication status. Authenticated users will asked \n\n" + - "to input their credentials.\n\n", + @RequestBody(description = "This method takes a user's credentials and language preferences to authenticate them.\n\n" + + "Requires a POST body consisting of a JSON object containing the following properties:\n\n" + + "| **Property** | **Value** | **Description** |\n" + + "|--------------|-----------|-----------------------------------------------|\n" + + "| `userId` | String | **Required.** ID of user attempting to log in |\n" + + "| `password` | String | User password |\n" + + "| `language` | String | Preferred language for user |\n" + + "| `country` | String | Country where user is located |\n", required = true, content = @Content( schema = @Schema(implementation = AuthenticationForm.class) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java index f66957e91df8..6db3efdb49d2 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java @@ -108,19 +108,7 @@ protected CreateJsonWebTokenResource(final LoginServiceAPI loginService, @JSONP @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) - @Operation(operationId = "postAuthenticateApiToken", - summary = "Creates a JSON web token", - description = "Takes a user ID and verifies that user is authenticated.\n\n" + - "If user has proper permissions, a JSON web token will be created.\n\n" + - "The system will also notify the user when their token is set to expire.\n\n", - tags = {"Authentication"}, - responses = { - @ApiResponse(responseCode = "200", description = "JSON web token created", - content = @Content(mediaType = "application/JSON", - schema = @Schema(implementation = ResponseEntityView.class) - )) - } - ) + @Deprecated public final Response getApiToken(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final CreateTokenForm createTokenForm) { From 4fe4bfdd3f1f68b47987c251d06c96bed3e8d61e Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Thu, 22 Aug 2024 09:36:04 -0600 Subject: [PATCH 07/10] Added @Hidden to /api-token endpoint --- .../rest/api/v1/authentication/CreateJsonWebTokenResource.java | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java index 6db3efdb49d2..d271f870c560 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java @@ -32,6 +32,7 @@ import com.liferay.portal.model.User; import com.liferay.portal.util.PortalUtil; import com.liferay.util.LocaleUtil; +import io.swagger.v3.oas.annotations.Hidden; import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; @@ -109,6 +110,7 @@ protected CreateJsonWebTokenResource(final LoginServiceAPI loginService, @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) @Deprecated + @Hidden public final Response getApiToken(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final CreateTokenForm createTokenForm) { From f7ed8295ce4bab37fc6f4fa4a2f441474fce3ca8 Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Fri, 23 Aug 2024 12:00:00 -0600 Subject: [PATCH 08/10] Format change --- .../rest/api/v1/authentication/AuthenticationResource.java | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java index 900051793a9e..2a25bc99df80 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/AuthenticationResource.java @@ -217,9 +217,8 @@ public final Response authentication( @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) @Operation(operationId = "getLogInUser", summary = "Retrieves user data", - description = "Provides information about any users that are currently " + - "in a session. This retrieved data will be formatted into " + - "a JSON response body.", + description = "Provides information about any users that are currently in a session.\n\n" + + "This retrieved data will be formatted into a JSON response body.\n\n", tags = {"Authentication"}, responses = { @ApiResponse(responseCode = "200", description = "User data successfully collected", From 57517c1808ac0fcf7010d9045d5935e89ac55356 Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Fri, 23 Aug 2024 12:22:48 -0600 Subject: [PATCH 09/10] Unecessary file removal --- dotCMS/javac.20240820_083616.args | 1 - 1 file changed, 1 deletion(-) delete mode 100644 dotCMS/javac.20240820_083616.args diff --git a/dotCMS/javac.20240820_083616.args b/dotCMS/javac.20240820_083616.args deleted file mode 100644 index 58297f80e66d..000000000000 --- a/dotCMS/javac.20240820_083616.args +++ /dev/null @@ -1 +0,0 @@ -@/tmp/org.codehaus.plexus.compiler.javac.JavacCompiler14439678467023706055arguments From a45d7793ef1ff4142f97207f74962ef69a3088fb Mon Sep 17 00:00:00 2001 From: Gavriella Santiago Date: Fri, 23 Aug 2024 14:26:16 -0600 Subject: [PATCH 10/10] Comment adde to @Hidden --- .../rest/api/v1/authentication/CreateJsonWebTokenResource.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java index d271f870c560..bc07561ac923 100644 --- a/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java +++ b/dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/CreateJsonWebTokenResource.java @@ -110,7 +110,7 @@ protected CreateJsonWebTokenResource(final LoginServiceAPI loginService, @NoCache @Produces({MediaType.APPLICATION_JSON, "application/javascript"}) @Deprecated - @Hidden + @Hidden //not shown in API playground public final Response getApiToken(@Context final HttpServletRequest request, @Context final HttpServletResponse response, final CreateTokenForm createTokenForm) {