feat(jans-auth-server): java docs for ssa (#2995)

Author: Milton-Ch

jans-auth-server/server/src/main/java/io/jans/as/server/ssa/ws/rs/SsaContextBuilder.java

@@ -14,10 +14,28 @@
 import jakarta.inject.Named;
 import jakarta.servlet.http.HttpServletRequest;
 
+/**
+ * Provides builder methods for SSA
+ */
 @Stateless
 @Named
 public class SsaContextBuilder {
 
+    /**
+     * ModifySsaResponseContext instance for use in the SSA custom script call.
+     * <p>
+     * Method was created with the purpose of passing unit tests, since when instantiating ModifySsaResponseContext
+     * it internally call {@link io.jans.service.cdi.util.CdiUtil} and cannot be mocked
+     * </p>
+     *
+     * @param httpRequest      Http request
+     * @param grant            Grant type
+     * @param client           Client
+     * @param appConfiguration App configuration
+     * @param attributeService Attribute service
+     * @return New instance of {@link ModifySsaResponseContext}
+     */
+    @Deprecated
     public ModifySsaResponseContext buildModifySsaResponseContext(HttpServletRequest httpRequest, AuthorizationGrant grant,
                                                                   Client client, AppConfiguration appConfiguration, AttributeService attributeService) {
         return new ModifySsaResponseContext(httpRequest, grant, client, appConfiguration, attributeService);

jans-auth-server/server/src/main/java/io/jans/as/server/ssa/ws/rs/SsaJsonService.java

@@ -22,21 +22,49 @@
 
 import static io.jans.as.model.ssa.SsaRequestParam.*;
 
+/**
+ * Provides json utilities for SSA
+ */
 @Stateless
 @Named
 public class SsaJsonService {
 
     @Inject
     private AppConfiguration appConfiguration;
 
+    /**
+     * Convert to json string from jsonObject.
+     *
+     * @param jsonObject Json object to convert
+     * @return Json string
+     * @throws JSONException If an error is found when converting.
+     */
     public String jsonObjectToString(JSONObject jsonObject) throws JSONException {
         return jsonObject.toString(4).replace("\\/", "/");
     }
 
+    /**
+     * Convert to json string from jsonArray.
+     *
+     * @param jsonArray Json array to convert
+     * @return Json string
+     * @throws JSONException If an error is found when converting.
+     */
     public String jsonArrayToString(JSONArray jsonArray) throws JSONException {
         return jsonArray.toString(4).replace("\\/", "/");
     }
 
+    /**
+     * Convert to JSONArray from ssaList with structure SSA.
+     *
+     * <p>
+     * Method generates the SSA structure to add them to a json array.
+     * </p>
+     *
+     * @param ssaList List of SSA
+     * @return Json array
+     * @throws JSONException If an error is found when converting.
+     */
     public JSONArray getJSONArray(List<Ssa> ssaList) throws JSONException {
         JSONArray jsonArray = new JSONArray();
         if (ssaList == null) {
@@ -67,6 +95,13 @@ public JSONArray getJSONArray(List<Ssa> ssaList) throws JSONException {
         return jsonArray;
     }
 
+    /**
+     * Convert to JSON using jwt.
+     *
+     * @param jwt json web token of SSA
+     * @return Json object.
+     * @throws JSONException If an error is found when converting.
+     */
     public JSONObject getJSONObject(String jwt) throws JSONException {
         JSONObject responseJsonObject = new JSONObject();
         Util.addToJSONObjectIfNotNull(responseJsonObject, SSA.getName(), jwt);

jans-auth-server/server/src/main/java/io/jans/as/server/ssa/ws/rs/SsaRestWebService.java

@@ -12,8 +12,20 @@
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 
+/**
+ * Interface to handle all SSA REST web services.
+ */
 public interface SsaRestWebService {
 
+    /**
+     * Create SSA for the organization with "expiration" (optional).
+     *
+     * @param requestParams Valid json
+     * @param httpRequest   Http request object
+     * @return {@link Response} with status {@code 201 (Created)} and with body the ssa token,
+     * or with status {@code 401 (Unauthorized)} if unauthorized access request,
+     * or with status {@code 500 (Internal Server Error)} if internal error occurred.
+     */
     @POST
     @Path("/ssa")
     @Produces({MediaType.APPLICATION_JSON})
@@ -22,6 +34,16 @@ Response create(
             @Context HttpServletRequest httpRequest
     );
 
+    /**
+     * Get list of SSA based on "jti" or "org_id" filter.
+     *
+     * @param jti           Unique identifier
+     * @param orgId         Organization ID
+     * @param httpRequest   Http request
+     * @return the {@link Response} with status {@code 200 (Ok)} and with body the ssa list,
+     * or with status {@code 401 (Unauthorized)} if unauthorized access request,
+     * or with status {@code 500 (Internal Server Error)} if internal error occurred.
+     */
     @GET
     @Path("/ssa")
     @Produces({MediaType.APPLICATION_JSON})
@@ -32,11 +54,29 @@ Response get(
             @Context HttpServletRequest httpRequest
     );
 
+    /**
+     * Validate existing active SSA based on "jti".
+     *
+     * @param jti Unique identifier
+     * @return {@link Response} with status {@code 200 (Ok)} if is was validated successfully,
+     * or with status {@code 401 (Unauthorized)} if unauthorized access request,
+     * or with status {@code 500 (Internal Server Error)} if internal error occurred.
+     */
     @HEAD
     @Path("/ssa")
     @Produces({MediaType.APPLICATION_JSON})
     Response validate(@HeaderParam("jti") String jti);
 
+    /**
+     * Revokes existing active SSA based on "jti" or "org_id".
+     *
+     * @param jti         Unique identifier
+     * @param orgId       Organization ID
+     * @param httpRequest Http request
+     * @return the {@link Response} with status {@code 200 (Ok)} if it was revoked successfully,
+     * or with status {@code 401 (Unauthorized)} if unauthorized access request,
+     * or with status {@code 500 (Internal Server Error)} if internal error occurred.
+     */
     @DELETE
     @Path("/ssa")
     @Produces({MediaType.APPLICATION_JSON})

jans-auth-server/server/src/main/java/io/jans/as/server/ssa/ws/rs/SsaRestWebServiceImpl.java

@@ -15,6 +15,9 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.core.Response;
 
+/**
+ * Implements all methods of the {@link SsaRestWebService} interface.
+ */
 @Path("/")
 public class SsaRestWebServiceImpl implements SsaRestWebService {
 
@@ -30,21 +33,62 @@ public class SsaRestWebServiceImpl implements SsaRestWebService {
     @Inject
     private SsaRevokeAction ssaRevokeAction;
 
+    /**
+     * Creates an SSA from the requested parameters.
+     * <p>
+     * Method calls the action where the SSA creation logic is implemented.
+     * <p/>
+     *
+     * @param requestParams Valid json
+     * @param httpRequest   Http request object
+     * @return {@link Response} with status {@code 201} (Created) and with body the ssa token (jwt).
+     */
     @Override
     public Response create(String requestParams, HttpServletRequest httpRequest) {
         return ssaCreateAction.create(requestParams, httpRequest);
     }
 
+    /**
+     * Get existing active SSA based on "jti" or "org_id".
+     * <p>
+     * Method calls the action where the SSA get logic is implemented.
+     * <p/>
+     *
+     * @param jti         Unique identifier
+     * @param orgId       Organization ID
+     * @param httpRequest Http request
+     * @return {@link Response} with status {@code 200 (Ok)} and with body List of SSA.
+     */
     @Override
     public Response get(Boolean softwareRoles, String jti, Long orgId, HttpServletRequest httpRequest) {
         return ssaGetAction.get(softwareRoles, jti, orgId, httpRequest);
     }
 
+    /**
+     * Validate existing active SSA based on "jti".
+     * <p>
+     * Method calls the action where the SSA validate logic is implemented.
+     * <p/>
+     *
+     * @param jti Unique identifier
+     * @return {@link Response} with status {@code 200} (Ok) if SSA has been validated.
+     */
     @Override
     public Response validate(String jti) {
         return ssaValidateAction.validate(jti);
     }
 
+    /**
+     * Revoked existing active SSA based on "jti" or "org_id".
+     * <p>
+     * Method calls the action where the SSA revoke logic is implemented.
+     * </p>
+     *
+     * @param jti         Unique identifier
+     * @param orgId       Organization ID
+     * @param httpRequest Http request
+     * @return {@link Response} with status {@code 200 (Ok)} if SSA has been revoked.
+     */
     @Override
     public Response revoke(String jti, Long orgId, HttpServletRequest httpRequest) {
         return ssaRevokeAction.revoke(jti, orgId, httpRequest);

jans-auth-server/server/src/main/java/io/jans/as/server/ssa/ws/rs/SsaRestWebServiceValidator.java

@@ -15,13 +15,17 @@
 import jakarta.ejb.Stateless;
 import jakarta.inject.Inject;
 import jakarta.inject.Named;
+import jakarta.ws.rs.WebApplicationException;
 import jakarta.ws.rs.core.Response;
 import org.slf4j.Logger;
 
 import java.util.Arrays;
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * Provides methods to validate different params about SSA.
+ */
 @Named
 @Stateless
 public class SsaRestWebServiceValidator {
@@ -38,7 +42,14 @@ public class SsaRestWebServiceValidator {
     @Inject
     private ScopeService scopeService;
 
-    public Client getClientFromSession() {
+    /**
+     * Get client from session
+     *
+     * @return {@link Client} if obtained.
+     * @throws WebApplicationException with status {@code 401} and key <b>INVALID_CLIENT</b> if the client cannot
+     *                                 be obtained.
+     */
+    public Client getClientFromSession() throws WebApplicationException {
         SessionClient sessionClient = identity.getSessionClient();
         if (sessionClient != null) {
             log.debug("Client: {}, obtained from session", sessionClient.getClient().getClientId());
@@ -47,13 +58,27 @@ public Client getClientFromSession() {
         throw errorResponseFactory.createBadRequestException(SsaErrorResponseType.INVALID_CLIENT, "Invalid client");
     }
 
-    public void checkScopesPolicy(Client client, String scope) {
+    /**
+     * Check if the client has the given scope.
+     *
+     * @param client Client to check scope
+     * @param scope  Scope to validate
+     * @throws WebApplicationException with status {@code 401} and key <b>UNAUTHORIZED_CLIENT</b> if you don't have the scope.
+     */
+    public void checkScopesPolicy(Client client, String scope) throws WebApplicationException {
         List<String> scopes = scopeService.getScopeIdsByDns(Arrays.stream(client.getScopes()).collect(Collectors.toList()));
         if (!scopes.contains(scope))
             throw errorResponseFactory.createWebApplicationException(Response.Status.UNAUTHORIZED, SsaErrorResponseType.UNAUTHORIZED_CLIENT, "Unauthorized client");
     }
 
-    public void checkScopesPolicy(Client client, List<String> scopeList) {
+    /**
+     * Check if the client has at least one scope from the list of scopes.
+     *
+     * @param client    Client to check scope
+     * @param scopeList List of scope to validated
+     * @throws WebApplicationException with status {@code 401} and key <b>UNAUTHORIZED_CLIENT</b> if you don't have the scope.
+     */
+    public void checkScopesPolicy(Client client, List<String> scopeList) throws WebApplicationException {
         if (client == null || scopeList == null || scopeList.isEmpty()) {
             throw errorResponseFactory.createWebApplicationException(Response.Status.UNAUTHORIZED, SsaErrorResponseType.UNAUTHORIZED_CLIENT, "Unauthorized client");
         }