This is a resource server implementation on Spring Framework. It supports a userinfo endpoint defined in OpenID Connect Core 1.0 and includes an example of a protected resource endpoint that accepts an access token in the ways defined in RFC 6750 (The OAuth 2.0 Authorization Framework: Bearer Token Usage).
This implementation is written using Spring Framework and authlete-java-jaxrs library which uses JAX-RS 2.0 API. JAX-RS is The Java API for RESTful Web Services. JAX-RS 2.0 API has been standardized by JSR 339 and it is included in Java EE 7. On the other hand, authlete-java-jaxrs library is an open source library which provides utility classes for developers to implement an authorization server and a resource server. authlete-java-jaxrs in turn uses authlete-java-common library which is another open source library to communicate with Authlete Web APIs.
To validate an access token presented by a client application, this resource server makes an inquiry to the Authlete server. This means that this resource server expects that the authorization server which has issued the access token uses Authlete as a backend service. spring-oauth-server is such an authorization server implementation and it supports OAuth 2.0 and OpenID Connect.
This implementation does not use Spring Security OAuth. You can change settings of authorization servers and client applications via web consoles (Service Owner Console and Developer Console), so you don't have to do programming to configure authorization servers and register client applications.
$ git clone https://github.com/authlete/spring-resource-server.git
$ cd spring-resource-server
$ vi authlete.properties
$ mvn spring-boot:run
$ curl http://localhost:8081/api/userinfo -d access_token={access-token}
$ curl http://localhost:8081/api/country/{country-code} -d access_token={access-token}
Apache License, Version 2.0
https://github.com/authlete/spring-resource-server
Authlete is a cloud service that provides an implementation of OAuth 2.0 & OpenID Connect (overview). You can easily get the functionalities of OAuth 2.0 and OpenID Connect either by using the default implementation provided by Authlete or by implementing your own authorization server using Authlete Web APIs as spring-oauth-server does.
To use this resource server implementation, you need to get API credentials
from Authlete and set them in authlete.properties. The steps to get API
credentials are very easy. All you have to do is just to register your account
(sign up). See Getting Started for details.
Read New Architecture of OAuth 2.0 and OpenID Connect Implementation for details about the architecture of Authlete.
-
Download the source code of this resource server implementation.
$ git clone https://github.com/authlete/spring-resource-server.git $ cd spring-resource-server -
Edit the configuration file to set the API credentials of yours.
$ vi authlete.properties -
Make sure that you have installed maven and set
JAVA_HOMEproperly. -
Start the resource server on http://localhost:8081/.
$ mvn spring-boot
If you would prefer to use Docker, just hit the following command after the step 2.
$ docker-compose up
spring-resource-server refers to authlete.properties as a configuration file.
If you want to use another different file, specify the name of the file by
the system property authlete.configuration.file like the following.
$ mvn spring-boot:run \
-Drun.jvmArguments="-Dauthlete.configuration.file=local.authlete.properties"
This implementation exposes endpoints as listed in the table below.
| Endpoint | Path |
|---|---|
| UserInfo Endpoint | /api/userinfo |
| Country Endpoint | /api/country/{country-code} |
The userinfo endpoint is an implementation of the requirements described in 5.3. UserInfo Endpoint of OpenID Connect Core 1.0.
The endpoint accepts an access token as a Bearer Token. That is, it accepts
an access token via Authorization: Bearer {access-token} or by a request
parameter access_token={access-token}. See RFC 6750 for details.
Access tokens to access the userinfo endpoint must have the openid scope
as required by the specification. Therefore, when you make an authorization
request to the authorization server, the scope parameter of the request
must contain openid like the following.
http://localhost:8080/api/authorization
?client_id={client-id}
&response_type=token
&scope=openid
&redirect_uri={redirect-uri}
The endpoint returns user information in JSON or JWT format, depending
on the configuration of the client application. If both
userinfo_signed_response_alg and userinfo_encrypted_response_alg of
the metadata of the client application are not specified, user information
is returned as a plain JSON. Otherwise, it is returned as a serialized JWT.
Authlete provides you with a Web console (Developer Console) to manage
metadata of client applications. As for metadata of client applications, see
2. Client Metadata in OpenID Connect Dynamic Client Registration 1.0.
User information returned from the endpoint contains claims of the user.
In short, claims are pieces of information about the user such as a given
name and an email address. Because Authlete does not manage user data (although
it supports OpenID Connect), you have to provide claim values. It is achieved
by implementing UserInfoRequestHandlerSpi interface.
In this resource server implementation, UserInfoRequestHandlerSpiImpl is
an example implementation of UserInfoRequestHandlerSpi interface and it
retrieves claim values from a dummy database. You need to modify the
implementation to make it refer to your actual user database.
The country endpoint implemented in this resource server is just an example
of a protected resource endpoint. Its main purpose is to show how to validate
an access token at a protected resource endpoint. To be concrete, the purpose
is to show usage of extractAccessToken method and validateAccessToken
method defined in BaseResourceEndpoint class.
The path of the country endpoint is /api/country/{country-code} where
{country-code} is an ISO 3166-1 code (alpha-2, alpha-3,
or numeric). For example, JP, JPN and 392 are valid ISO 3166-1
codes and all of them represent Japan. Therefore, the following URL is a
valid request to the country endpoint.
http://localhost:8081/api/country/JP?access_token={access-token}
The response from the endpoint is JSON that contains the following information
about the country identified by the {country-code}.
- Country name
- ISO 3166-1 alpha-2 code
- ISO 3166-1 alpha-3 code
- ISO 3166-1 numeric code
- Currency
The following is an example response.
{
"name": "Japan",
"alpha2": "JP",
"alpha3": "JPN",
"numeric": 392,
"currency": "JPY"
}As for generic and Authlete-specific information regarding how to protect Web APIs by OAuth access tokens, see Protected Resource in Authlete Definitive Guide.
The simplest way to add a new protected resource endpoint is to create a
subclass of SpringResourceEndpoint as CountryEndpoint does. However,
of course, it is okay for you to use AccessTokenValidator (in
authlete-java-jaxrs) or call
AuthleteApi.introspection(IntrospectionRequest) API (in
authlete-java-common) directly.
As you add new protected resource endpoints, you will want to add new scopes. Use Service Owner Console to add new scopes for your Web APIs.
- Authlete - Authlete Home Page
- authlete-java-common - Authlete Common Library for Java
- authlete-java-jaxrs - Authlete Library for JAX-RS (Java)
- spring-oauth-server - Authorization Server Implementation
| Purpose | Email Address |
|---|---|
| General | info@authlete.com |
| Sales | sales@authlete.com |
| PR | pr@authlete.com |
| Technical | support@authlete.com |