diff --git a/README.ja.md b/README.ja.md index 4e3d3c287..96c8478da 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,8 +1,12 @@ + + + + Java 用 Authlete 共通ライブラリ -=============================== +================================ 概要 ----- +-------- このライブラリは [Authlete Web API][2] のラッパーです。 @@ -18,7 +22,7 @@ Java 用 Authlete 共通ライブラリ ライセンス ----------- +------- Apache License, Version 2.0 @@ -44,7 +48,7 @@ Maven ソースコード ------------- +----------- https://github.com/authlete/authlete-java-common @@ -56,7 +60,7 @@ JavaDoc 説明 ----- +----------- #### AuthleteApi の取得方法 @@ -388,7 +392,7 @@ ServiceListResponse response = api.getServiceList(); Authlete バージョン -------------------- +---------------- 幾つかの API や機能は、使用されている Authlete API サーバーがサポートしていなければ（たとえ `AuthleteApi` インターフェースで定義されているとしても）使うことができません。例えば、CIBA は @@ -424,7 +428,7 @@ Authlete 2.1 以降で利用できる機能： 曖昧なセッターメソッド群に対する自動アノテーション ------------------------------------------- +----------------------------------------------------- JSON デシリアライズに複数のセッターメソッドが存在する問題を解決するために、maven の build ステップに アノテーションプロセッサー (`JsonSetterAnnotationProcessor` クラス) が追加されました。 @@ -434,8 +438,10 @@ JSON デシリアライズに複数のセッターメソッドが存在する問 と合致するセッターメソッドに対してアノテーションが付与され、当該クラスに書き込まれます。 + + その他の情報 ------------- +-------- - [Authlete][1] - Authlete ホームページ - [JavaDoc][8] - このライブラリの JavaDoc @@ -446,16 +452,17 @@ JSON デシリアライズに複数のセッターメソッドが存在する問 コンタクト ----------- +------- | 目的 | メールアドレス | -|:-----|:---------------------| +|:----------|:---------------------| | 一般 | info@authlete.com | | 営業 | sales@authlete.com | | 広報 | pr@authlete.com | | 技術 | support@authlete.com | + [1]: https://www.authlete.com/ [2]: https://docs.authlete.com/ [3]: https://www.rfc-editor.org/rfc/rfc6749.html diff --git a/README.md b/README.md index b795cfbde..ea4923db4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ + + + + Authlete Common Library for Java ================================ diff --git a/README.src.md b/README.src.md new file mode 100644 index 000000000..725c18c2b --- /dev/null +++ b/README.src.md @@ -0,0 +1,739 @@ + + + + + + + + +${en:'Authlete Common Library for Java', ja:'Java 用 Authlete 共通ライブラリ'} +================================ + +${en:'Overview', ja:'概要'} +-------- + +This is a wrapper library for [Authlete Web APIs][2]. +このライブラリは [Authlete Web API][2] のラッパーです。 + +[Authlete][1] is a cloud service that provides an implementation of +[OAuth 2.0][3] & [OpenID Connect][4] ([overview][5]). 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. +[Authlete][1] は [OAuth 2.0][3] と [OpenID Connect][4] の実装を提供するクラウドサービスです +([overview][5])。 Authlete が提供する Web API を使い、DB-less (データベース無し) +の認可サーバーを構築することができます。「DB-less」とは、認可データ (アクセストークン等)、 +認可サーバーの設定、クライアントアプリケーションの設定を保存するデータベースを持つ必要が無い、という意味です。 +これらのデータはクラウド上にある Authlete サーバーに保存されます。 + +[java-oauth-server][6] is the reference implementation of an authorization +server written using this library and [authlete-java-jaxrs][7] library. +It is a good starting point for your own authorization server implementation. +[java-oauth-server][6] は、このライブラリおよび [authlete-java-jaxrs][7] +ライブラリを用いて書かれた、認可サーバーのリファレンス実装です。 +あなたの認可サーバー実装の開始点として活用してください。 + + +${en:'License', ja:'ライセンス'} +------- + + Apache License, Version 2.0 + + JSON files under `src/test/resources/ekyc-ida` have been copied from + https://bitbucket.org/openid/ekyc-ida/src/master/examples/response/ . + Regarding their license, ask the eKYC-IDA WG of OpenID Foundation. + `src/test/resources/ekyc-ida` 以下の JSON ファイル群は + https://bitbucket.org/openid/ekyc-ida/src/master/examples/response/ + からコピーしたものです。それらのライセンスについては、OpenID Foundation の + eKYC-IDA ワーキンググループにお尋ねください。 + + +Maven +----- + +```xml + + com.authlete + authlete-java-common + \${authlete-java-common.version} + +``` + +Please refer to the [CHANGES.md](CHANGES.md) file to know the latest version +to write in place of `\${authlete-java-common.version}`. +`\${authlete-java-common.version}` の箇所に書き込む最新バージョンについては +[CHANGES.ja.md](CHANGES.ja.md) ファイルを参照してください。 + + +${en:'Source Code', ja:'ソースコード'} +----------- + + https://github.com/authlete/authlete-java-common + + +JavaDoc +------- + + https://authlete.github.io/authlete-java-common/ + + +${en:'Description', ja:'説明'} +----------- + +#### ${en:'How To Get AuthleteApi', ja:'AuthleteApi の取得方法'} + +All the methods to communicate with [Authlete Web APIs][2] 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. +[Authlete Web API][2] とやりとりするメソッドは全て `AuthleteApi` インターフェースに集められています。 +`AuthleteApiFactory` クラスの `create()` メソッドを呼ぶと、`AuthleteApi` の実装を取得できます。 +このメソッドには二つのバリアントがあります。 + +```java +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. +どちらのメソッドも `AuthleteConfiguration` を第一引数として受け取ります。 +`AuthleteConfiguration` は、Authlete サーバーの URL やサービスの API クレデンシャルズなどの、Authlete +Web API にアクセスするのに必要な設定値を保持するインターフェースです。 +具体的には、このインターフェースには次のようなメソッド群があります。 + +| Method | Authlete Version | Description | +|:-----------------------------|:------------------|:---------------------------| +| `getBaseUrl()` | Common | URL of Authlete server | +| `getServiceApiKey()` | Common | API key of a service | +| `getServiceApiSecret()` | Up to version 2.x | API secret of a service | +| `getServiceOwnerApiKey()` | Up to version 2.x | API key of your account | +| `getServiceOwnerApiSecret()` | Up to version 2.x | API secret of your account | +| `getApiVersion()` | Since version 3.0 | API version | +| `getServiceAccessToken()` | Since version 3.0 | API access token | +| メソッド | Authlete バージョン | 説明 | +|:-----------------------------|:--------------------|:--------------------------------------| +| `getBaseUrl()` | 共通 | Authlete サーバーの URL | +| `getServiceApiKey()` | 共通 | サービスの API キー | +| `getServiceApiSecret()` | バージョン 2.x まで | サービスの API シークレット | +| `getServiceOwnerApiKey()` | バージョン 2.x まで | あなたのアカウントの API キー | +| `getServiceOwnerApiSecret()` | バージョン 2.x まで | あなたのアカウントの API シークレット | +| `getApiVersion()` | バージョン 3.0 以降 | Authlete API のバージョン | +| `getServiceAccessToken()` | バージョン 3.0 以降 | あなたの API アクセストークン | + +authlete-java-common library includes three implementations of +`AuthleteConfiguration` interface as listed below. +authlete-java-common ライブラリには、`AuthleteConfiguration` インターフェースの実装が三つ含まれています。 + +| Class | Description | +|:----------------------------------|:----------------------------------------| +| `AuthleteEnvConfiguration` | Configuration via environment variables | +| `AuthletePropertiesConfiguration` | Configuration via a properties file | +| `AuthleteSimpleConfiguration` | Configuration via POJO | +| クラス | 説明 | +|:----------------------------------|:-------------------------------| +| `AuthleteEnvConfiguration` | 環境変数による設定 | +| `AuthletePropertiesConfiguration` | プロパティーファイルによる設定 | +| `AuthleteSimpleConfiguration` | POJO による設定 | + +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. +これらの実装を使うこともできますし、インターフェースの実装を自分で作成することもできます。 +いずれにしても、`AuthleteConfiguration` インスタンスを `AuthleteApiFactory` クラスの +`create()` メソッドに渡すことで、`AuthleteApi` の実装を取得することができます。 + +In summary, the flow to get an implementation of `AuthleteApi` becomes like below. +まとめると、`AuthleteApi` の実装を取得する流れは次のようになります。 + +```java +// Prepare an instance of AuthleteConfiguration interface. +// AuthleteConfiguration インターフェースのインスタンスを用意する。 +AuthleteConfiguration configuration = ...; + +// Get an instance of AuthleteApi interface. +// AuthleteApi インターフェースのインスタンスを取得する。 +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. +より簡単な方法がよければ、`AuthleteApiFactory.getDefaultApi()` メソッドを使用してください。 +このメソッドは、ファイルシステムとクラスパスから、`authlete.properties` +という名前のプロパティーファイルを探し、`AuthletePropertiesConfiguration` +クラスを使ってそのファイルの内容を読み込みます。 + +```java +// Search the file system and the classpath for "authlete.properties". +//ファイルシステムとクラスパスから "authlete.properties" を探す。 +AuthleteApi api = AuthleteApiFactory.getDefaultApi(); +``` + +`AuthleteApiFactory.getDefaultApi()` method caches the search result, so you can +call the method as many times as you like without worrying about the overhead of +file loading. +`AuthleteApiFactory.getDefaultApi()` メソッドは結果をキャッシュするので、 +ファイルを読み込む処理のオーバーヘッドを気にせずに何回でも呼ぶことができます。 + + +#### AuthletePropertiesConfiguration + +Among the three implementations of `AuthleteConfiguration` interface, this section +explains `AuthletePropertiesConfiguration` class. +`AuthleteConfiguration` インターフェースの三つの実装のうち、ここでは +`AuthletePropertiesConfiguration` クラスについて説明します。 + +`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. +`AuthletePropertiesConfiguration` クラスは、Authlete Web API +へのアクセスに必要な設定をプロパティーファイルでおこなう仕組みを提供します。 +このクラスは、ファイルシステムとクラスパスから指定されたファイルを探します。 + +Valid property keys in a properties file and their meanings are as follows. +プロパティーファイル内で有効なプロパティーキーとその意味は次のとおりです。 + +| Property Key | Description | +|:-------------------------------------|:-------------------------------------| +| `base_url` | URL of Authlete server | +| `service.api_key` | API key of a service | +| `service.api_secret` | API secret of a service | +| `service.api_secret.encrypted` | Encrypted API secret of a service | +| `service_owner.api_key` | API key of your account | +| `service_owner.api_secret` | API secret of your account | +| `service_owner.api_secret.encrypted` | Encrypted API secret of your account | +| `api_version` | API version. "V3" for Authlete 3.0 | +| `service.access_token` | API access token | +| プロパティーキー | 説明 | +|:-------------------------------------|:------------------------------------------------------| +| `base_url` | Authlete サーバーの URL | +| `service.api_key` | サービスの API キー | +| `service.api_secret` | サービスの API シークレット | +| `service.api_secret.encrypted` | サービスの API シークレットを暗号化したもの | +| `service_owner.api_key` | あなたのアカウントの API キー | +| `service_owner.api_secret` | あなたのアカウントの API シークレット | +| `service_owner.api_secret.encrypted` | あなたのアカウントの API シークレットを暗号化したもの | +| `api_version` | Authlete API バージョン。3.0 用には "V3" を指定する。 | +| `service.access_token` | あなたの API アクセストークン | + +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][8] for details. +API シークレットを平文で書きたくなければ、`*.api_secret` キーのかわりに +`*.api_secret.encrypted` キーを使用してください。 暗号化したシークレットを +`*.encrypted` キーに設定することができます。 +ただしこの場合、暗号化された値を復号化するため、`AuthletePropertiesConfiguration` +のコンストラクタに暗号化キーと初期ベクターを渡す必要があります。 詳細は +[JavaDoc][8] を参照してください。 + + +#### ${en:'AuthleteApi Implementation', ja:'AuthleteApi の実装'} + +Since version 2.0, authlete-java-common library includes an implementation of +`AuthleteApi` interface using `HttpURLConnection`. Before version 2.0, +[authlete-java-jaxrs][7] which contains an implementation of `AuthleteApi` was +additionally needed. +authlete-java-common ライブラリのバージョン 2.0 以降には、`HttpURLConnection` による +`AuthleteApi` インターフェースの実装が含まれています。バージョン 2.0 以前は `AuthleteApi` +インターフェースの実装を含む [authlete-java-jaxrs][7] ライブラリが別途必要でした。 + +`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). +`AuthleteApiFactory.create()` メソッドは既知の場所を探し、`AuthleteApi` +の実装をリフレクションを使ってロードします。 リフレクションを使用する理由は、特定の実装 +(例えば authlete-java-jaxrs 内の JAX-RS ベースの実装) に依存しないようにするためです。 + +As of this writing, known implementations of `AuthleteApi` interface are as +follows. +現時点で `AuthleteApi` インターフェースの既知の実装は次の二つです。 + + 1. `com.authlete.jaxrs.api.AuthleteApiImpl` (in [authlete-java-jaxrs][7]) + 2. `com.authlete.common.api.AuthleteApiImpl` (in authlete-java-common) + +`AuthleteApiFactory` checks existence of the above classes in this order. +`AuthleteApiFactory` は上記の順番で実装を検索しにいきます。 + + +#### AuthleteApi Settings +### AuthleteApi の設定 + +`getSettings()` method of `AuthleteApi` interface has been available since +the version 2.9. By configuring the instance returned by the method, you can +change behaviours of the implementation of `AuthleteApi` interface. +バージョン 2.9 で `AuthleteApi` に `getSettings()` メソッドが追加されました。 +このメソッドが返す `Settings` インスタンスの設定を変更することにより、`AuthleteApi` +インターフェースの実装の動作を変更することができます。 + +*${en:'Examples', ja:'例'}* + +```java +// An implementation of AuthleteApi interface. +// AuthleteApi インターフェースの実装 +AuthleteApi api = ...; + +// Get the instance which holds settings of the AuthleteApi implementation. +// AuthleteApi 実装の設定を保持するインスタンスを取得する。 +Settings settings = api.getSettings(); + +// Set a connection timeout in milliseconds. +// +// Note: +// There is no standard way to set a connection timeout value +// before JAX-RS API 2.1 (which is a part of Java EE 8). +// Therefore, if authlete-java-jaxrs is used as AuthleteApi +// implementation and if the JAX-RS Client implementation is +// not supported by the implementation of setConnectionTimeout() +// of authlete-java-jaxrs, the value given to setConnectionTimeout() +// won't have any effect. See README in authlete-java-jaxrs +// for details. +// +// 接続タイムアウト値をミリ秒単位で設定する。 +// +// 注意： +// Java EE 8 の一部となっている JAX-RS API 2.1 より前は、接続タイムアウトを +// 設定する方法が標準化されていません。 そのため、AuthleteApi の実装として +// authlete-java-jaxrs が使用されていて、かつ authlete-java-jaxrs の +// setConnectionTimeout() の実装がサポートしていない JAX-RS Client 実装が +// 使われている場合、setConnectionTimeout() の設定は効きません。詳細は +// authlete-java-jaxrs の README を参照してください。 +// +settings.setConnectionTimeout(5000); + +// Set a read timeout in milliseconds. +// +// Note: +// There is no standard way to set a read timeout value before +// JAX-RS API 2.1 (which is a part of Java EE 8). Therefore, +// if authlete-java-jaxrs is used as AuthleteApi implementation +// and if the JAX-RS Client implementation is not supported by +// the implementation of setReadTimeout() of authlete-java-jaxrs, +// the value given to setReadTimeout() won't have any effect. +// See README in authlete-java-jaxrs for details. +// +// リードタイムアウト値をミリ秒単位で設定する。 +// +// 注意： +// Java EE 8 の一部となっている JAX-RS API 2.1 より前は、リードタイムアウトを +// 設定する方法が標準化されていません。 そのため、AuthleteApi の実装として +// authlete-java-jaxrs が使用されていて、かつ authlete-java-jaxrs の +// setReadTimeout() の実装がサポートしていない JAX-RS Client 実装が使われて +// いる場合、setReadTimeout() の設定は効きません。 詳細は authlete-java-jaxrs +// の README を参照してください。 +// +settings.setReadTimeout(5000); +``` + + +#### ${en:'AuthleteApi Method Categories', ja:'AuthleteApi メソッドのカテゴリー'} + +Methods in `AuthleteApi` interface can be divided into some categories. +`AuthleteApi` インターフェースのメソッド群は幾つかのカテゴリーに分けることができます。 + + 1. Methods for Authorization Endpoint Implementation + 1. 認可エンドポイント実装のためのメソッド群 + + - `authorization(AuthorizationRequest request)` + - `authorizationFail(AuthorizationFailRequest request)` + - `authorizationIssue(AuthorizationIssueRequest request)` + + 2. Methods for Token Endpoint Implementation + 2. トークンエンドポイント実装のためのメソッド群 + + - `token(TokenRequest request)` + - `tokenFail(TokenFailRequest request)` + - `tokenIssue(TokenIssueRequest request)` + - `idTokenReissue(IDTokenReissueRequest request)` + + 3. Methods for Service Management + 3. サービス管理のためのメソッド群 + + - `createService(Service service)` + - `deleteService(long serviceApiKey)` + - `getService(long serviceApiKey)` + - `getServiceList()` + - `getServiceList(int start, int end)` + - `updateService(Service service)` + + 4. Methods for Client Application Management + 4. クライアントアプリケーション管理のためのメソッド群 + + - `createClient(Client client)` + - `deleteClient(long clientId)` + - `deleteClient(String clientId)` + - `getClient(long clientId)` + - `getClient(String clientId)` + - `getClientList()` + - `getClientList(int start, int end)` + - `updateClient(Client client)` + - `refreshClientSecret(long clientId)` + - `refreshClientSecret(String clientIdentifier)` + - `updateClientSecret(long clientId, String clientSecret)` + - `updateClientSecret(String clientIdentifier, String clientSecret)` + + 5. Methods for Access Token Introspection + 5. アクセストークンの情報取得のためのメソッド群 + + - `introspection(IntrospectionRequest request)` + - `standardIntrospection(StandardIntrospectionRequest request)` + - `getTokenList()` + - `getTokenList(String clientIdentifier, String subject)` + - `getTokenList(int start, int end)` + - `getTokenList(String clientIdentifier, String subject, int start, int end)` + - `getTokenList(TokenStatus)` + - `getTokenList(int start, int end, TokenStatus tokenStatus)` + - `getTokenList(String clientIdentifier, String subject, TokenStatus tokenStatus)` + - `getTokenList(String clientIdentifier, String subject, int start, int end, TokenStatus tokenStatus)` + + 6. Methods for Revocation Endpoint Implementation + 6. アクセストークン取り消しエンドポイント実装のためのメソッド群 + + - `revocation(RevocationRequest request)` + + 7. Methods for User Info Endpoint Implementation + 7. ユーザー情報エンドポイント実装のためのメソッド群 + + - `userinfo(UserInfoRequest request)` + - `userinfoIssue(UserInfoIssueRequest request)` + + 8. Methods for JWK Set Endpoint Implementation + 8. JWK セットエンドポイント実装のためのメソッド群 + + - `getServiceJwks()` + - `getServiceJwks(boolean pretty, boolean includePrivateKeys)` + + 9. Methods for OpenID Connect Discovery + 9. OpenID Connect Discovery のためのメソッド群 + + - `getServiceConfiguration()` + - `getServiceConfiguration(boolean pretty)` + + 10. Methods for Token Operations + 10. トークン操作のためのメソッド群 + + - `tokenCreate(TokenCreateRequest request)` + - `tokenDelete(String token)` + - `tokenRevoke(TokenRevokeRequest request)` + - `tokenUpdate(TokenUpdateRequest request)` + - `tokenCreateBatch(TokenCreateRequest[] request)` + - `getTokenCreateBatchStatus(String requestId)` + + 11. Methods for Requestable Scopes per Client (deprecated; Client APIs suffice) + 11. クライアント毎の要求可能スコープ群に関するメソッド群 (非推奨; Client API で代替可能) + + - `getRequestableScopes(long clientId)` + - `setRequestableScopes(long clientId, String[] scopes)` + - `deleteRequestableScopes(long clientId)` + + 12. Methods for Records of Granted Scopes + 12. 付与されたスコープの記録に関するメソッド群 + + - `getGrantedScopes(long clientId, String subject)` + - `deleteGrantedScopes(long clientId, String subject)` + + 13. Methods for Authorization Management on a User-Client Combination Basis + 13. ユーザー・クライアント単位の認可管理に関するメソッド群 + + - `deleteClientAuthorization(long clientId, String subject)` + - `getClientAuthorizationList(ClientAuthorizationGetListRequest request)` + - `updateClientAuthorization(long clientId, ClientAuthorizationUpdateRequest request)` + + 14. Methods for JOSE + 14. JOSE に関するメソッド群 + + - `verifyJose(JoseVerifyRequest)` + + 15. Methods for CIBA (Client Initiated Backchannel Authentication) + 15. CIBA (Client Initiated Backchannel Authentication) に関するメソッド群 + + - `backchannelAuthentication(BackchannelAuthenticationRequest)` + - `backchannelAuthenticationIssue(BackchannelAuthenticationIssueRequest)` + - `backchannelAuthenticationFail(BackchannelAuthenticationFailRequest)` + - `backchannelAuthenticationComplete(BackchannelAuthenticationCompleteRequest)` + + 16. Methods for OpenID Connect Dynamic Client Registration + 16. OpenID Connect Dynamic Client Registration に関するメソッド群 + + - `dynamicClientRegister(ClientRegistrationRequest)` + - `dynamicClientGet(ClientRegistrationRequest)` + - `dynamicClientUpdate(ClientRegistrationRequest)` + - `dynamicClientDelete(ClientRegistrationRequest)` + + 17. Methods for Device Flow + 17. Device Flow に関するメソッド群 + + - `deviceAuthorization(DeviceAuthorizationRequest)` + - `deviceComplete(DeviceCompleteRequest)` + - `deviceVerification(DeviceVerificationRequest)` + + 18. Methods for Pushed Authorization Requests + 18. Pushed Authorization Requests に関するメソッド群 + + - `pushAuthorizationRequest(PushedAuthReqRequest)` + + 19. Methods for Grant Management for OAuth 2.0 + 19. Grant Management for OAuth 2.0 に関するメソッド群 + + - `gm(GMRequest)` + + 20. Methods for OpenID Connect Federation 1.0 + 20. OpenID Connect Federation 1.0 に関するメソッド群 + + - `federationConfiguration(FederationConfigurationRequest)` + - `federationRegistration(FederationRegistrationRequest)` + + 21. Methods for Verifiable Credentials + 21. Verifiable Credentials に関するメソッド群 + + - `credentialIssuerMetadata(CredentialIssuerMetadataRequest)` + - `credentialIssuerJwks(CredentialIssuerJwksRequest)` + - `credentialJwtIssuerMetadata(CredentialJwtIssuerMetadataRequest)` + - `credentialOfferCreate(CredentialOfferCreateRequest)` + - `credentialOfferInfo(CredentialOfferInfoRequest)` + - `credentialSingleParse(CredentialSingleParseRequest)` + - `credentialSingleIssue(CredentialSingleIssueRequest)` + - `credentialBatchParse(CredentialBatchParseRequest)` + - `credentialBatchIssue(CredentialBatchIssueRequest)` + - `credentialDeferredParse(CredentialDeferredParseRequest)` + - `credentialDeferredIssue(CredentialDeferredIssueRequest)` + - `credentialNonce(CredentialNonceRequest)` + + 22. Methods for OpenID Connect Native SSO for Mobile Apps 1.0 + 22. OpenID Connect Native SSO for Mobile Apps 1.0 に関するメソッド群 + + - `nativeSso(NativeSsoRequest)` + - `nativeSsoLogout(NativeSsoLogoutRequest)` + + 23. Methods for OAuth 2.0 Attestation-Based Client Authentication + 23. OAuth 2.0 Attestation-Based Client Authentication に関するメソッド群 + + - `attestationChallenge(AttestationChallengeRequest)` + +*${en:'Examples', ja:'例'}* + +The following code snippet is an example to get the list of your existing +services. Each service corresponds to an authorization server. +次のコードは既存のサービスのリストを取得する例です。 +各サービスは一つの認可サーバーに対応します。 + +```java +// Get an implementation of AuthleteApi interface. +// AuthleteApi インターフェースの実装を取得する。 +AuthleteApi api = AuthleteApiFactory.getDefaultApi(); + +// Get the list of services. +// サービスのリストを取得する。 +ServiceListResponse response = api.getServiceList(); +``` + + +${en:'Authlete Version', ja:'Authlete バージョン'} +---------------- + +Some APIs and features don't work (even if they are defined in the `AuthleteApi` +interface) if Authlete API server you use doesn't support them. For example, +CIBA works only in Authlete 2.1 onwards. Please contact us if you want to use +newer Authlete versions. +幾つかの API や機能は、使用されている Authlete API サーバーがサポートしていなければ（たとえ +`AuthleteApi` インターフェースで定義されているとしても）使うことができません。例えば、CIBA は +Authlete 2.1 以降でのみ機能します。新しい Authlete バージョンを使用されたい場合は、ご連絡ください。 + +Features available in Authlete 2.0 and onwards: +Authlete 2.0 以降で利用できる機能： + +- Financial-grade API (FAPI) +- OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens (MTLS) +- JWT-based Client Authentication (RFC 7523) +- Scope attributes +- UK Open Banking Security Profile + +Features available in Authlete 2.1 and onwards: +Authlete 2.1 以降で利用できる機能： + +- Client Initiated Backchannel Authentication (CIBA) +- JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) +- Dynamic Client Registration (RFC 7591 & RFC 7592) +- OAuth 2.0 Device Authorization Grant (Device Flow) +- JWT-based Access Token + +See [Spec Sheet](https://www.authlete.com/legal/spec_sheet/) for further details. +詳細情報は [スペックシート](https://www.authlete.com/ja/legal/spec_sheet/) +を参照してください。 + + +${en:'Note', ja:'メモ'} +---- + +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][7] library. See [java-oauth-server][6] for an example of +an authorization server implementation written using the utility classes. +`AuthleteApi` インターフェースのメソッドだけを用いて認可サーバーを書くこともできますが、 +[authlete-java-jaxrs][7] ライブラリのユーティリティークラス群を用いれば、作業はずっと楽になります。 +ユーティリティークラス群を使って書かれた認可サーバー実装の例については、[java-oauth-server][6] +を参照してください。 + + +${en:'Automatic Annotation of Ambiguous Json Setter Methods', ja:'曖昧なセッターメソッド群に対する自動アノテーション'} +----------------------------------------------------- + +To address the "multiple ambiguous setter methods" json deserialization issue. +An annotation processor has been added to the maven build step and will run +during the `process-classes` maven phase. +The `JsonSetterAnnotationProcessor` class is responsible for this process. +The process involves iterating over all classes in the DTO package. Then +finding any ambiguously defined setter methods (setter methods defined with +the same name) which do not have any `@JsonSetter` annotation defined. If +there are setters found that match these criteria, the correct setter method +to annotate will be determined by matching the first argument of the setter +method with the return type of the matching getter method. +The new annotation is then added to the identified setter method and written +to the existing class file. +JSON デシリアライズに複数のセッターメソッドが存在する問題を解決するために、maven の build ステップに +アノテーションプロセッサー (`JsonSetterAnnotationProcessor` クラス) が追加されました。 +本プロセッサーは `process-classes` フェーズ時に実行され、DTO パッケージ内の全クラスを走査し、 +曖昧なセッターメソッド (`@JsonSetter` アノテーションが定義されていないセッターメソッド) を検出します。 +仮に当該クラス内にそのようなメソッドが複数存在する場合、最初の引数の型が「ゲッターメソッドの返り値の型」 +と合致するセッターメソッドに対してアノテーションが付与され、当該クラスに書き込まれます。 + + +Code Quality Tools +----------------- + +The project now includes several code quality tools to maintain high standards: + +1. **Checkstyle** + - Added via maven-checkstyle-plugin + - Custom rules defined in `checkstyle.xml` + - Enforces coding standards and improves code quality + +2. **SpotBugs** + - Configuration split into include and exclude files + - `spotbugs-exclude.xml`: Defines patterns to exclude from analysis + - `spotbugs-include.xml`: Contains rules for various bug categories + +3. **Dependencies** + - Updated nimbus-jose-jwt to version 9.31 + - Added new dependencies for enhanced security and functionality + +These tools are configured to run during the build process and help maintain code quality across the project. + +**Quality Standards for Contributors:** + +- **Code Review**: All changes must pass automated quality checks before submission +- **Testing**: Maintain test coverage and ensure all tests pass +- **Documentation**: Keep code documentation current and comprehensive +- **Performance**: Consider impact on performance and optimize where necessary +- **Security**: Follow security best practices and validate all inputs +- **Compatibility**: Maintain backward compatibility unless breaking changes are necessary +- **Standards**: Follow established coding conventions and project guidelines + + +Contributing Guidelines +---------------------- + +To maintain high code quality standards, please follow these guidelines when contributing to the project: + +1. **Code Style** + - Follow the Checkstyle rules defined in `checkstyle.xml` + - Use consistent indentation and formatting + - Follow Java naming conventions + - Keep methods and classes focused and well-documented + +2. **Code Quality Checks** + - Run `mvn checkstyle:check` to verify code style compliance + - Run `mvn spotbugs:check` to detect potential bugs + - Ensure all tests pass before submitting changes + - Address any warnings or errors from quality tools + +3. **Documentation** + - Update relevant documentation when adding new features + - Include JavaDoc comments for public methods and classes + - Update README.md if introducing new functionality + - Provide clear commit messages + +4. **Testing** + - Write unit tests for new functionality + - Ensure existing tests continue to pass + - Test with different Authlete API versions when applicable + +5. **Security** + - Follow security best practices + - Validate all inputs + - Use secure coding patterns + - Review for potential vulnerabilities + +6. **Performance** + - Consider performance implications of changes + - Use efficient algorithms and data structures + - Avoid unnecessary object creation + - Profile critical code paths when needed + +7. **Compatibility** + - Maintain backward compatibility when possible + - Test with supported Java versions + - Verify compatibility with Authlete API versions + - Document any breaking changes + +8. **Review Process** + - Self-review your changes before submission + - Ensure code follows project conventions + - Address feedback from code reviews promptly + - Keep pull requests focused and manageable + +For questions about these guidelines or the development process, please reach out to the development team. + + +${en:'See Also', ja:'その他の情報'} +-------- + +- [Authlete][1] - Authlete Home Page +- [JavaDoc][8] - JavaDoc of this library +- [authlete-java-jaxrs][7] - Authlete Library for JAX-RS (Java) +- [java-oauth-server][6] - Authorization Server Implementation +- [java-resource-server][9] - Resource Server Implementation +- [New Architecture of OAuth 2.0 and OpenID Connect Implementation][10] - Explanation about Authlete Architecture +- [Authlete][1] - Authlete ホームページ +- [JavaDoc][8] - このライブラリの JavaDoc +- [authlete-java-jaxrs][7] - JAX-RS (Java) 用 Authlete ライブラリ +- [java-oauth-server][6] - 認可サーバー実装 +- [java-resource-server][9] - リソースサーバー実装 +- [OAuth 2.0 / OIDC 実装の新アーキテクチャー][10] - Authlete アーキテクチャー解説 + + +${en:'Contact', ja:'コンタクト'} +------- + +| ${en:'Purpose ', ja:'目的'} | ${en:'Email Address ', ja:'メールアドレス '} | +|:----------|:---------------------| +| ${en:'General ', ja:'一般'} | info@authlete.com | +| ${en:'Sales ', ja:'営業'} | sales@authlete.com | +| ${en:'PR ', ja:'広報'} | pr@authlete.com | +| ${en:'Technical', ja:'技術'} | support@authlete.com | + + + +[1]: https://www.authlete.com/ +[2]: https://docs.authlete.com/ +[3]: https://www.rfc-editor.org/rfc/rfc6749.html +[4]: https://openid.net/connect/ +[5]: ${ref5} +[6]: https://github.com/authlete/java-oauth-server +[7]: https://github.com/authlete/authlete-java-jaxrs +[8]: https://authlete.github.io/authlete-java-common/ +[9]: https://github.com/authlete/java-resource-server +[10]: ${ref10} diff --git a/pom.xml b/pom.xml index f79582923..6e69df01a 100644 --- a/pom.xml +++ b/pom.xml @@ -252,6 +252,26 @@ + + com.nanolaba + nrg-maven-plugin + 1.1 + + + README.src.md + + false + + + + compile + + create-files + + + + + org.apache.maven.plugins maven-source-plugin