Java client library for the Auth0 platform.
Get Auth0 Java via Maven:
<dependency>
<groupId>com.auth0</groupId>
<artifactId>auth0</artifactId>
<version>1.34.1</version>
</dependency>or Gradle:
implementation 'com.auth0:auth0:1.34.1'The Auth0 Authentication API and User's Management API are available for Android in the auth0.android library. Check https://github.com/auth0/auth0.android for more information.
The implementation is based on the Authentication API Docs.
Create an AuthAPI instance by providing the Application details from the dashboard. Read the recommendations for keeping the resources usage low.
AuthAPI auth = new AuthAPI("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}");Creates an AuthorizeUrlBuilder to authenticate the user with an OAuth provider. The redirectUri must be white-listed in the "Allowed Callback URLs" section of the Applications Settings. Parameters can be added to the final URL by using the builder methods. When ready, call build() and obtain the URL.
AuthorizeUrlBuilder authorizeUrl(String redirectUri)
Example:
String url = auth.authorizeUrl("https://me.auth0.com/callback")
.withConnection("facebook")
.withAudience("https://api.me.auth0.com/users")
.withScope("openid contacts")
.withState("state123")
.build();Creates a LogoutUrlBuilder to log out the user. The returnToUrl must be white-listed in the "Allowed Logout URLs" section of the Dashboard, depending on the value of setClientId this configuration should be set in the Application or in the Tenant Settings. Parameters can be added to the final URL by using the builder methods. When ready, call build() and obtain the URL.
LogoutUrlBuilder logoutUrl(String returnToUrl, boolean setClientId)
Example:
String url = auth.logoutUrl("https://me.auth0.com/home", true)
.useFederated(true)
.build();Creates a request to get the user information associated to a given access token. This will only work if the token has been granted the openid scope.
Request<UserInfo> userInfo(String accessToken)
Example:
Request<UserInfo> request = auth.userInfo("nisd1h9dk.....s1doWJOsaf");
try {
UserInfo info = request.execute();
// info.getValues();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to reset the user's password. This will only work for db connections.
Request resetPassword(String email, String connection)
Example:
Request request = auth.resetPassword("[email protected]", "Username-Password-Authentication");
try {
request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to create a user. Up to 10 additional Sign Up fields can be added to the request. This will only work for db connections.
SignUpRequest signUp(String email, String username, String password, String connection)
SignUpRequest signUp(String email, String password, String connection)
Example:
Map<String, String> fields = new HashMap<>();
fields.put("age", "25");
fields.put("city", "Buenos Aires");
SignUpRequest request = auth.signUp("[email protected]", "username", "password123", "Username-Password-Authentication")
.setCustomFields(fields);
try {
CreatedUser user = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to exchange the code previously obtained by calling the /authorize endpoint. The redirect URI must be the one sent in the /authorize call.
AuthRequest exchangeCode(String code, String redirectUri)
Example:
AuthRequest request = auth.exchangeCode("asdfgh", "https://me.auth0.com/callback")
.setAudience("https://api.me.auth0.com/users")
.setScope("openid contacts");
try {
TokenHolder holder = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to log in the user with username and password. The connection used is the one defined as "Default Directory" in the account settings.
AuthRequest login(String emailOrUsername, String password)
Example:
AuthRequest request = auth.login("[email protected]", "password123")
.setAudience("https://api.me.auth0.com/users")
.setScope("openid contacts");
try {
TokenHolder holder = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to log in the user with username and password using the Password Realm.
AuthRequest login(String emailOrUsername, String password, String realm)
Example:
AuthRequest request = auth.login("[email protected]", "password123", "Username-Password-Authentication")
.setAudience("https://api.me.auth0.com/users")
.setScope("openid contacts");
try {
TokenHolder holder = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to get a Token for the given Audience.
AuthRequest requestToken(String audience)
Example:
AuthRequest request = auth.requestToken("https://api.me.auth0.com/users")
.setScope("openid contacts");
try {
TokenHolder holder = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to revoke an existing Refresh Token.
Request<Void> revokeToken(String refreshToken)
Example:
Request<Void> request = auth.revokeToken("nisd1h9dks1doWJOsaf");
try {
request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to renew the authentication and get fresh new credentials using a valid Refresh Token.
AuthRequest renewAuth(String refreshToken)
Example:
AuthRequest request = auth.renewAuth("nisd1h9dks1doWJOsaf");
try {
TokenHolder holder = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}This library supports Passwordless Authentication to allow users to log in without the need to remember a password.
The email flow supports sending both a code or link to initiate login:
try {
PasswordlessEmailResponse = auth.startPasswordlessEmailFlow("[email protected]", PasswordlessEmailType.CODE)
.execute();
} catch (Auth0Exception e) {
// handle request error
}You can also initiate the passwordless flow by sending a code via SMS:
try {
PasswordlessSmsResponse result = auth.startPasswordlessSmsFlow("+16511234567")
.execute();
} catch (Auth0Exception e) {
// handle request error
}Using the verification code sent to the user, you can complete the passwordless authentication flow and obtain the tokens:
AuthRequest request = auth.exchangePasswordlessOtp("emailOrPhone", PasswordlessRealmType.EMAIL, new char[]{'c','o','d','e'});
try {
TokenHolder tokens = request.execute();
} catch (Auth0Exception e) {
// handle request error
}Organizations is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications.
Note that Organizations is currently only available to customers on our Enterprise and Startup subscription plans.
Log in to an organization by using withOrganization() when building the Authorization URL:
AuthAPI auth = new AuthAPI("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}");
String url = auth.authorizeUrl("https://me.auth0.com/callback")
.withOrganization("{YOUR_ORGANIZATION_ID")
.build();Important! When logging into an organization, it is important to ensure the org_id claim of the ID Token matches the expected organization value. The IdTokenVerifier can be configured with an expected org_id claim value, as the example below demonstrates.
For more information, please read Work with Tokens and Organizations on Auth0 Docs.
IdTokenVerifier.init("{ISSUER}", "{AUDIENCE}", signatureVerifier)
.withOrganization("{ORG_ID}")
.build()
.verify(jwt);Accept a user invitation by using withInvitation() when building the Authorization URL:
AuthAPI auth = new AuthAPI("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}");
String url = auth.authorizeUrl("https://me.auth0.com/callback")
.withOrganization("{YOUR_ORGANIZATION_ID")
.withInvitation("{YOUR_INVITATION_ID}")
.build();
The implementation is based on the Management API Docs.
Create a ManagementAPI instance by providing the domain from the Application dashboard and a valid API Token. Read the recommendations for keeping the resources usage low.
ManagementAPI mgmt = new ManagementAPI("{YOUR_DOMAIN}", "{YOUR_API_TOKEN}");You can use the Authentication API to obtain a token for a previously authorized Application:
AuthAPI authAPI = new AuthAPI("{YOUR_DOMAIN}", "{YOUR_CLIENT_ID}", "{YOUR_CLIENT_SECRET}");
AuthRequest authRequest = authAPI.requestToken("https://{YOUR_DOMAIN}/api/v2/");
TokenHolder holder = authRequest.execute();
ManagementAPI mgmt = new ManagementAPI("{YOUR_DOMAIN}", holder.getAccessToken());(Note that the snippet above should have error handling, and ideally cache the obtained token until it expires instead of requesting one access token for each Management API v2 invocation).
An expired token for an existing ManagementAPI instance can be replaced by calling the setApiToken method with the new token.
Click here for more information on how to obtain API Tokens.
The Management API is divided into different entities. Each of them have the list, create, update, delete and update methods plus a few more if corresponds. The calls are authenticated using the API Token given in the ManagementAPI instance creation and must contain the scope required by each entity. See the javadoc for details on which scope is expected for each call.
- Blacklists: See Docs. Access the methods by calling
mgmt.blacklists(). - Client Grants: See Docs. Access the methods by calling
mgmt.clientGrants(). This endpoint supports pagination. - Clients: See Docs. Access the methods by calling
mgmt.clients(). This endpoint supports pagination. - Connections: See Docs. Access the methods by calling
mgmt.connections(). This endpoint supports pagination. - Device Credentials: See Docs. Access the methods by calling
mgmt.deviceCredentials(). - Email Providers: See Docs. Access the methods by calling
mgmt.emailProvider(). - Email Templates: See Docs. Access the methods by calling
mgmt.emailTemplates(). - Grants: See Docs. Access the methods by calling
mgmt.grants(). This endpoint supports pagination. - Guardian: See Docs. Access the methods by calling
mgmt.guardian(). - Jobs: See Docs. Access the methods by calling
mgmt.jobs(). - Logs: See Docs. Access the methods by calling
mgmt.logEvents(). This endpoint supports pagination. - Log Streams: See Docs. Access the methods by calling
mgmt.logStreams(). - Resource Servers: See Docs. Access the methods by calling
mgmt.resourceServers(). This endpoint supports pagination. - Roles: See Docs. Access the methods by calling
mgmt.roles(). This endpoint supports pagination. - Rules: See Docs. Access the methods by calling
mgmt.rules(). This endpoint supports pagination. - Stats: See Docs. Access the methods by calling
mgmt.stats(). - Tenants: See Docs. Access the methods by calling
mgmt.tenants(). - Tickets: See Docs. Access the methods by calling
mgmt.tickets(). - User Blocks: See Docs. Access the methods by calling
mgmt.userBlocks(). - Users: See this and this doc. Access the methods by calling
mgmt.users(). This endpoint supports pagination.
Some of the endpoints above indicate they support paginated responses. You can request a page of items by passing in the filter instance the
pageandper_pageparameters, and optionallyinclude_totalsto obtain a summary of the results. Refer to the "List Users" example below for details.
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<List<User>> listByEmail(String email, UserFilter filter)
Example:
FieldsFilter filter = new FieldsFilter();
//...
Request<List<User>> request = mgmt.users().listByEmail("[email protected]", filter);
try {
List<User> response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}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.
You can pass an optional Filter to narrow the results in the response.
Request<UsersPage> list(UserFilter filter)
Example:
UserFilter filter = new UserFilter()
.withPage(0, 20);
//...
Request<UsersPage> request = mgmt.users().list(filter);
try {
UsersPage response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to get a User. 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 specify the fields you want to include or exclude from the response.
Request<User> get(String userId, UserFilter filter)
Example:
UserFilter filter = new UserFilter();
//...
Request<User> request = mgmt.users().get("auth0|123", filter);
try {
User response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to create a User. An API Token with scope create:users is needed.
Request<User> create(User user)
Example:
User data = new User("my-connection");
//...
Request<User> request = mgmt.users().create(data);
try {
User response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to delete a User. An API Token with scope delete:users is needed.
Request delete(String userId)
Example:
Request request = mgmt.users().delete("auth0|123");
try {
request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to update a User. An API Token with scope update:users is needed. If you're updating app_metadata you'll also need update:users_app_metadata scope.
Request<User> update(String userId, User user)
Example:
User data = new User();
//...
Request request = mgmt.users().update("auth0|123", data);
try {
User response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to list the User's Guardian Enrollments. An API Token with scope read:users is needed.
Request<List<Enrollment>> getEnrollments(String userId)
Example:
Request<List<Enrollment>> request = mgmt.users().getEnrollments("auth0|123");
try {
List<Enrollment> response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to list the User's Log Events. An API Token with scope read:logs is needed.
You can pass an optional Filter to narrow the results in the response.
Request<LogEventsPage> getLogEvents(String userId, LogEventFilter filter)
Example:
LogEventFilter filter = new LogEventFilter();
//...
Request<LogEventsPage> request = mgmt.users().getLogEvents("auth0|123", filter);
try {
LogEventsPage response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to delete the User's Multifactor Provider. An API Token with scope update:users is needed.
Request deleteMultifactorProvider(String userId, String provider)
Example:
Request request = mgmt.users().deleteMultifactorProvider("auth0|123", "duo");
try {
request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to rotate the User's Recovery Code. An API Token with scope update:users is needed.
Request<RecoveryCode> rotateRecoveryCode(String userId)
Example:
Request<RecoveryCode> request = mgmt.users().rotateRecoveryCode("auth0|123");
try {
RecoveryCode response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to link two User identities. An API Token with scope update:users is needed.
Request<List<Identity>> linkIdentity(String primaryUserId, String secondaryUserId, String provider, String connectionId)
Example:
Request<List<Identities>> request = mgmt.users().linkIdentity("auth0|123", "124", "facebook", "c90");
try {
List<Identities> response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Creates a request to un-link two User identities. An API Token with scope update:users is needed.
Request<List<Identity>> unlinkIdentity(String primaryUserId, String secondaryUserId, String provider)
Example:
Request<List<Identities>> request = mgmt.users().unlinkIdentity("auth0|123", "124", "facebook");
try {
List<Identities> response = request.execute();
} catch (APIException exception) {
// api error
} catch (Auth0Exception exception) {
// request error
}Requests can be executed asynchronously, using the executeAsync() method, which returns a CompletableFuture<T>.
The SDK implements a custom networking stack on top of the OkHttp library. The official recommendation from Square is to re-use as much as possible these clients. However, it's not possible to pass an existing OkHttpClient instance to our AuthAPI and ManagementAPI clients.
The networking client used by both the AuthAPI and ManagementAPI clients can be configured through the HttpOptions, which enables custom timeout configuration and proxy support:
HttpOptions options = new HttpOptions();
// configure timeouts; default is ten seconds for both connect and read timeouts:
options.setConnectTimeout(5);
options.setReadTimeout(15);
// configure proxy:
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("{IP-ADDRESS}", {PORT}));
ProxyOptions proxyOptions = new ProxyOptions(proxy);
options.setProxyOptions(proxyOptions);
// create client
AuthAPI authAPI = new AuthAPI("{CLIENT_ID}", "{CLIENT_SECRET}", options);Whenever you instantiate a client, a new OkHttpClient instance is created internally to handle the network requests. This instance is not directly exposed for customization. In order to reduce resource consumption, make use of the singleton pattern to keep a single instance of this SDK's API client during the lifecycle of your application.
For the particular case of the ManagementAPI client, if the token you've originally set has expired or you require to change its scopes, you can update the client's token with the setApiToken(String) method.
The API Clients throw Auth0Exception when an unexpected error happens on a request execution, i.e. Connectivity or Timeout error.
If you need to handle different error scenarios you need to catch first APIException, which provides methods to get a clue of what went wrong.
The APIExplorer includes a list of response messages for each endpoint. You can get a clue of what went wrong by asking the Http status code: exception.getStatusCode(). i.e. a status_code=403 would mean that the token has an insufficient scope.
An error code will be included to categorize the type of error, you can get it by calling exception.getError(). If you want to see a user friendly description of what happened and why the request is failing check the exception.getDescription(). Finally, if the error response includes additional properties they can be obtained by calling exception.getValue("{THE_KEY}").
Example exception data
{
statusCode: 400,
description: "Query validation error: 'String 'users' does not match pattern. Must be a comma separated list of the following values: name,strategy,options,enabled_clients,id,provisioning_ticket_url' on property fields (A comma separated list of fields to include or exclude (depending on include_fields) from the result, empty to retrieve all fields).",
error: "invalid_query_string"
}
This library also provides the ability to validate an OIDC-compliant ID Token, according to the OIDC Specification.
To verify an ID Token that is signed using the RS256 signing algorithm, you will need to provide an implementation of
PublicKeyProvider that will return the public key used to verify the token's signature. The example below demonstrates how to use the JwkProvider from the jwks-rsa-java library:
JwkProvider provider = new JwkProviderBuilder("https://your-domain.auth0.com").build();
SignatureVerifier sigVerifier = SignatureVerifier.forRS256(new PublicKeyProvider() {
@Override
public RSAPublicKey getPublicKeyById(String keyId) throws PublicKeyProviderException {
try {
return (RSAPublicKey) provider.get(keyId).getPublicKey();
} catch (JwkException jwke) {
throw new PublicKeyProviderException("Error obtaining public key", jwke);
}
}
}
IdTokenVerifier idTokenVerifier = IdTokenVerifier.init("https://your-domain.auth0.com/","your-client-id", signatureVerifier).build();
try {
idTokenVerifier.verify("token", "expected-nonce");
} catch(IdTokenValidationException idtve) {
// Handle invalid token exception
}To verify an ID Token that is signed using the HS256 signing algorithm:
SignatureVerifier signatureVerifier = SignatureVerifier.forHS256("your-client-secret");
IdTokenVerifier idTokenVerifier = IdTokenVerifier.init("https://your-domain.auth0.com/","your-client-id", signatureVerifier).build();
try {
idTokenVerifier.verify("token", "expected-nonce");
} catch(IdTokenValidationException idtve) {
// Handle invalid token exception
}By default, time-based claims such as the token expiration (exp claim) will allow for a leeway of 60 seconds.
You can customize the leeway by using the withLeeway when building the IdTokenVerifier:
IdTokenVerifier idTokenVerifier = IdTokenVerifier.init("https://your-domain.auth0.com/","your-client-id", signatureVerifier)
.withLeeway(120) // two minutes
.build();When verifying the token, the following methods are available to support different scenarios:
// Verify the token's signature and claims, excluding the nonce and auth_time claims
idTokenVerifier.verify("token");
// Verify the token's signature and claims, including the nonce.
// The expected nonce should be the nonce sent on the authorization request.
idTokenVerifier.verify("token", "expected-nonce");
// Verify the token's signature and claims, including the nonce and the auth_time claim.
// The maxAuthenticationAge parameter specifies the maximum amount of time since the end-user last actively authenticated,
// and it should match the max_age parameter sent on the authorization request.
idTokenVerifier.verify("token", "expected-nonce", 24 * 60 * 60); // maximum authentication age of 24 hoursFor more information about Auth0 check our documentation page.
Auth0 helps you to:
- Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, among others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
- Add authentication through more traditional username/password databases.
- Add support for linking different user accounts with the same user.
- Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
- Analytics of how, when and where users are logging in.
- Pull data from other sources and add it to the user profile, through JavaScript rules.
- Go to Auth0 and click Sign Up.
- Use Google, GitHub or Microsoft Account to login.
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
This project is licensed under the MIT license. See the LICENSE file for more info.