Skip to content

Commit b68f872

Browse files
spboltonspbolton
committed
Batch 1 resources
1 parent 2bbeab4 commit b68f872

File tree

17 files changed

+2238
-436
lines changed

17 files changed

+2238
-436
lines changed

‎dotCMS/src/main/java/com/dotcms/auth/providers/saml/v1/DotSamlResource.java‎

Lines changed: 106 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import com.dotcms.filters.interceptor.saml.SamlWebUtils;
44
import com.dotcms.rest.WebResource;
55
import com.dotcms.rest.annotation.NoCache;
6+
import com.dotcms.rest.annotation.SwaggerCompliant;
67
import com.dotcms.saml.Attributes;
78
import com.dotcms.saml.DotSamlConstants;
89
import com.dotcms.saml.DotSamlException;
@@ -21,6 +22,12 @@
2122
import com.dotmarketing.util.WebKeys;
2223
import com.google.common.annotations.VisibleForTesting;
2324
import com.liferay.portal.model.User;
25+
import io.swagger.v3.oas.annotations.Operation;
26+
import io.swagger.v3.oas.annotations.Parameter;
27+
import io.swagger.v3.oas.annotations.media.Content;
28+
import io.swagger.v3.oas.annotations.parameters.RequestBody;
29+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
30+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
2431
import io.swagger.v3.oas.annotations.tags.Tag;
2532
import org.glassfish.jersey.server.JSONP;
2633

@@ -49,6 +56,7 @@
4956
* - metadata renders the XML metadata.
5057
* @author jsanca
5158
*/
59+
@SwaggerCompliant(value = "Core authentication and user management APIs", batch = 1)
5260
@Tag(name = "SAML Authentication")
5361
@Path("/v1/dotsaml")
5462
public class DotSamlResource implements Serializable {
@@ -98,12 +106,29 @@ protected DotSamlResource(final SamlConfigurationService samlConfigura
98106
* @param httpServletResponse {@link HttpServletResponse}
99107
* @return Response
100108
*/
109+
@Operation(
110+
summary = "Initiate SAML login",
111+
description = "Initiates a SAML authentication request by redirecting the user to the Identity Provider (IDP) login screen. Requires IDP metadata to determine the SSO login endpoint."
112+
)
113+
@ApiResponses(value = {
114+
@ApiResponse(responseCode = "200",
115+
description = "SAML authentication request initiated successfully (no body)"),
116+
@ApiResponse(responseCode = "400",
117+
description = "Bad request - invalid IDP configuration ID",
118+
content = @Content(mediaType = "application/json")),
119+
@ApiResponse(responseCode = "404",
120+
description = "IDP configuration not found or not enabled",
121+
content = @Content(mediaType = "application/json")),
122+
@ApiResponse(responseCode = "500",
123+
description = "Internal server error during SAML authentication initiation",
124+
content = @Content(mediaType = "application/json"))
125+
})
101126
@GET
102127
@Path( "/login/{idpConfigId}" )
103128
@JSONP
104129
@NoCache
105-
@Produces( { MediaType.APPLICATION_JSON, "application/javascript" } )
106-
public Response doLogin(@PathParam( "idpConfigId" ) final String idpConfigId,
130+
@Produces( { MediaType.APPLICATION_JSON } )
131+
public Response doLogin(@Parameter(description = "Identity Provider configuration ID (typically host ID)", required = true) @PathParam( "idpConfigId" ) final String idpConfigId,
107132
@Context final HttpServletRequest httpServletRequest,
108133
@Context final HttpServletResponse httpServletResponse) {
109134

@@ -148,12 +173,36 @@ public Response doLogin(@PathParam( "idpConfigId" ) final String idpConfigId,
148173
* @param httpServletResponse {@link HttpServletResponse}
149174
* @throws IOException
150175
*/
176+
@Operation(
177+
summary = "Process SAML login callback",
178+
description = "Handles the callback from the Identity Provider after successful authentication. Extracts user information from the SAML assertion and creates/logs in the user to dotCMS.",
179+
requestBody = @RequestBody(description = "SAML assertion data from Identity Provider", required = true,
180+
content = {@Content(mediaType = "application/xml"),
181+
@Content(mediaType = "application/x-www-form-urlencoded")})
182+
)
183+
@ApiResponses(value = {
184+
@ApiResponse(responseCode = "200",
185+
description = "SAML login processed successfully - user logged in",
186+
content = @Content(mediaType = "text/html")),
187+
@ApiResponse(responseCode = "400",
188+
description = "Bad request - invalid SAML assertion or missing data",
189+
content = @Content(mediaType = "text/html")),
190+
@ApiResponse(responseCode = "401",
191+
description = "Unauthorized - SAML assertion validation failed",
192+
content = @Content(mediaType = "text/html")),
193+
@ApiResponse(responseCode = "404",
194+
description = "IDP configuration not found or not enabled",
195+
content = @Content(mediaType = "text/html")),
196+
@ApiResponse(responseCode = "500",
197+
description = "Internal server error during SAML login processing",
198+
content = @Content(mediaType = "text/html"))
199+
})
151200
@POST
152201
@Path("/login/{idpConfigId}")
153202
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_FORM_URLENCODED})
154203
@Produces( { MediaType.APPLICATION_XML, "text/html" } )
155204
@NoCache
156-
public void processLogin(@PathParam("idpConfigId") final String idpConfigId,
205+
public void processLogin(@Parameter(description = "Identity Provider configuration ID (typically host ID)", required = true) @PathParam("idpConfigId") final String idpConfigId,
157206
@Context final HttpServletRequest httpServletRequest,
158207
@Context final HttpServletResponse httpServletResponse) throws IOException {
159208

@@ -272,12 +321,33 @@ public void processLogin(@PathParam("idpConfigId") final String idpConfigId,
272321
* @param httpServletResponse {@link HttpServletResponse}
273322
* @throws IOException
274323
*/
324+
@Operation(
325+
summary = "Get SAML metadata",
326+
description = "Renders the XML metadata for the SAML Service Provider configuration. This endpoint is only accessible by administrators and provides the metadata required for IDP configuration."
327+
)
328+
@ApiResponses(value = {
329+
@ApiResponse(responseCode = "200",
330+
description = "SAML metadata rendered successfully",
331+
content = @Content(mediaType = "application/xml")),
332+
@ApiResponse(responseCode = "401",
333+
description = "Unauthorized - admin access required",
334+
content = @Content(mediaType = "application/xml")),
335+
@ApiResponse(responseCode = "403",
336+
description = "Forbidden - user is not an administrator",
337+
content = @Content(mediaType = "application/xml")),
338+
@ApiResponse(responseCode = "404",
339+
description = "IDP configuration not found or not enabled",
340+
content = @Content(mediaType = "application/xml")),
341+
@ApiResponse(responseCode = "500",
342+
description = "Internal server error rendering metadata",
343+
content = @Content(mediaType = "application/xml"))
344+
})
275345
@GET
276346
@Path( "/metadata/{idpConfigId}" )
277347
@JSONP
278348
@NoCache
279349
@Produces( { MediaType.APPLICATION_XML, "application/xml" } )
280-
public void metadata( @PathParam( "idpConfigId" ) final String idpConfigId,
350+
public void metadata( @Parameter(description = "Identity Provider configuration ID (typically host ID)", required = true) @PathParam( "idpConfigId" ) final String idpConfigId,
281351
@Context final HttpServletRequest httpServletRequest,
282352
@Context final HttpServletResponse httpServletResponse ) throws IOException {
283353

@@ -313,12 +383,27 @@ public void metadata( @PathParam( "idpConfigId" ) final String idpConfigId,
313383
throw new DoesNotExistException(message);
314384
}
315385

386+
@Operation(
387+
summary = "Process SAML logout (POST)",
388+
description = "Processes a SAML logout request via POST method. Handles logout callbacks from the Identity Provider and redirects to the configured logout endpoint."
389+
)
390+
@ApiResponses(value = {
391+
@ApiResponse(responseCode = "200",
392+
description = "SAML logout processed successfully",
393+
content = @Content(mediaType = "text/html")),
394+
@ApiResponse(responseCode = "404",
395+
description = "IDP configuration not found or not enabled",
396+
content = @Content(mediaType = "text/html")),
397+
@ApiResponse(responseCode = "500",
398+
description = "Internal server error during logout processing",
399+
content = @Content(mediaType = "text/html"))
400+
})
316401
@POST
317402
@Path("/logout/{idpConfigId}")
318403
@NoCache
319404
@Produces({MediaType.TEXT_HTML, MediaType.APPLICATION_XHTML_XML})
320405
// Login configuration by id
321-
public void logoutPost(@PathParam("idpConfigId") final String idpConfigId,
406+
public void logoutPost(@Parameter(description = "Identity Provider configuration ID (typically host ID)", required = true) @PathParam("idpConfigId") final String idpConfigId,
322407
@Context final HttpServletRequest httpServletRequest,
323408
@Context final HttpServletResponse httpServletResponse) throws IOException, URISyntaxException {
324409

@@ -350,12 +435,27 @@ public void logoutPost(@PathParam("idpConfigId") final String idpConfigId,
350435
throw new DoesNotExistException(message);
351436
}
352437

438+
@Operation(
439+
summary = "Process SAML logout (GET)",
440+
description = "Processes a SAML logout request via GET method. Initiates logout flow and redirects to the configured logout endpoint or builds a logout URL based on the request."
441+
)
442+
@ApiResponses(value = {
443+
@ApiResponse(responseCode = "200",
444+
description = "SAML logout processed successfully",
445+
content = @Content(mediaType = "text/html")),
446+
@ApiResponse(responseCode = "404",
447+
description = "IDP configuration not found or not enabled",
448+
content = @Content(mediaType = "text/html")),
449+
@ApiResponse(responseCode = "500",
450+
description = "Internal server error during logout processing",
451+
content = @Content(mediaType = "text/html"))
452+
})
353453
@GET
354454
@Path("/logout/{idpConfigId}")
355455
@NoCache
356456
@Produces({MediaType.TEXT_HTML, MediaType.APPLICATION_XHTML_XML})
357457
// Login configuration by id
358-
public void logoutGet(@PathParam("idpConfigId") final String idpConfigId,
458+
public void logoutGet(@Parameter(description = "Identity Provider configuration ID (typically host ID)", required = true) @PathParam("idpConfigId") final String idpConfigId,
359459
@Context final HttpServletRequest httpServletRequest,
360460
@Context final HttpServletResponse httpServletResponse) throws IOException, URISyntaxException {
361461

‎dotCMS/src/main/java/com/dotcms/rest/RoleResource.java‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.dotcms.rest;
22

3+
import com.dotcms.rest.annotation.SwaggerCompliant;
34
import javax.ws.rs.GET;
45
import javax.ws.rs.Path;
56
import javax.ws.rs.PathParam;
@@ -17,6 +18,12 @@
1718
import com.dotmarketing.util.json.JSONArray;
1819
import com.dotmarketing.util.json.JSONException;
1920
import com.dotmarketing.util.json.JSONObject;
21+
import io.swagger.v3.oas.annotations.Operation;
22+
import io.swagger.v3.oas.annotations.Parameter;
23+
import io.swagger.v3.oas.annotations.media.Content;
24+
import io.swagger.v3.oas.annotations.media.Schema;
25+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
26+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
2027
import io.swagger.v3.oas.annotations.tags.Tag;
2128
import javax.servlet.http.HttpServletRequest;
2229
import javax.servlet.http.HttpServletResponse;
@@ -25,6 +32,7 @@
2532
import java.util.Map;
2633

2734

35+
@SwaggerCompliant(value = "Core authentication and user management APIs", batch = 1)
2836
@Tag(name = "Roles")
2937
@Path("/role")
3038
public class RoleResource {
@@ -61,10 +69,31 @@ public class RoleResource {
6169
* @throws JSONException
6270
*/
6371

72+
@Operation(
73+
summary = "Load role children (deprecated)",
74+
description = "Returns role hierarchy with first-level children for lazy-loading role tree in admin UI. If no ID provided, returns root roles. This endpoint is deprecated.",
75+
deprecated = true
76+
)
77+
@ApiResponses(value = {
78+
@ApiResponse(responseCode = "200",
79+
description = "Role children loaded successfully",
80+
content = @Content(mediaType = "application/json",
81+
schema = @Schema(type = "object", description = "Role hierarchy tree with child roles containing id, name, locked, and children properties"))),
82+
@ApiResponse(responseCode = "401",
83+
description = "Unauthorized - backend user authentication required",
84+
content = @Content(mediaType = "application/json")),
85+
@ApiResponse(responseCode = "403",
86+
description = "Forbidden - insufficient permissions",
87+
content = @Content(mediaType = "application/json")),
88+
@ApiResponse(responseCode = "500",
89+
description = "Internal server error",
90+
content = @Content(mediaType = "application/json"))
91+
})
6492
@GET
6593
@Path("/loadchildren/{params:.*}")
6694
@Produces("application/json")
67-
public Response loadChildren(@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam("params") String params)
95+
public Response loadChildren(@Context HttpServletRequest request, @Context final HttpServletResponse response,
96+
@Parameter(description = "URL parameters including role ID (id=roleId or empty for root roles)", required = true) @PathParam("params") String params)
6897
throws DotDataException, JSONException {
6998

7099
final InitDataObject initData = new WebResource.InitBuilder(webResource)
@@ -172,10 +201,28 @@ public Response loadChildren(@Context HttpServletRequest request, @Context final
172201
* @throws JSONException
173202
*/
174203

204+
@Operation(
205+
summary = "Load role by ID (deprecated)",
206+
description = "Returns detailed role information including all role properties. Used for loading complete role details in admin UI. This endpoint is deprecated.",
207+
deprecated = true
208+
)
209+
@ApiResponses(value = {
210+
@ApiResponse(responseCode = "200",
211+
description = "Role loaded successfully",
212+
content = @Content(mediaType = "application/json",
213+
schema = @Schema(type = "object", description = "Role details including DBFQN, FQN, description, permissions, id, name, and other role properties"))),
214+
@ApiResponse(responseCode = "401",
215+
description = "Unauthorized - backend user authentication required",
216+
content = @Content(mediaType = "application/json")),
217+
@ApiResponse(responseCode = "500",
218+
description = "Internal server error",
219+
content = @Content(mediaType = "application/json"))
220+
})
175221
@GET
176222
@Path("/loadbyid/{params:.*}")
177223
@Produces("application/json")
178-
public Response loadById(@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam("params") String params) throws DotDataException, JSONException {
224+
public Response loadById(@Context HttpServletRequest request, @Context final HttpServletResponse response,
225+
@Parameter(description = "URL parameters including role ID (id=roleId)", required = true) @PathParam("params") String params) throws DotDataException, JSONException {
179226

180227
final InitDataObject initData = new WebResource.InitBuilder(webResource)
181228
.requiredBackendUser(true)
@@ -241,11 +288,29 @@ public Response loadById(@Context HttpServletRequest request, @Context final Htt
241288
* @throws DotDataException
242289
* @throws JSONException
243290
*/
291+
@Operation(
292+
summary = "Load roles by name filter (deprecated)",
293+
description = "Returns a filtered role tree structure where leaf nodes contain the specified name. Used for role filtering in admin UI. This endpoint is deprecated.",
294+
deprecated = true
295+
)
296+
@ApiResponses(value = {
297+
@ApiResponse(responseCode = "200",
298+
description = "Filtered roles loaded successfully",
299+
content = @Content(mediaType = "application/json",
300+
schema = @Schema(type = "object", description = "Filtered role tree structure with identifier, label, and items containing matching roles"))),
301+
@ApiResponse(responseCode = "401",
302+
description = "Unauthorized - backend user authentication required",
303+
content = @Content(mediaType = "application/json")),
304+
@ApiResponse(responseCode = "500",
305+
description = "Internal server error",
306+
content = @Content(mediaType = "application/json"))
307+
})
244308
@GET
245309
@Path("/loadbyname/{params:.*}")
246310
@Produces("application/json")
247311
@SuppressWarnings("unchecked")
248-
public Response loadByName(@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam("params") String params) throws DotDataException, JSONException {
312+
public Response loadByName(@Context HttpServletRequest request, @Context final HttpServletResponse response,
313+
@Parameter(description = "URL parameters including name filter (name=filterText)", required = true) @PathParam("params") String params) throws DotDataException, JSONException {
249314

250315
final InitDataObject initData = new WebResource.InitBuilder(webResource)
251316
.requiredBackendUser(true)

‎dotCMS/src/main/java/com/dotcms/rest/UserResource.java‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
package com.dotcms.rest;
22

3+
import com.dotcms.rest.annotation.SwaggerCompliant;
4+
import io.swagger.v3.oas.annotations.media.Schema;
35
import javax.ws.rs.GET;
46
import javax.ws.rs.Path;
57
import javax.ws.rs.PathParam;
@@ -17,6 +19,11 @@
1719
import com.liferay.portal.PortalException;
1820
import com.liferay.portal.SystemException;
1921
import com.liferay.portal.model.User;
22+
import io.swagger.v3.oas.annotations.Operation;
23+
import io.swagger.v3.oas.annotations.Parameter;
24+
import io.swagger.v3.oas.annotations.media.Content;
25+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
26+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
2027
import io.swagger.v3.oas.annotations.tags.Tag;
2128

2229
import javax.servlet.http.HttpServletRequest;
@@ -29,6 +36,7 @@
2936
* {@link com.dotcms.rest.api.v1.user.UserResource} end-point.
3037
*/
3138
@Deprecated
39+
@SwaggerCompliant(value = "Core authentication and user management APIs", batch = 1)
3240
@Tag(name = "Users")
3341
@Path("/user")
3442
public class UserResource {
@@ -43,12 +51,29 @@ public class UserResource {
4351
* @throws JSONException
4452
*
4553
*/
46-
54+
@Operation(
55+
summary = "Get logged in user (deprecated)",
56+
description = "Returns a JSON representation of the currently logged in user including userId, emailAddress, firstName, lastName, and roleId. This endpoint is deprecated - use v1 UserResource instead.",
57+
deprecated = true
58+
)
59+
@ApiResponses(value = {
60+
@ApiResponse(responseCode = "200",
61+
description = "User information retrieved successfully",
62+
content = @Content(mediaType = "application/json",
63+
schema = @Schema(type = "object", description = "User information containing userId, emailAddress, firstName, lastName, and roleId"))),
64+
@ApiResponse(responseCode = "401",
65+
description = "Unauthorized - backend user authentication required",
66+
content = @Content(mediaType = "application/json")),
67+
@ApiResponse(responseCode = "500",
68+
description = "Internal server error",
69+
content = @Content(mediaType = "application/json"))
70+
})
4771
@GET
4872
@Path("/getloggedinuser/{params:.*}")
4973
@Produces("application/json")
5074
@Deprecated
51-
public Response getLoggedInUser(@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam("params") String params) throws DotDataException,
75+
public Response getLoggedInUser(@Context HttpServletRequest request, @Context final HttpServletResponse response,
76+
@Parameter(description = "URL parameters for the request", required = true) @PathParam("params") String params) throws DotDataException,
5277
DotRuntimeException, PortalException, SystemException, JSONException {
5378

5479
final InitDataObject initData = new WebResource.InitBuilder(webResource)

0 commit comments

Comments
 (0)