OAuth2.0 認可コードフロー導入ガイド

呼び出しシーケンス

概要

OAuth 2.0は広く利用されている認可プロトコルであり、サードパーティアプリケーションがユーザーの資格情報を公開することなく、ユーザーの同意を得てリソースにアクセスすることを可能にします。OAuth 2.0の認可コードフローでは、クライアントはユーザーを認証サーバーの認可エンドポイント（Authorization Endpoint）へ誘導し、ユーザーからの認可を取得する必要があります。

本ドキュメントでは、OAuth 2.0プロトコルに基づいた認可URLの組み立て方と使用方法を詳しく解説し、実例や注意事項を示します。

1. 認可コード取得用のURLの組み立て

認可URLの基本構造

認可URLは、クライアントが認証サーバーに対してリクエストを送信する際に使用するURLです。以下の要素で構成されています：

https://<authorization-server-domain>/oauth?
    response_type=<response_type>&
    clientId=<client_id>&
    redirectUri=<redirect_uri>&
    scope=<scope>&
    state=<state>

パラメータの説明

パラメータ名	必須かどうか	説明
`response_type`	必須	認可タイプ。通常は「 `code`（認可コードフローを使用していることを示す）
`clientId`	必須	クライアントの一意な識別子、つまり APP ID
`redirectUri`	必須	認可完了後のリダイレクト先アドレス。クライアント登録時のコールバックアドレスと一致している必要があります。
`scope`	必須	要求する権限スコープ。現在サポートされているのは`signature`、`stamp`、`comparisons`、認可後、eSignGlobalが提供する既存のopenapiを呼び出すことができます。複数のscopeは半角スペースで区切ってください。
`state`	任意	CSRF攻撃を防ぐためのランダム文字列。クライアントが生成し、コールバック時にその整合性を検証します。

認可URLの構築手順

認可サーバーアドレスの確認 サンドボックス環境：https://account-sml.esignglobal.com/oauth
本番環境：https://account.esignglobal.com/oauth
パラメータ値の設定 実際の要件に応じて各パラメータの値を設定してください。以下に例を示します：
- response_type: code
- clientId: your-client-id-12345
- redirectUri: https://your-app.com/callback
- scope: signature
- state: random-state-value
クエリパラメータの結合 上記のパラメータをキーと値のペアとして認可サーバーのアドレスに結合した後、 & 各パラメータを接続します。なお、パラメータ値はURLエンコードする必要があります。
結合結果の例：
```
https://account-sml.esignglobal.com/oauth?
    response_type=code&
    clientId=your-client-id-12345&
    redirectUri=https%3A%2F%2Fyour-app.com%2Fcallback&
    scope=signature&
    state=random-state-value
```
結合結果の確認 結合後のアドレスが以下の要件を満たしていることを確認してください：
- パラメータの順序は任意です
- パラメータ値が正しくURLエンコードされていること
- 必須パラメータがすべて含まれていること

サンプルコード

以下に、一般的なプログラミング言語での認可URL結合サンプルコードを示します：

Pythonの例

import urllib.parse

# 定义参数
base_url = "https://account-sml.esignglobal.com/oauth"
params = {
    "response_type": "code",
    "clientId": "your-client-id-12345",
    "redirectUri": "https://your-app.com/callback",
    "scope": "signature",
    "state": "random-state-value"
}

# 拼接地址
query_string = urllib.parse.urlencode(params)
authorization_url = f"{base_url}?{query_string}"
print(authorization_url)

JavaScriptの例

// 定义参数
const baseUrl = "https://account-sml.esignglobal.com/oauth";
const params = new URLSearchParams({
    response_type: "code",
    clientId: "your-client-id-12345",
    redirectUri: "https://your-app.com/callback",
    scope: "signature",
    state: "random-state-value"
});

// 拼接地址
const authorizationUrl = `${baseUrl}?${params.toString()}`;
console.log(authorizationUrl);

Javaの例

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class OAuthUrlBuilder {

    public static void main(String[ ] args) throws Exception {

        // 定义参数
        String baseUrl = "https://account-sml.esignglobal.com/oauth";
        String responseType = "code";
        String clientId = "your-client-id-12345";
        String redirectUri = "https://your-app.com/callback";
        String scope = "signature";
        String state = "random-state-value";

        // 拼接查询参数
        String queryString = String.format(
            "response_type=%s&clientId=%s&redirectUri=%s&scope=%s&state=%s",
            URLEncoder.encode(responseType, StandardCharsets.UTF_8),
            URLEncoder.encode(clientId, StandardCharsets.UTF_8),
            URLEncoder.encode(redirectUri, StandardCharsets.UTF_8),
            URLEncoder.encode(scope, StandardCharsets.UTF_8),
            URLEncoder.encode(state, StandardCharsets.UTF_8)
        );

        // 生成完整的授权地址
        String authorizationUrl = baseUrl + "?" + queryString;
        System.out.println(authorizationUrl);
    }
}

注意事項

認可URLの構築および使用時には、以下の点に注意してください：

URLエンコードの正確性 すべてのパラメータ値はURLエンコード（percent-encoding）により、特殊文字（例：「 :、/、? 」など）がURLの構造を損なわないようにします。例えば、https://your-app.com/callback は「」にエンコードする必要がありますhttps%3A%2F%2Fyour-app.com%2Fcallback。
リダイレクトURIの一貫性redirect_uri パラメータの値は、クライアントが認可サーバーに登録したリダイレクトURIと完全に一致している必要があります。プロトコル（http または https）、ホスト名、ポート、パスを含みます。そうでない場合、認可サーバーはリクエストを拒否します。
state パラメータのセキュリティstate パラメータはクロスサイトリクエストフォージェリ（CSRF）攻撃を防ぐために使用されます。クライアントはランダムで予測不可能な文字列を生成し、ユーザーの認可完了後にコールバック内の state の値が最初に送信された値と一致していることを検証する必要があります。
スコープの適切さscope パラメータはクライアントが要求するアクセス権限の範囲を定義します。実際のニーズに基づいて最小限の権限範囲を選択し、ユーザーリソースの過剰な要求を避けることで、ユーザーの信頼性を高めることができます。
環境区分 開発およびテスト段階では、通常サンドボックス環境（例： account-sml.esignglobal.com）、本番公開後は、本番環境（例： account.esignglobal.com）、各環境で正しい認可サーバーアドレスを使用していることを確認してください。
認可成功後の情報処理 認可が完了すると、eSignGlobal認可サービスはredirect_uri結合して返却しcodeとbaseUrl、baseUrlにより、認可者のデータが保存されているデータセンターを識別でき、openapiリクエストを実行する際は、該当するデータセンターに対してリクエストを送信する必要があります。
エラー処理 ユーザーが認可を拒否した場合やその他のエラーが発生した場合は、認可サーバーは redirect_uri エラー情報を返します（例： error および error_description パラメータ）。クライアントはこれらのエラーを適切に処理し、ユーザーに明確なフィードバックを提供する必要があります。

OAuth2.0 認可コードフロー 導入ガイド