From 3bbe82057c4d55c452724a4e99bf3d092bd2d99d Mon Sep 17 00:00:00 2001 From: Marko Strukelj Date: Tue, 15 Sep 2015 21:22:06 +0200 Subject: [PATCH] KEYCLOAK-1241 Can't build release with Java 8 - Improve javadoc comments for new REST API documentation generation --- services/pom.xml | 1 + .../ClientIdAndSecretAuthenticator.java | 7 +- .../client/JWTClientAuthenticator.java | 3 +- .../services/managers/RealmManager.java | 2 +- .../admin/AttackDetectionResource.java | 48 +---- .../AuthenticationManagementResource.java | 171 ++++++++++++++++-- .../ClientAttributeCertificateResource.java | 13 +- .../resources/admin/ClientResource.java | 62 +++++-- .../resources/admin/ClientsResource.java | 8 +- .../admin/IdentityProviderResource.java | 54 +++++- .../admin/IdentityProvidersResource.java | 34 ++++ .../admin/ProtocolMappersResource.java | 31 +++- .../resources/admin/RealmAdminResource.java | 62 ++++--- .../resources/admin/RealmsAdminResource.java | 14 +- .../resources/admin/RoleByIdResource.java | 22 ++- .../admin/RoleContainerResource.java | 15 +- .../admin/ScopeMappedClientResource.java | 12 +- .../resources/admin/ScopeMappedResource.java | 12 +- .../admin/UserClientRoleMappingsResource.java | 14 +- .../admin/UserFederationProviderResource.java | 20 +- .../UserFederationProvidersResource.java | 10 +- .../resources/admin/UsersResource.java | 125 ++++++++----- .../admin/info/ServerInfoAdminResource.java | 2 +- 23 files changed, 528 insertions(+), 214 deletions(-) diff --git a/services/pom.xml b/services/pom.xml index 25e1756547..bfb07ce768 100755 --- a/services/pom.xml +++ b/services/pom.xml @@ -292,6 +292,7 @@ + ${project.basedir}/target/apidocs-rest/asciidoc diff --git a/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java b/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java index e86e68e10e..bb17291d85 100644 --- a/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java +++ b/services/src/main/java/org/keycloak/authentication/authenticators/client/ClientIdAndSecretAuthenticator.java @@ -12,15 +12,10 @@ import javax.ws.rs.core.Response; import org.jboss.logging.Logger; import org.keycloak.OAuth2Constants; -import org.keycloak.authentication.AuthenticationFlowContext; import org.keycloak.authentication.AuthenticationFlowError; import org.keycloak.authentication.ClientAuthenticationFlowContext; -import org.keycloak.events.Details; -import org.keycloak.events.Errors; import org.keycloak.models.AuthenticationExecutionModel; import org.keycloak.models.ClientModel; -import org.keycloak.models.KeycloakSession; -import org.keycloak.models.RealmModel; import org.keycloak.provider.ProviderConfigProperty; import org.keycloak.representations.idm.CredentialRepresentation; import org.keycloak.util.BasicAuthHelper; @@ -147,7 +142,7 @@ public class ClientIdAndSecretAuthenticator extends AbstractClientAuthenticator @Override public List getConfigPropertiesPerClient() { - // This impl doesn't use generic screen in admin console, but has it's own screen. So no need to return anything here + // This impl doesn't use generic screen in admin console, but has its own screen. So no need to return anything here return Collections.emptyList(); } diff --git a/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java b/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java index bb87e34dc0..0c308abec3 100644 --- a/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java +++ b/services/src/main/java/org/keycloak/authentication/authenticators/client/JWTClientAuthenticator.java @@ -19,7 +19,6 @@ import org.keycloak.jose.jws.JWSInput; import org.keycloak.jose.jws.crypto.RSAProvider; import org.keycloak.models.AuthenticationExecutionModel; import org.keycloak.models.ClientModel; -import org.keycloak.models.KeycloakSession; import org.keycloak.models.RealmModel; import org.keycloak.models.utils.KeycloakModelUtils; import org.keycloak.provider.ProviderConfigProperty; @@ -163,7 +162,7 @@ public class JWTClientAuthenticator extends AbstractClientAuthenticator { @Override public List getConfigPropertiesPerClient() { - // This impl doesn't use generic screen in admin console, but has it's own screen. So no need to return anything here + // This impl doesn't use generic screen in admin console, but has its own screen. So no need to return anything here return Collections.emptyList(); } diff --git a/services/src/main/java/org/keycloak/services/managers/RealmManager.java b/services/src/main/java/org/keycloak/services/managers/RealmManager.java index bb582af189..fb0578e8f3 100755 --- a/services/src/main/java/org/keycloak/services/managers/RealmManager.java +++ b/services/src/main/java/org/keycloak/services/managers/RealmManager.java @@ -337,7 +337,7 @@ public class RealmManager implements RealmImporter { } // Could happen when migrating from older version and I have exported JSON file, which contains "realm-management" client but not "impersonation" client - // I need to postpone impersonation because it needs "realm-management" client and it's roles set + // I need to postpone impersonation because it needs "realm-management" client and its roles set if (postponeImpersonationSetup) { setupImpersonationService(realm); } diff --git a/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java b/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java index 38eec9cd77..26b9956f56 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java @@ -2,64 +2,24 @@ package org.keycloak.services.resources.admin; import org.jboss.logging.Logger; import org.jboss.resteasy.annotations.cache.NoCache; -import org.jboss.resteasy.spi.BadRequestException; -import org.jboss.resteasy.spi.NotFoundException; -import org.jboss.resteasy.spi.ResteasyProviderFactory; import org.keycloak.ClientConnection; -import org.keycloak.events.Event; -import org.keycloak.events.EventQuery; -import org.keycloak.events.EventStoreProvider; -import org.keycloak.events.EventType; -import org.keycloak.events.admin.AdminEvent; -import org.keycloak.events.admin.AdminEventQuery; import org.keycloak.events.admin.OperationType; -import org.keycloak.exportimport.ClientImporter; -import org.keycloak.models.ClientModel; import org.keycloak.models.KeycloakSession; -import org.keycloak.models.ModelDuplicateException; import org.keycloak.models.RealmModel; -import org.keycloak.models.UserFederationProviderModel; -import org.keycloak.models.UserSessionModel; import org.keycloak.models.UsernameLoginFailureModel; -import org.keycloak.models.cache.CacheRealmProvider; -import org.keycloak.models.cache.CacheUserProvider; -import org.keycloak.models.utils.ModelToRepresentation; -import org.keycloak.models.utils.RepresentationToModel; -import org.keycloak.protocol.oidc.TokenManager; -import org.keycloak.representations.adapters.action.GlobalRequestResult; -import org.keycloak.representations.idm.RealmEventsConfigRepresentation; -import org.keycloak.representations.idm.RealmRepresentation; -import org.keycloak.services.ErrorResponse; -import org.keycloak.services.managers.AuthenticationManager; import org.keycloak.services.managers.BruteForceProtector; -import org.keycloak.services.managers.LDAPConnectionTestManager; -import org.keycloak.services.managers.RealmManager; -import org.keycloak.services.managers.ResourceAdminManager; -import org.keycloak.services.managers.UsersSyncManager; -import org.keycloak.timer.TimerProvider; -import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.GET; -import javax.ws.rs.POST; -import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; -import javax.ws.rs.QueryParam; import javax.ws.rs.core.Context; import javax.ws.rs.core.HttpHeaders; import javax.ws.rs.core.MediaType; -import javax.ws.rs.core.Response; import javax.ws.rs.core.UriInfo; -import java.text.ParseException; -import java.text.SimpleDateFormat; -import java.util.Date; import java.util.HashMap; -import java.util.LinkedList; -import java.util.List; import java.util.Map; -import java.util.regex.PatternSyntaxException; /** * Base resource class for the admin REST api of one realm @@ -127,7 +87,9 @@ public class AttackDetectionResource { } /** - * Clear any user login failures for the user. This can release temporary disabled user + * Clear any user login failures for the user + * + * This can release temporary disabled user * * @param username */ @@ -143,7 +105,9 @@ public class AttackDetectionResource { } /** - * Clear any user login failures for all users. This can release temporary disabled users + * Clear any user login failures for all users + * + * This can release temporary disabled users * */ @Path("brute-force/usernames") diff --git a/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java b/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java index 0bb2e11866..ede2e278a7 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java @@ -6,13 +6,10 @@ import org.jboss.resteasy.spi.BadRequestException; import org.jboss.resteasy.spi.NotFoundException; import org.keycloak.authentication.AuthenticationFlow; import org.keycloak.authentication.Authenticator; -import org.keycloak.authentication.AuthenticatorUtil; import org.keycloak.authentication.ClientAuthenticator; import org.keycloak.authentication.ClientAuthenticatorFactory; import org.keycloak.authentication.ConfigurableAuthenticatorFactory; -import org.keycloak.authentication.DefaultAuthenticationFlow; import org.keycloak.authentication.FormAction; -import org.keycloak.authentication.FormAuthenticationFlow; import org.keycloak.authentication.FormAuthenticator; import org.keycloak.authentication.RequiredActionFactory; import org.keycloak.authentication.RequiredActionProvider; @@ -22,7 +19,6 @@ import org.keycloak.models.AuthenticatorConfigModel; import org.keycloak.models.KeycloakSession; import org.keycloak.models.RealmModel; import org.keycloak.models.RequiredActionProviderModel; -import org.keycloak.provider.ConfiguredProvider; import org.keycloak.provider.ProviderConfigProperty; import org.keycloak.provider.ProviderFactory; import org.keycloak.representations.idm.ConfigPropertyRepresentation; @@ -172,6 +168,11 @@ public class AuthenticationManagementResource { } } + /** + * Get form providers + * + * Returns a list of form providers. + */ @Path("/form-providers") @GET @NoCache @@ -182,6 +183,11 @@ public class AuthenticationManagementResource { return buildProviderMetadata(factories); } + /** + * Get authenticator providers + * + * Returns a list of authenticator providers. + */ @Path("/authenticator-providers") @GET @NoCache @@ -192,6 +198,11 @@ public class AuthenticationManagementResource { return buildProviderMetadata(factories); } + /** + * Get client authenticator providers + * + * Returns a list of client authenticator providers. + */ @Path("/client-authenticator-providers") @GET @NoCache @@ -216,6 +227,11 @@ public class AuthenticationManagementResource { return providers; } + /** + * Get form action providers + * + * Returns a list of form action providers. + */ @Path("/form-action-providers") @GET @NoCache @@ -227,6 +243,11 @@ public class AuthenticationManagementResource { } + /** + * Get authentication flows + * + * Returns a list of authentication flows. + */ @Path("/flows") @GET @NoCache @@ -242,6 +263,12 @@ public class AuthenticationManagementResource { return flows; } + /** + * Create a new authentication flow + * + * @param model Authentication flow model + * @return + */ @Path("/flows") @POST @NoCache @@ -258,6 +285,12 @@ public class AuthenticationManagementResource { } + /** + * Get authentication flow for id + * + * @param id Flow id + * @return + */ @Path("/flows/{id}") @GET @NoCache @@ -272,6 +305,11 @@ public class AuthenticationManagementResource { return flow; } + /** + * Delete an authentication flow + * + * @param id Flow id + */ @Path("/flows/{id}") @DELETE @NoCache @@ -288,6 +326,14 @@ public class AuthenticationManagementResource { realm.removeAuthenticationFlow(flow); } + /** + * Copy existing authentication flow under a new name + * + * The new name is given as 'newName' attribute of the passed JSON object + * + * @param flowAlias Name of the existing authentication flow + * @param data JSON containing 'newName' attribute + */ @Path("/flows/{flowAlias}/copy") @POST @NoCache @@ -338,6 +384,12 @@ public class AuthenticationManagementResource { } } + /** + * Add new flow with new execution to existing flow + * + * @param flowAlias Alias of parent authentication flow + * @param data New authentication flow / execution JSON data containing 'alias', 'type', 'provider', and 'description' attributes + */ @Path("/flows/{flowAlias}/executions/flow") @POST @NoCache @@ -373,6 +425,12 @@ public class AuthenticationManagementResource { realm.addAuthenticatorExecution(execution); } + /** + * Add new authentication execution to a flow + * + * @param flowAlias Alias of parent flow + * @param data New execution JSON data containing 'provider' attribute + */ @Path("/flows/{flowAlias}/executions/execution") @POST @NoCache @@ -395,8 +453,11 @@ public class AuthenticationManagementResource { realm.addAuthenticatorExecution(execution); } - - + /** + * Get authentication executions for a flow + * + * @param flowAlias Flow alias + */ @Path("/flows/{flowAlias}/executions") @GET @NoCache @@ -467,6 +528,12 @@ public class AuthenticationManagementResource { } } + /** + * Update authentication executions of a flow + * + * @param flowAlias Flow alias + * @param rep + */ @Path("/flows/{flowAlias}/executions") @PUT @NoCache @@ -492,6 +559,11 @@ public class AuthenticationManagementResource { } } + /** + * Add new authentication execution + * + * @param model JSON model describing authentication execution + */ @Path("/executions") @POST @NoCache @@ -525,6 +597,11 @@ public class AuthenticationManagementResource { return parentFlow; } + /** + * Raise execution's priority + * + * @param execution Execution id + */ @Path("/executions/{executionId}/raise-priority") @POST @NoCache @@ -564,6 +641,11 @@ public class AuthenticationManagementResource { return executions; } + /** + * Lower execution's priority + * + * @param execution Execution id + */ @Path("/executions/{executionId}/lower-priority") @POST @NoCache @@ -597,6 +679,11 @@ public class AuthenticationManagementResource { } + /** + * Delete execution + * + * @param execution Execution id + */ @Path("/executions/{executionId}") @DELETE @NoCache @@ -617,9 +704,13 @@ public class AuthenticationManagementResource { } - - - + /** + * Update execution with new configuration + * + * @param execution Execution id + * @param config JSON with new configuration + * @return + */ @Path("/executions/{executionId}/config") @POST @NoCache @@ -639,6 +730,12 @@ public class AuthenticationManagementResource { return Response.created(uriInfo.getAbsolutePathBuilder().path(config.getId()).build()).build(); } + /** + * Get execution's configuration + * + * @param execution Execution id + * @param id Configuration id + */ @Path("/executions/{executionId}/config/{id}") @GET @Produces(MediaType.APPLICATION_JSON) @@ -702,6 +799,11 @@ public class AuthenticationManagementResource { } } + /** + * Get unregistered required actions + * + * Returns a list of unregistered required actions. + */ @Path("unregistered-required-actions") @GET @Produces(MediaType.APPLICATION_JSON) @@ -729,6 +831,11 @@ public class AuthenticationManagementResource { return unregisteredList; } + /** + * Register a new required actions + * + * @param data JSON containing 'providerId', and 'name' attributes. + */ @Path("register-required-action") @POST @Consumes(MediaType.APPLICATION_JSON) @@ -746,7 +853,11 @@ public class AuthenticationManagementResource { } - + /** + * Get required actions + * + * Returns a list of required actions. + */ @Path("required-actions") @GET @Produces(MediaType.APPLICATION_JSON) @@ -770,6 +881,10 @@ public class AuthenticationManagementResource { return rep; } + /** + * Get required action for alias + * @param alias Alias of required action + */ @Path("required-actions/{alias}") @GET @Produces(MediaType.APPLICATION_JSON) @@ -783,6 +898,12 @@ public class AuthenticationManagementResource { } + /** + * Update required action + * + * @param alias Alias of required action + * @param rep JSON describing new state of required action + */ @Path("required-actions/{alias}") @PUT @Consumes(MediaType.APPLICATION_JSON) @@ -803,6 +924,10 @@ public class AuthenticationManagementResource { realm.updateRequiredActionProvider(update); } + /** + * Delete required action + * @param alias Alias of required action + */ @Path("required-actions/{alias}") @DELETE public void updateRequiredAction(@PathParam("alias") String alias) { @@ -855,6 +980,9 @@ public class AuthenticationManagementResource { } + /** + * Get authenticator provider's configuration description + */ @Path("config-description/{providerId}") @GET @Produces(MediaType.APPLICATION_JSON) @@ -888,7 +1016,9 @@ public class AuthenticationManagementResource { return propRep; } - + /** + * Get configuration descriptions for all clients + */ @Path("per-client-config-description") @GET @Produces(MediaType.APPLICATION_JSON) @@ -915,6 +1045,10 @@ public class AuthenticationManagementResource { return toReturn; } + /** + * Create new authenticator configuration + * @param config JSON describing new authenticator configuration + */ @Path("config") @POST @NoCache @@ -924,6 +1058,10 @@ public class AuthenticationManagementResource { return Response.created(uriInfo.getAbsolutePathBuilder().path(config.getId()).build()).build(); } + /** + * Get authenticator configuration + * @param id Configuration id + */ @Path("config/{id}") @GET @Produces(MediaType.APPLICATION_JSON) @@ -937,6 +1075,11 @@ public class AuthenticationManagementResource { } return config; } + + /** + * Delete authenticator configuration + * @param id Configuration id + */ @Path("config/{id}") @DELETE @NoCache @@ -959,6 +1102,12 @@ public class AuthenticationManagementResource { realm.removeAuthenticatorConfig(config); } + + /** + * Update authenticator configuration + * @param id Configuration id + * @param config JSON describing new state of authenticator configuration + */ @Path("config/{id}") @PUT @Consumes(MediaType.APPLICATION_JSON) diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java index f6949fc4c2..c6a5feae93 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java @@ -64,6 +64,7 @@ public class ClientAttributeCertificateResource { } /** + * Get key info * * @return */ @@ -78,6 +79,7 @@ public class ClientAttributeCertificateResource { } /** + * Generate a new certificate with new key pair * * @return */ @@ -256,8 +258,9 @@ public class ClientAttributeCertificateResource { } /** + * Get a keystore file for the client, containing private key and public certificate * - * @param config + * @param config Keystore configuration as JSON * @return */ @POST @@ -288,10 +291,12 @@ public class ClientAttributeCertificateResource { } /** - * Generate new keypair and certificate and downloads private key into specified keystore format. Only generated certificate is saved in Keycloak DB, but private - * key is not. + * Generate a new keypair and certificate, and get the private key file * - * @param config + * Generates a keypair and certificate and serves the private key in a specified keystore format. + * Only generated public certificate is saved in Keycloak DB - the private key is not. + * + * @param config Keystore configuration as JSON * @return */ @POST diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java index 821f2793ee..2198333559 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java @@ -92,7 +92,7 @@ public class ClientResource { } /** - * Update the client. + * Update the client * @param rep * @return */ @@ -116,7 +116,7 @@ public class ClientResource { /** - * Get representation of the client. + * Get representation of the client * * @return */ @@ -129,6 +129,7 @@ public class ClientResource { } /** + * Get representation of certificate resource * * @param attributePrefix * @return @@ -140,7 +141,9 @@ public class ClientResource { /** - * Return keycloak.json file for this client to be used to configure the adapter of that client. + * Get keycloak.json file + * + * Returns a keycloak.json file to be used to configure the adapter of the specified client. * * @return * @throws IOException @@ -160,7 +163,9 @@ public class ClientResource { } /** - * Return XML that can be included in the JBoss/Wildfly Keycloak subsystem to configure the adapter of that client. + * Get adapter configuration XML for JBoss / Wildfly Keycloak subsystem + * + * Returns XML that can be included in the JBoss / Wildfly Keycloak subsystem to configure the adapter of that client. * * @return * @throws IOException @@ -177,7 +182,7 @@ public class ClientResource { } /** - * Delete this client. + * Delete the client * */ @DELETE @@ -190,7 +195,7 @@ public class ClientResource { /** - * Generates a new secret for this client + * Generate a new secret for the client * * @return */ @@ -209,7 +214,7 @@ public class ClientResource { } /** - * Get the secret of this client + * Get the client secret * * @return */ @@ -227,7 +232,7 @@ public class ClientResource { } /** - * Base path for managing the scope mappings for this client + * Base path for managing the scope mappings for the client * * @return */ @@ -242,7 +247,9 @@ public class ClientResource { } /** - * Returns set of allowed origin. This is used for CORS requests. Access tokens will have + * Get allowed origins + * + * This is used for CORS requests. Access tokens will have * their allowedOrigins claim set to this value for tokens created for this client. * * @return @@ -258,7 +265,9 @@ public class ClientResource { } /** - * Change the set of allowed origins. This is used for CORS requests. Access tokens will have + * Update allowed origins + * + * This is used for CORS requests. Access tokens will have * their allowedOrigins claim set to this value for tokens created for this client. * * @param allowedOrigins @@ -275,10 +284,12 @@ public class ClientResource { } /** - * Remove set of allowed origins from current allowed origins list. This is used for CORS requests. Access tokens will have + * Delete the specified origins from current allowed origins + * + * This is used for CORS requests. Access tokens will have * their allowedOrigins claim set to this value for tokens created for this client. * - * @param allowedOrigins + * @param allowedOrigins List of origins to delete */ @Path("allowed-origins") @DELETE @@ -294,7 +305,7 @@ public class ClientResource { } /** - * Returns user dedicated to this service account + * Get a user dedicated to the service account * * @return */ @@ -319,8 +330,9 @@ public class ClientResource { } /** - * If the client has an admin URL, push the client's revocation policy to it. + * Push the client's revocation policy to its admin URL * + * If the client has an admin URL, push revocation policy to it. */ @Path("push-revocation") @POST @@ -332,7 +344,9 @@ public class ClientResource { } /** - * Number of user sessions associated with this client + * Get application session count + * + * Returns a number of user sessions associated with this client * * { * "count": number @@ -352,8 +366,12 @@ public class ClientResource { } /** - * Return a list of user sessions associated with this client + * Get user sessions for client * + * Returns a list of user sessions associated with this client + * + * @param firstResult Paging offset + * @param maxResults Paging size * @return */ @Path("user-sessions") @@ -373,6 +391,8 @@ public class ClientResource { } /** + * Logout all sessions + * * If the client has an admin URL, invalidate all sessions associated with that client directly. * */ @@ -386,6 +406,8 @@ public class ClientResource { } /** + * Logout the user by username + * * If the client has an admin URL, invalidate the sessions for a particular user directly. * */ @@ -403,6 +425,8 @@ public class ClientResource { } /** + * Register a cluster node with the client + * * Manually register cluster node to this client - usually it's not needed to call this directly as adapter should handle * by sending registration request to Keycloak * @@ -423,7 +447,7 @@ public class ClientResource { } /** - * Unregister cluster node from this client + * Unregister a cluster node from the client * * @param node */ @@ -443,7 +467,9 @@ public class ClientResource { } /** - * Test if registered cluster nodes are available by sending 'ping' request to all of them + * Test if registered cluster nodes are available + * + * Tests availability by sending 'ping' request to all cluster nodes. * * @return */ diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java index 862aa0952b..e780dbf9b1 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java @@ -52,9 +52,9 @@ public class ClientsResource { } /** - * List of clients belonging to this realm. + * Get clients belonging to the realm * - * @return + * Returns a list of clients belonging to the realm */ @GET @Produces(MediaType.APPLICATION_JSON) @@ -80,7 +80,9 @@ public class ClientsResource { } /** - * Create a new client. Client client_id must be unique! + * Create a new client + * + * Client's client_id must be unique! * * @param uriInfo * @param rep diff --git a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java index eeffe5dc22..bf17f4be0c 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java @@ -7,7 +7,6 @@ import org.keycloak.broker.provider.IdentityProvider; import org.keycloak.broker.provider.IdentityProviderFactory; import org.keycloak.broker.provider.IdentityProviderMapper; import org.keycloak.events.admin.OperationType; -import org.keycloak.models.ClientModel; import org.keycloak.models.FederatedIdentityModel; import org.keycloak.models.IdentityProviderMapperModel; import org.keycloak.models.IdentityProviderModel; @@ -70,6 +69,11 @@ public class IdentityProviderResource { this.adminEvent = adminEvent; } + /** + * Get the identity provider + * + * @return + */ @GET @NoCache @Produces(MediaType.APPLICATION_JSON) @@ -79,6 +83,11 @@ public class IdentityProviderResource { return rep; } + /** + * Delete the identity provider + * + * @return + */ @DELETE @NoCache public Response delete() { @@ -91,6 +100,12 @@ public class IdentityProviderResource { return Response.noContent().build(); } + /** + * Update the identity provider + * + * @param providerRep + * @return + */ @PUT @Consumes(MediaType.APPLICATION_JSON) @NoCache @@ -161,7 +176,13 @@ public class IdentityProviderResource { return null; } - + /** + * Export public broker configuration for identity provider + * + * @param uriInfo + * @param format Format to use + * @return + */ @GET @Path("export") @NoCache @@ -175,6 +196,9 @@ public class IdentityProviderResource { } } + /** + * Get mapper types for identity provider + */ @GET @Path("mapper-types") @NoCache @@ -210,6 +234,9 @@ public class IdentityProviderResource { return types; } + /** + * Get mappers for identity provider + */ @GET @Path("mappers") @Produces(MediaType.APPLICATION_JSON) @@ -223,6 +250,12 @@ public class IdentityProviderResource { return mappers; } + /** + * Add a mapper to identity provider + * + * @param mapper + * @return + */ @POST @Path("mappers") @Consumes(MediaType.APPLICATION_JSON) @@ -238,6 +271,12 @@ public class IdentityProviderResource { } + /** + * Get mapper by id for the identity provider + * + * @param id + * @return + */ @GET @NoCache @Path("mappers/{id}") @@ -249,6 +288,12 @@ public class IdentityProviderResource { return ModelToRepresentation.toRepresentation(model); } + /** + * Update a mapper for the identity provider + * + * @param id Mapper id + * @param rep + */ @PUT @NoCache @Path("mappers/{id}") @@ -263,6 +308,11 @@ public class IdentityProviderResource { } + /** + * Delete a mapper for the identity provider + * + * @param id Mapper id + */ @DELETE @NoCache @Path("mappers/{id}") diff --git a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java index 8b2a0499e5..d3dc33a5a2 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java @@ -57,6 +57,12 @@ public class IdentityProvidersResource { this.adminEvent = adminEvent; } + /** + * Get identity providers + * + * @param providerId Provider id + * @return + */ @Path("/providers/{provider_id}") @GET @NoCache @@ -70,6 +76,14 @@ public class IdentityProvidersResource { return Response.status(BAD_REQUEST).build(); } + /** + * Import identity provider from uploaded JSON file + * + * @param uriInfo + * @param input + * @return + * @throws IOException + */ @POST @Path("import-config") @Consumes(MediaType.MULTIPART_FORM_DATA) @@ -85,6 +99,14 @@ public class IdentityProvidersResource { return config; } + /** + * Import identity provider from JSON body + * + * @param uriInfo + * @param data JSON body + * @return + * @throws IOException + */ @POST @Path("import-config") @Consumes(MediaType.APPLICATION_JSON) @@ -108,6 +130,11 @@ public class IdentityProvidersResource { } } + /** + * Get identity providers + * + * @return + */ @GET @Path("instances") @NoCache @@ -123,6 +150,13 @@ public class IdentityProvidersResource { return representations; } + /** + * Create a new identity provider + * + * @param uriInfo + * @param representation JSON body + * @return + */ @POST @Path("instances") @Consumes(MediaType.APPLICATION_JSON) diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java index 145a26d0ce..306d350b65 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java @@ -7,7 +7,6 @@ import org.keycloak.events.admin.OperationType; import org.keycloak.models.ClientModel; import org.keycloak.models.KeycloakSession; import org.keycloak.models.ProtocolMapperModel; -import org.keycloak.models.RealmModel; import org.keycloak.models.utils.ModelToRepresentation; import org.keycloak.models.utils.RepresentationToModel; import org.keycloak.representations.idm.ProtocolMapperRepresentation; @@ -39,7 +38,7 @@ public class ProtocolMappersResource { protected ClientModel client; - protected RealmAuth auth; + protected RealmAuth auth; protected AdminEventBuilder adminEvent; @@ -58,7 +57,7 @@ public class ProtocolMappersResource { } /** - * Map of mappers by name for a specific protocol + * Get mappers by name for a specific protocol * * @param protocol * @return @@ -77,7 +76,7 @@ public class ProtocolMappersResource { } /** - * creates mapper + * Create a mapper * * @param rep */ @@ -93,7 +92,7 @@ public class ProtocolMappersResource { return Response.created(uriInfo.getAbsolutePathBuilder().path(model.getId()).build()).build(); } /** - * creates multiple mapper + * Create multiple mappers * */ @Path("add-models") @@ -110,6 +109,11 @@ public class ProtocolMappersResource { adminEvent.operation(OperationType.CREATE).resourcePath(uriInfo).representation(reps).success(); } + /** + * Get mappers + * + * @return + */ @GET @NoCache @Path("models") @@ -123,6 +127,12 @@ public class ProtocolMappersResource { return mappers; } + /** + * Get mapper by id + * + * @param id Mapper id + * @return + */ @GET @NoCache @Path("models/{id}") @@ -134,6 +144,12 @@ public class ProtocolMappersResource { return ModelToRepresentation.toRepresentation(model); } + /** + * Update the mapper + * + * @param id Mapper id + * @param rep + */ @PUT @NoCache @Path("models/{id}") @@ -147,6 +163,11 @@ public class ProtocolMappersResource { adminEvent.operation(OperationType.UPDATE).resourcePath(uriInfo).representation(rep).success(); } + /** + * Delete the mapper + * + * @param id Mapper id + */ @DELETE @NoCache @Path("models/{id}") diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java index 40710a1a11..bab74d646e 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java @@ -6,8 +6,6 @@ import org.jboss.resteasy.spi.BadRequestException; import org.jboss.resteasy.spi.NotFoundException; import org.jboss.resteasy.spi.ResteasyProviderFactory; import org.keycloak.ClientConnection; -import org.keycloak.authentication.RequiredActionFactory; -import org.keycloak.authentication.RequiredActionProvider; import org.keycloak.events.Event; import org.keycloak.events.EventQuery; import org.keycloak.events.EventStoreProvider; @@ -27,7 +25,6 @@ import org.keycloak.models.cache.CacheUserProvider; import org.keycloak.models.utils.ModelToRepresentation; import org.keycloak.models.utils.RepresentationToModel; import org.keycloak.protocol.oidc.TokenManager; -import org.keycloak.provider.ProviderFactory; import org.keycloak.representations.adapters.action.GlobalRequestResult; import org.keycloak.representations.idm.RealmEventsConfigRepresentation; import org.keycloak.representations.idm.RealmRepresentation; @@ -143,7 +140,9 @@ public class RealmAdminResource { } /** - * Get the top-level representation of the realm. It will not include nested information like User and Client representations. + * Get the top-level representation of the realm + * + * It will not include nested information like User and Client representations. * * @return */ @@ -172,7 +171,9 @@ public class RealmAdminResource { } /** - * Update the top-level information of this realm. Any user, roles or client information in the representation + * Update the top-level information of the realm + * + * Any user, roles or client information in the representation * will be ignored. This will only update top-level attributes of the realm. * * @param rep @@ -215,7 +216,7 @@ public class RealmAdminResource { } /** - * Delete this realm. + * Delete the realm * */ @DELETE @@ -260,7 +261,7 @@ public class RealmAdminResource { } /** - * Path for managing all realm-level or client-level roles defined in this realm by it's id. + * Path for managing all realm-level or client-level roles defined in this realm by its id. * * @return */ @@ -316,8 +317,10 @@ public class RealmAdminResource { } /** + * Get client session stats + * * Returns a JSON map. The key is the client id, the value is the number of sessions that currently are active - * with that client. Only client's that actually have a session associated with them will be in this map. + * with that client. Only clients that actually have a session associated with them will be in this map. * * @return */ @@ -341,7 +344,9 @@ public class RealmAdminResource { } /** - * View the events provider and how it is configured. + * Get the events provider configuration + * + * Returns JSON object with events provider configuration * * @return */ @@ -356,7 +361,9 @@ public class RealmAdminResource { } /** - * Change the events provider and/or it's configuration + * Update the events provider + * + * Change the events provider and/or its configuration * * @param rep */ @@ -371,15 +378,17 @@ public class RealmAdminResource { } /** - * Query events. Returns all events, or will query based on URL query parameters listed here + * Get events * - * @param client app or oauth client name - * @param user user id - * @param ipAddress - * @param dateTo - * @param dateFrom - * @param firstResult - * @param maxResults + * Returns all events, or filters them based on URL query parameters listed here + * + * @param client App or oauth client name + * @param user User id + * @param ipAddress IP address + * @param dateTo To date + * @param dateFrom From date + * @param firstResult Paging offset + * @param maxResults Paging size * @return */ @Path("events") @@ -448,7 +457,9 @@ public class RealmAdminResource { } /** - * Query admin events. Returns all admin events, or will query based on URL query parameters listed here + * Get admin events + * + * Returns all admin events, or filters events based on URL query parameters listed here * * @param authRealm * @param authClient @@ -538,7 +549,7 @@ public class RealmAdminResource { } /** - * Delete all events. + * Delete all events * */ @Path("events") @@ -551,7 +562,7 @@ public class RealmAdminResource { } /** - * Delete all admin events. + * Delete all admin events * */ @Path("admin-events") @@ -563,6 +574,15 @@ public class RealmAdminResource { eventStore.clearAdmin(realm.getId()); } + /** + * Test LDAP connection + * + * @param action + * @param connectionUrl + * @param bindDn + * @param bindCredential + * @return + */ @Path("testLDAPConnection") @GET @NoCache diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java index f2494c90ee..d0fb5214eb 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java @@ -73,7 +73,9 @@ public class RealmsAdminResource { } /** - * Returns a list of realms. This list is filtered based on what realms the caller is allowed to view. + * Get accessible realms + * + * Returns a list of accessible realms. The list is filtered based on what realms the caller is allowed to view. * * @return */ @@ -107,10 +109,12 @@ public class RealmsAdminResource { } /** - * Import a realm from a full representation of that realm. Realm name must be unique. + * Import a realm + * + * Imports a realm from a full representation of that realm. Realm name must be unique. * * @param uriInfo - * @param rep JSON representation + * @param rep JSON representation of the realm * @return */ @POST @@ -141,7 +145,9 @@ public class RealmsAdminResource { } /** - * Upload a realm from a uploaded JSON file. The posted represenation is expected to be a multipart/form-data encapsulation + * Import a realm from uploaded JSON file + * + * The posted represenation is expected to be a multipart/form-data encapsulation * of a JSON file. The same format a browser would use when uploading a file. * * @param uriInfo diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java index bea5d5283c..1482cabe3f 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java @@ -87,7 +87,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Delete this role + * Delete the role * * @param id id of role */ @@ -102,7 +102,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Update this role + * Update the role * * @param id id of role * @param rep @@ -118,7 +118,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Make this role a composite role by associating some child roles to it. + * Make the role a composite role by associating some child roles * * @param id * @param roles @@ -133,7 +133,9 @@ public class RoleByIdResource extends RoleResource { } /** - * If this role is a composite, return a set of its children + * Get role's children + * + * Returns a set of role's children provided the role is a composite. * * @param id * @return @@ -151,7 +153,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Return a set of realm-level roles that are in the role's composite + * Get realm-level roles that are in the role's composite * * @param id * @return @@ -167,7 +169,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Return a set of client-level roles for a specific client that are in the role's composite + * Get client-level roles for the client that are in the role's composite * * @param id * @param client @@ -189,7 +191,7 @@ public class RoleByIdResource extends RoleResource { } /** - * Return a set of client-level roles for a specific client that are in the role's composite + * Get client-level roles for the client that are in the role's composite * * @param role * @param client @@ -212,10 +214,10 @@ public class RoleByIdResource extends RoleResource { } /** - * Remove the listed set of roles from this role's composite + * Remove a set of roles from the role's composite * - * @param id - * @param roles + * @param id Role id + * @param roles A set of roles to be removed */ @Path("{role-id}/composites") @DELETE diff --git a/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java b/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java index f267d15ef5..168ff471c6 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java @@ -4,7 +4,6 @@ import org.jboss.resteasy.annotations.cache.NoCache; import org.jboss.resteasy.spi.NotFoundException; import org.keycloak.events.admin.OperationType; import org.keycloak.models.ClientModel; -import org.keycloak.models.KeycloakSession; import org.keycloak.models.ModelDuplicateException; import org.keycloak.models.RealmModel; import org.keycloak.models.RoleContainerModel; @@ -51,7 +50,7 @@ public class RoleContainerResource extends RoleResource { } /** - * List all roles for this realm or client + * Get all roles for the realm or client * * @return */ @@ -70,7 +69,7 @@ public class RoleContainerResource extends RoleResource { } /** - * Create a new role for this realm or client + * Create a new role for the realm or client * * @param rep * @return @@ -164,7 +163,7 @@ public class RoleContainerResource extends RoleResource { } /** - * Add a composite to this role + * Add a composite to the role * * @param roleName role's name (not id!) * @param roles @@ -183,7 +182,7 @@ public class RoleContainerResource extends RoleResource { } /** - * List composites of this role + * Get composites of the role * * @param roleName role's name (not id!) * @return @@ -203,7 +202,7 @@ public class RoleContainerResource extends RoleResource { } /** - * Get realm-level roles of this role's composite + * Get realm-level roles of the role's composite * * @param roleName role's name (not id!) * @return @@ -223,7 +222,7 @@ public class RoleContainerResource extends RoleResource { } /** - * An app-level roles for a specific app for this role's composite + * An app-level roles for the specified app for the role's composite * * @param roleName role's name (not id!) * @param client @@ -252,7 +251,7 @@ public class RoleContainerResource extends RoleResource { /** - * Remove roles from this role's composite + * Remove roles from the role's composite * * @param roleName role's name (not id!) * @param roles roles to remove diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java index c087197efa..44b355e037 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java @@ -44,7 +44,9 @@ public class ScopeMappedClientResource { } /** - * Get the roles associated with a client's scope for a specific client. + * Get the roles associated with a client's scope + * + * Returns roles for the client. * * @return */ @@ -63,7 +65,9 @@ public class ScopeMappedClientResource { } /** - * The available client-level roles that can be associated with the client's scope + * The available client-level roles + * + * Returns the roles for the client that can be associated with the client's scope * * @return */ @@ -79,7 +83,9 @@ public class ScopeMappedClientResource { } /** - * Get effective client roles that are associated with the client's scope for a specific client. + * Get effective client roles + * + * Returns the roles for the client that are associated with the client's scope. * * @return */ diff --git a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java index 407594452c..2d9b6a263b 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java @@ -19,9 +19,7 @@ import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; -import javax.ws.rs.core.Context; import javax.ws.rs.core.MediaType; -import javax.ws.rs.core.UriInfo; import java.util.ArrayList; import java.util.HashMap; @@ -51,7 +49,7 @@ public class ScopeMappedResource { } /** - * Get all scope mappings for this client + * Get all scope mappings for the client * * @return */ @@ -94,7 +92,7 @@ public class ScopeMappedResource { } /** - * Get list of realm-level roles associated with this client's scope. + * Get realm-level roles associated with the client's scope * * @return */ @@ -114,7 +112,7 @@ public class ScopeMappedResource { } /** - * Get list of realm-level roles that are available to attach to this client's scope. + * Get realm-level roles that are available to attach to this client's scope * * @return */ @@ -139,7 +137,9 @@ public class ScopeMappedResource { } /** - * Get all effective realm-level roles that are associated with this client's scope. What this does is recurse + * Get effective realm-level roles associated with the client's scope + * + * What this does is recurse * any composite roles associated with the client's scope and adds the roles to this lists. The method is really * to show a comprehensive total view of realm-level roles associated with the client. * diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java index 228ebbde86..8c5851c99f 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/UserClientRoleMappingsResource.java @@ -5,7 +5,6 @@ import org.jboss.resteasy.annotations.cache.NoCache; import org.jboss.resteasy.spi.NotFoundException; import org.keycloak.events.admin.OperationType; import org.keycloak.models.ClientModel; -import org.keycloak.models.KeycloakSession; import org.keycloak.models.RealmModel; import org.keycloak.models.RoleModel; import org.keycloak.models.UserModel; @@ -18,7 +17,6 @@ import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.Produces; -import javax.ws.rs.core.Context; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.UriInfo; @@ -51,7 +49,7 @@ public class UserClientRoleMappingsResource { } /** - * Get client-level role mappings for this user for a specific app + * Get client-level role mappings for the user, and the app * * @return */ @@ -70,7 +68,9 @@ public class UserClientRoleMappingsResource { } /** - * Get effective client-level role mappings. This recurses any composite roles + * Get effective client-level role mappings + * + * This recurses any composite roles * * @return */ @@ -120,9 +120,9 @@ public class UserClientRoleMappingsResource { } /** - * Add client-level roles to the user role mapping. + * Add client-level roles to the user role mapping * - * @param roles + * @param roles */ @POST @Consumes(MediaType.APPLICATION_JSON) @@ -141,7 +141,7 @@ public class UserClientRoleMappingsResource { } /** - * Delete client-level roles from user role mapping. + * Delete client-level roles from user role mapping * * @param roles */ diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java index db1e278e92..6f7bedfd82 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProviderResource.java @@ -98,7 +98,7 @@ public class UserFederationProviderResource { } /** - * get a provider + * Get a provider * */ @GET @@ -126,7 +126,7 @@ public class UserFederationProviderResource { } /** - * trigger sync of users + * Trigger sync of users * * @return */ @@ -150,7 +150,7 @@ public class UserFederationProviderResource { } /** - * List of available User Federation mapper types + * Get available user federation mapper types * * @return */ @@ -227,7 +227,7 @@ public class UserFederationProviderResource { } /** - * Create mapper + * Create a mapper * * @param mapper * @return @@ -251,9 +251,9 @@ public class UserFederationProviderResource { } /** - * Get mapper + * Get a mapper * - * @param id mapperId + * @param id Mapper id * @return */ @GET @@ -268,9 +268,9 @@ public class UserFederationProviderResource { } /** - * Update mapper + * Update a mapper * - * @param id + * @param id Mapper id * @param rep */ @PUT @@ -291,9 +291,9 @@ public class UserFederationProviderResource { } /** - * Delete mapper with given ID + * Delete a mapper with a given id * - * @param id + * @param id Mapper id */ @DELETE @NoCache diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java index 294e633874..8946c36e72 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/UserFederationProvidersResource.java @@ -8,8 +8,6 @@ import org.keycloak.constants.KerberosConstants; import org.keycloak.events.admin.OperationType; import org.keycloak.models.KeycloakSession; import org.keycloak.models.RealmModel; -import org.keycloak.models.RequiredCredentialModel; -import org.keycloak.models.UserCredentialModel; import org.keycloak.models.UserFederationProvider; import org.keycloak.models.UserFederationProviderFactory; import org.keycloak.models.UserFederationProviderModel; @@ -84,7 +82,9 @@ public class UserFederationProvidersResource { } /** - * Get List of available provider factories + * Get available provider factories + * + * Returns a list of available provider factories. * * @return */ @@ -105,7 +105,7 @@ public class UserFederationProvidersResource { } /** - * Get factory with given ID + * Get factory with given id * * @return */ @@ -159,7 +159,7 @@ public class UserFederationProvidersResource { } /** - * list configured providers + * Get configured providers * * @return */ diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java index e3e243788c..24aa35adaf 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java @@ -118,7 +118,7 @@ public class UsersResource { /** * Update the user * - * @param id + * @param id User id * @param rep * @return */ @@ -164,7 +164,9 @@ public class UsersResource { } /** - * Create a new user. Must be a unique username! + * Create a new user + * + * Username must be unique. * * @param uriInfo * @param rep @@ -245,7 +247,7 @@ public class UsersResource { /** * Get represenation of the user * - * @param id user id + * @param id User id * @return */ @Path("{id}") @@ -274,6 +276,12 @@ public class UsersResource { return rep; } + /** + * Impersonate the user + * + * @param id User id + * @return + */ @Path("{id}/impersonation") @POST @NoCache @@ -314,9 +322,9 @@ public class UsersResource { /** - * List set of sessions associated with this user. + * Get sessions associated with the user * - * @param id + * @param id User id * @return */ @Path("{id}/sessions") @@ -339,9 +347,9 @@ public class UsersResource { } /** - * List set of social logins associated with this user. + * Get social logins associated with the user * - * @param id + * @param id User id * @return */ @Path("{id}/federated-identity") @@ -373,6 +381,14 @@ public class UsersResource { return result; } + /** + * Add a social login provider to the user + * + * @param id User id + * @param provider Social login provider id + * @param rep + * @return + */ @Path("{id}/federated-identity/{provider}") @POST @NoCache @@ -392,6 +408,12 @@ public class UsersResource { return Response.noContent().build(); } + /** + * Remove a social login provider from user + * + * @param id User id + * @param provider Social login provider id + */ @Path("{id}/federated-identity/{provider}") @DELETE @NoCache @@ -408,9 +430,9 @@ public class UsersResource { } /** - * List set of consents granted by this user. + * Get consents granted by the user * - * @param id + * @param id User id * @return */ @Path("{id}/consents") @@ -435,10 +457,10 @@ public class UsersResource { } /** - * Revoke consent for particular client + * Revoke consent for particular client from user * - * @param id - * @param clientId + * @param id User id + * @param clientId Client id */ @Path("{id}/consents/{client}") @DELETE @@ -462,10 +484,11 @@ public class UsersResource { } /** - * Remove all user sessions associated with this user. And, for all client that have an admin URL, tell - * them to invalidate the sessions for this particular user. + * Remove all user sessions associated with the user * - * @param id user id + * Also send notification to all clients that have an admin URL to invalidate the sessions for the particular user. + * + * @param id User id */ @Path("{id}/logout") @POST @@ -484,9 +507,9 @@ public class UsersResource { } /** - * delete this user + * Delete the user * - * @param id user id + * @param id User id */ @Path("{id}") @DELETE @@ -509,13 +532,17 @@ public class UsersResource { } /** - * Query list of users. May pass in query criteria + * Get users * - * @param search string contained in username, first or last name, or email + * Returns a list of users, filtered according to query parameters + * + * @param search A String contained in username, first or last name, or email * @param last * @param first * @param email * @param username + * @param first Pagination offset + * @param maxResults Pagination size * @return */ @GET @@ -563,9 +590,9 @@ public class UsersResource { } /** - * Get role mappings for this user + * Get role mappings for the user * - * @param id user id + * @param id User id * @return */ @Path("{id}/role-mappings") @@ -614,9 +641,9 @@ public class UsersResource { } /** - * Get realm-level role mappings for this user + * Get realm-level role mappings for the user * - * @param id user id + * @param id User id * @return */ @Path("{id}/role-mappings/realm") @@ -640,9 +667,11 @@ public class UsersResource { } /** - * Effective realm-level role mappings for this user. Will recurse all composite roles to get this list. + * Get effective realm-level role mappings for the user * - * @param id user id + * This will recurse all composite roles to get the result. + * + * @param id User id * @return */ @Path("{id}/role-mappings/realm/composite") @@ -668,9 +697,9 @@ public class UsersResource { } /** - * Realm-level roles that can be mapped to this user + * Get realm-level roles that can be mapped to this user * - * @param id + * @param id User id * @return */ @Path("{id}/role-mappings/realm/available") @@ -690,10 +719,10 @@ public class UsersResource { } /** - * Add realm-level role mappings + * Add realm-level role mappings to the user * - * @param id - * @param roles + * @param id User id + * @param roles Roles to add */ @Path("{id}/role-mappings/realm") @POST @@ -720,7 +749,7 @@ public class UsersResource { /** * Delete realm-level role mappings * - * @param id user id + * @param id User id * @param roles */ @Path("{id}/role-mappings/realm") @@ -770,12 +799,14 @@ public class UsersResource { return new UserClientRoleMappingsResource(uriInfo, realm, auth, user, clientModel, adminEvent); } + /** - * Set up a temporary password for this user. User will have to reset this temporary password when they log - * in next. + * Set up a temporary password for the user * - * @param id - * @param pass temporary password + * User will have to reset the temporary password next time they log in. + * + * @param id User id + * @param pass A Temporary password */ @Path("{id}/reset-password") @PUT @@ -805,9 +836,9 @@ public class UsersResource { } /** + * Remove TOTP from the user * - * - * @param id + * @param id User id */ @Path("{id}/remove-totp") @PUT @@ -825,13 +856,15 @@ public class UsersResource { } /** - * Send an email to the user with a link they can click to reset their password. + * Send a password-reset email to the user + * + * An email contains a link the user can click to reset their password. * The redirectUri and clientId parameters are optional. The default for the * redirect is the account client. * - * @param id - * @param redirectUri redirect uri - * @param clientId client id + * @param id User is + * @param redirectUri Redirect uri + * @param clientId Client id * @return */ @Path("{id}/execute-actions-email") @@ -880,13 +913,15 @@ public class UsersResource { } /** - * Send an email to the user with a link they can click to verify their email address. + * Send an email-verification email to the user + * + * An email contains a link the user can click to verify their email address. * The redirectUri and clientId parameters are optional. The default for the * redirect is the account client. * - * @param id - * @param redirectUri redirect uri - * @param clientId client id + * @param id User id + * @param redirectUri Redirect uri + * @param clientId Client id * @return */ @Path("{id}/send-verify-email") diff --git a/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java b/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java index fd0afc9615..70022c0c21 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/info/ServerInfoAdminResource.java @@ -38,7 +38,7 @@ public class ServerInfoAdminResource { private KeycloakSession session; /** - * Returns a list of themes, social providers, auth providers, and event listeners available on this server + * Get themes, social providers, auth providers, and event listeners available on this server * * @return */