Руководство по интеграции OAuth 2.0 в режиме авторизационного кода

Последовательность вызовов

Обзор

OAuth 2.0 — это широко используемый протокол авторизации, позволяющий сторонним приложениям получать доступ к ресурсам пользователя с его разрешения, не раскрывая учетные данные. В режиме кода авторизации OAuth 2.0 клиенту необходимо перенаправить пользователя на конечную точку авторизации (Authorization Endpoint) сервера авторизации для получения разрешения пользователя.

Настоящий документ подробно описывает процесс формирования и использования адреса авторизации в соответствии с протоколом OAuth 2.0, а также содержит практические примеры и рекомендации.

1. Формирование URL для получения кода авторизации

Базовая структура адреса авторизации

Адрес авторизации — это URL, который использует клиент при отправке запроса на сервер авторизации. Он состоит из следующих компонентов:

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

Описание параметров

Шаги формирования адреса авторизации

1. Определите адрес сервера авторизации Для среды песочницы: https://account-sml.esignglobal.com/oauth

   Для рабочей среды: https://account.esignglobal.com/oauth

2. Установка значений параметров В соответствии с фактическими потребностями установите значения каждого параметра. Ниже приведен пример:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Формирование параметров запроса После добавления вышеуказанных параметров в виде пар ключ-значение к адресу сервера авторизации используйте & для соединения каждого параметра. Обратите внимание, что значения параметров должны быть закодированы в формате 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

4. Проверка собранного результата Убедитесь, что итоговый адрес соответствует следующим требованиям:
   • Порядок параметров может быть любым
   • Значения параметров правильно закодированы в формате 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);
    }
}

Примечания

При формировании и использовании адреса авторизации следует обратить внимание на следующие моменты:

1. Корректность URL-кодирования Все значения параметров должны проходить URL-кодирование (percent-encoding), чтобы специальные символы (например, :、/、? и т. д.) не нарушали структуру URL. Например, https://your-app.com/callback должен быть закодирован как https%3A%2F%2Fyour-app.com%2Fcallback。
2. Согласованность адреса перенаправленияredirect_uri Значение параметра должно полностью совпадать с адресом перенаправления, зарегистрированным клиентом на сервере авторизации, включая протокол (http или https), имя хоста, порт и путь. В противном случае сервер авторизации отклонит запрос.
3. state Безопасность параметраstate Параметр используется для предотвращения атак подделки межсайтовых запросов (CSRF). Клиент должен сгенерировать случайную и непредсказуемую строку и после завершения авторизации пользователем проверить, соответствует ли значение в обратном вызове state первоначально отправленному значению.
4. Обоснованность области видимости прав доступаscope Параметр определяет область видимости прав доступа, запрашиваемую клиентом. Необходимо выбирать минимально необходимую область в соответствии с реальными потребностями, избегая избыточных запросов к ресурсам пользователя, что способствует повышению уровня доверия.
5. Разделение сред На этапах разработки и тестирования обычно используется среда песочницы (например, account-sml.esignglobal.com), после вывода продукта в промышленную эксплуатацию необходимо переключиться на производственную среду (например, account.esignglobal.com), чтобы гарантировать использование правильного адреса сервера авторизации в различных средах.
6. Обработка данных после успешной авторизации После завершения авторизации сервис авторизации eSignGlobal черезredirect_uriсоединит и вернетcodeиbaseUrl, с помощьюbaseUrlможно определить центр обработки данных, в котором находятся данные авторизовавшейся стороны; при выполнении запросов openapi необходимо инициировать запросы в соответствии с соответствующим центром обработки данных.
7. Обработка ошибок Если пользователь отклонил авторизацию или произошла другая ошибка, сервер авторизации через redirect_uri вернет информацию об ошибке (например, error и error_description параметры), клиент должен корректно обработать эти ошибки и предоставить пользователю четкую обратную связь.