This is a wrapper library for Authlete Web APIs.

Authlete is a cloud service that provides an implementation of OAuth 2.0 & OpenID Connect (overview). By using the Web APIs provided by Authlete, you can build a DB-less authorization server. "DB-less" here means that you don't have to prepare a database server that stores authorization data (e.g. access tokens), settings of authorization servers and settings of client applications. These data are stored in the Authlete server on cloud.

java-oauth-server is the reference implementation of an authorization server written using this library and authlete-java-jaxrs library. It is a good starting point for your own authorization server implementation.

Apache License, Version 2.0

<dependency>
    <groupId>com.authlete</groupId>
    <artifactId>authlete-java-common</artifactId>
    <version>1.38</version>
</dependency>

https://github.com/authlete/authlete-java-common

http://authlete.github.io/authlete-java-common/

All the methods to communicate with Authlete Web APIs are gathered in AuthleteApi interface. To get an implementation of the interface, you need to call create() method of AuthleteApiFactory class. There are two variants of the method as shown below.

public static AuthleteApi
    create(AuthleteConfiguration configuration);

public static AuthleteApi
    create(AuthleteConfiguration configuration, String className);

As you can see, both methods take AuthleteConfiguration as their first argument. AuthleteConfiguration is an interface that holds configuration values to access Authlete Web APIs such as the URL of Authlete server and API credentials of a service. To be concrete, the interface has the following methods.

authlete-java-common library includes three implementations of AuthleteConfiguration interface as listed below.

You can use one of these or create your own implementation of the interface. In either case, you can get an implementation of AuthleteApi interface by passing an AuthleteConfiguration instance to create() method of AuthleteApiFactory class.

In summary, the flow to get an implementation of AuthleteApi becomes like below.

// Prepare an instance of AuthleteConfiguration interface.
AuthleteConfiguration configuration = ...;

// Get an instance of AuthleteApi interface.
AuthleteApi api = AuthleteApiFactory.create(configuration);

If you want to do it in an easier way, use AuthleteApiFactory.getDefaultApi() method. This method searches the file system and the classpath for a properties file named authlete.properties and loads the content of the file using AuthletePropertiesConfiguration class.

// Search the file system and the classpath for "authlete.properties".
AuthleteApi api = AuthleteApiFactory.getDefaultApi();

AuthleteApiFactory.getDefaultApi() method caches the search result, so you can call th emethod as many times as you like without worrying about the overhead of file loading.

Among the three implementations of AuthleteConfiguration interface, this secion explains AuthletePropertiesConfiguration class.

AuthletePropertiesConfiguration class provides a mechanism to use a properties file to set configuration values to access Authlete Web APIs. The class searches the file system and the classpath for a specified file.

Valid property keys in a properties file and their meanings are as follows.

If you don't want to write API secrets in plain text, use *.api_secret.encrypted keys instead of *.api_secret keys. You can set encrypted secrets to the *.encrypted keys. But in this case, you have to pass the encryption key and the initial vector to a constructor of AuthletePropertiesConfiguration so that the loader can decode the encrypted values. See the JavaDoc for details.

As a matter of fact, authlete-java-common library does NOT include any implementation of AuthleteApi interface. Therefore, you need another library that contains an implementation of AuthleteApi interface. At the time of this writing, authlete-java-jaxrs is the only such library.

AuthleteApiFactory.create() method searches known locations for an AuthleteApi implementation and loads one using reflection. The reason to use reflection is to avoid depending on specific implementations (e.g. JAX-RS based implementation in authlete-java-jaxrs). And again, at the time of this writing, com.authlete.jaxrs.api.AuthleteApiImpl is the only entry in the internal list of known locations of implementation classes.

Methods in AuthleteApi interface can be divided into some categories.

1. Methods for Authorization Endpoint Implementation

- `authorization(AuthorizationRequest)`
- `authorizationFail(AuthorizationFailRequest)`
- `authorizationIssue(AuthorizationIssueRequest)`

2. Methods for Token Endpoint Implementation

- `token(TokenRequest)`
- `tokenFail(TokenFailRequest)`
- `tokenIssue(TokenIssueRequest)`

3. Methods for Service Management

- `createService(Service)`
- `deleteService(long serviceApiKey)`
- `getService(long serviceApiKey)`
- `getServiceList()`
- `getServiceList(int start, int end)`
- `updateService(Service)`

4. Methods for Client Application Management

- `createClient(Client)`
- `deleteClient(long clientId)`
- `getClient(long clientId)`
- `getClientList()`
- `getClientList(int start, int end)`
- `updateClient(Client)`

5. Methods for Access Token Introspection

- `introspection(IntrospectionRequest)`

6. Methods for Revocation Endpoint Implementation

- `revocation(RevocationRequest)`

7. Methods for User Info Endpoint Implementation

- `userinfo(UserInfoRequest)`
- `userinfoIssue(UserInfoIssueRequest)`

8. Methods for JWK Set Endpoint Implementation

- `getServiceJwks()`
- `getServiceJwks(boolean pretty, boolean includePrivateKeys)`

9. Methods for OpenID Connect Discovery

- `getServiceConfiguration()`
- `getServiceConfiguration(boolean pretty)`

10. Methods for Token Operations

- `tokenCreate(TokenCreateRequest)`
- `tokenUpdate(TokenUpdateRequest)`

11. Methods for Requestable Scopes per Client

- `getRequestableScopes(long clientId)`
- `setRequestableScopes(long clientId, String[] scopes)`
- `deleteRequestableScopes(long clientId)`

The following code snippet is an example to get the list of your existing services. Each service corresponds to an authorization server.

// Get an implementation of AuthleteApi interface.
AuthleteApi api = AuthleteApiFactory.getDefaultApi();

// Get the list of services.
ServiceListResponse response = api.getServiceList();

You can write an authorization server using the methods in AuthleteApi interface only, but the task will become much easier if you use utility classes in authlete-java-jaxrs library. See java-oauth-server for an example of an authorization server implementation written using the utility classes.

• Authlete - Authlete Home Page
• JavaDoc - JavaDoc of this library
• authlete-java-jaxrs - Authlete Library for JAX-RS (Java)
• java-oauth-server - Authorization Server Implementation
• java-resource-server - Resource Server Implementation

Authlete, Inc.
support@authlete.com