OAuth2.0 인가 코드 모드 연동 가이드

호출 시퀀스

개요

OAuth 2.0은 널리 사용되는 인가 프로토콜로, 사용자의 자격 증명을 노출하지 않고도 사용자의 승인을 통해 제3자 애플리케이션이 리소스에 접근할 수 있도록 합니다. 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 인코딩됨
- 모든 필수 파라미터가 포함됨

예제 코드

다음은 몇 가지 일반적인 프로그래밍 언어에서 인증 주소를 조합하는 예제 코드입니다:

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。
콜백 주소의 일치성redirect_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파라미터), 클라이언트는 이러한 오류를 적절히 처리하여 사용자에게 명확한 피드백을 제공해야 합니다.