diff --git a/.gitignore b/.gitignore index 8ea0bdbd..c6f007a3 100644 --- a/.gitignore +++ b/.gitignore @@ -119,6 +119,7 @@ gradle-app.setting modules.xml .idea/misc.xml *.ipr +/out/ # End of https://www.gitignore.io/api/intellij+iml diff --git a/.idea/.name b/.idea/.name new file mode 100644 index 00000000..4dd8587f --- /dev/null +++ b/.idea/.name @@ -0,0 +1 @@ +auth0 \ No newline at end of file diff --git a/.idea/compiler.xml b/.idea/compiler.xml index 238d375b..26c7e48e 100644 --- a/.idea/compiler.xml +++ b/.idea/compiler.xml @@ -5,7 +5,7 @@ - + \ No newline at end of file diff --git a/README.md b/README.md index db1b9011..ca337c19 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,7 @@ The Management API is divided into different entities. Each of them have the lis * **Logs:** See [Docs](https://auth0.com/docs/api/management/v2#!/Logs/get_logs). Access the methods by calling `mgmt.logEvents()`. * **Rules:** See [Docs](https://auth0.com/docs/api/management/v2#!/Rules/get_rules). Access the methods by calling `mgmt.rules()`. * **User Blocks:** See [Docs](https://auth0.com/docs/api/management/v2#!/User_Blocks/get_user_blocks). Access the methods by calling `mgmt.userBlocks()`. -* **Users:** See [Docs](https://auth0.com/docs/api/management/v2#!/Users/get_users). Access the methods by calling `mgmt.users()`. +* **Users:** See [this](https://auth0.com/docs/api/management/v2#!/Users/get_users) and [this](https://auth0.com/docs/api/management/v2#!/Users_By_Email) Docs. Access the methods by calling `mgmt.users()`. * **Blacklists:** See [Docs](https://auth0.com/docs/api/management/v2#!/Blacklists/get_tokens). Access the methods by calling `mgmt.blacklists()`. * **Emails:** See [Docs](https://auth0.com/docs/api/management/v2#!/Emails/get_provider). Access the methods by calling `mgmt.emailProvider()`. * **Guardian:** See [Docs](https://auth0.com/docs/api/management/v2#!/Guardian/get_factors). Access the methods by calling `mgmt.guardian()`. @@ -275,6 +275,26 @@ The Management API is divided into different entities. Each of them have the lis ### Users +#### List by Email + +Creates a request to list the Users by Email. This is the preferred and fastest way to query Users by Email, and should be used instead of calling the generic list method with an email query. An API Token with scope `read:users` is needed. If you want the identities.access_token property to be included, you will also need the scope `read:user_idp_tokens`. +You can pass an optional Filter to narrow the results in the response. + +`Request listByEmail(String email, UserFilter filter)` + +Example: +```java +FieldsFilter filter = new FieldsFilter(...); +Request request = mgmt.users().listByEmail("johndoe@auth0.com", filter); +try { + UsersPage response = request.execute(); +} catch (APIException exception) { + // api error +} catch (Auth0Exception exception) { + // request error +} +``` + #### List Creates a request to list the Users. An API Token with scope `read:users` is needed. If you want the identities.access_token property to be included, you will also need the scope `read:user_idp_tokens`. diff --git a/src/main/java/com/auth0/client/mgmt/UsersEntity.java b/src/main/java/com/auth0/client/mgmt/UsersEntity.java index 476c4a2f..cee46e36 100644 --- a/src/main/java/com/auth0/client/mgmt/UsersEntity.java +++ b/src/main/java/com/auth0/client/mgmt/UsersEntity.java @@ -1,5 +1,6 @@ package com.auth0.client.mgmt; +import com.auth0.client.mgmt.filter.FieldsFilter; import com.auth0.client.mgmt.filter.LogEventFilter; import com.auth0.client.mgmt.filter.UserFilter; import com.auth0.json.mgmt.guardian.Enrollment; @@ -23,7 +24,7 @@ import static com.auth0.client.mgmt.filter.QueryFilter.KEY_QUERY; /** - * Class that provides an implementation of the Users methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Users + * Class that provides an implementation of the Users methods of the Management API as defined in https://auth0.com/docs/api/management/v2#!/Users and https://auth0.com/docs/api/management/v2#!/Users_By_Email */ @SuppressWarnings("WeakerAccess") public class UsersEntity extends BaseManagementEntity { @@ -32,6 +33,35 @@ public class UsersEntity extends BaseManagementEntity { super(client, baseUrl, apiToken); } + /** + * Request all the Users that match a given email. A token with scope read:users is needed. + * If you want the identities.access_token property to be included, you will also need the scope read:user_idp_tokens. + * See https://auth0.com/docs/api/management/v2#!/Users_By_Email/get_users_by_email + * + * @param email the email of the users to look up. + * @param filter the filter to use. Can be null. + * @return a Request to execute. + */ + public Request> listByEmail(String email, FieldsFilter filter) { + Asserts.assertNotNull(email, "email"); + + HttpUrl.Builder builder = baseUrl + .newBuilder() + .addPathSegments("api/v2/users-by-email"); + builder.addQueryParameter("email", email); + if (filter != null) { + for (Map.Entry e : filter.getAsMap().entrySet()) { + builder.addQueryParameter(e.getKey(), String.valueOf(e.getValue())); + } + } + + String url = builder.build().toString(); + CustomRequest> request = new CustomRequest<>(client, url, "GET", new TypeReference>() { + }); + request.addHeader("Authorization", "Bearer " + apiToken); + return request; + } + /** * Request all the Users. A token with scope read:users is needed. * If you want the identities.access_token property to be included, you will also need the scope read:user_idp_tokens. diff --git a/src/test/java/com/auth0/client/mgmt/UsersEntityTest.java b/src/test/java/com/auth0/client/mgmt/UsersEntityTest.java index b34d9c5e..a6924827 100644 --- a/src/test/java/com/auth0/client/mgmt/UsersEntityTest.java +++ b/src/test/java/com/auth0/client/mgmt/UsersEntityTest.java @@ -1,5 +1,6 @@ package com.auth0.client.mgmt; +import com.auth0.client.mgmt.filter.FieldsFilter; import com.auth0.client.mgmt.filter.LogEventFilter; import com.auth0.client.mgmt.filter.UserFilter; import com.auth0.json.mgmt.guardian.Enrollment; @@ -23,6 +24,57 @@ public class UsersEntityTest extends BaseMgmtEntityTest { + @Test + public void shouldListUsersByEmail() throws Exception { + Request> request = api.users().listByEmail("johndoe@auth0.com", null); + assertThat(request, is(notNullValue())); + + server.jsonResponse(MGMT_USERS_LIST, 200); + List response = request.execute(); + RecordedRequest recordedRequest = server.takeRequest(); + + assertThat(recordedRequest, hasMethodAndPath("GET", "/api/v2/users-by-email")); + assertThat(recordedRequest, hasHeader("Content-Type", "application/json")); + assertThat(recordedRequest, hasHeader("Authorization", "Bearer apiToken")); + assertThat(recordedRequest, hasQueryParameter("email", "johndoe@auth0.com")); + + assertThat(response, is(notNullValue())); + assertThat(response, hasSize(2)); + } + + @Test + public void shouldListUsersByEmailWithFields() throws Exception { + FieldsFilter filter = new FieldsFilter().withFields("some,random,fields", true); + Request> request = api.users().listByEmail("johndoe@auth0.com", filter); + assertThat(request, is(notNullValue())); + + server.jsonResponse(MGMT_USERS_LIST, 200); + List response = request.execute(); + RecordedRequest recordedRequest = server.takeRequest(); + + assertThat(recordedRequest, hasMethodAndPath("GET", "/api/v2/users-by-email")); + assertThat(recordedRequest, hasHeader("Content-Type", "application/json")); + assertThat(recordedRequest, hasHeader("Authorization", "Bearer apiToken")); + assertThat(recordedRequest, hasQueryParameter("email", "johndoe@auth0.com")); + assertThat(recordedRequest, hasQueryParameter("fields", "some,random,fields")); + assertThat(recordedRequest, hasQueryParameter("include_fields", "true")); + + assertThat(response, is(notNullValue())); + assertThat(response, hasSize(2)); + } + + @Test + public void shouldReturnEmptyUsersByEmail() throws Exception { + Request> request = api.users().listByEmail("missing@auth0.com", null); + assertThat(request, is(notNullValue())); + + server.jsonResponse(MGMT_EMPTY_LIST, 200); + List response = request.execute(); + + assertThat(response, is(notNullValue())); + assertThat(response, is(emptyCollectionOf(User.class))); + } + @Test public void shouldListUsers() throws Exception { Request request = api.users().list(null);