Azure Fluid Relay 토큰 계약

2025-05-08

Azure Fluid Relay로 전송된 요청에는 권한 부여 헤더에 JWT가 포함되어야 합니다. 이 토큰은 테넌트 키로 서명해야 합니다.

클레임

JWT(JSON 웹 토큰)는 다음 세 부분으로 분할됩니다.

헤더 - 토큰 유형 및 토큰 서명 방법에 대한 정보를 포함하여 토큰의 유효성을 검사하는 방법에 대한 정보를 제공합니다.
페이로드 - 서비스를 호출하려는 사용자 또는 앱에 대한 모든 중요한 데이터를 포함합니다.
서명 - 토큰의 유효성을 검사하는 데 사용되는 원시 자료입니다.

각 파트는 마침표(.)로 구분되고 별도로 Base64로 인코딩됩니다.

헤더 클레임

클레임	포맷	설명
alg (은)	문자열	토큰에 서명하는 데 사용되는 알고리즘입니다. 예: "HS256"
일반	문자열	이 값은 항상 "JWT"여야 합니다.

페이로드 클레임

클레임	포맷	설명
문서 ID	문자열	AFR(Azure Fluid Relay) 서비스에서 생성됩니다. 토큰이 생성되는 문서를 식별합니다.
범위	문자열[]	문서 또는 요약에 대해 클라이언트가 요구하는 사용 권한을 식별합니다. 모든 범위에 대해 클라이언트에 부여하려는 권한을 정의할 수 있습니다.
테넌트ID	문자열	테넌트 식별
사용자	JSON (자바스크립트 객체 표기법)	애플리케이션의 사용자를 식별합니다. 애플리케이션에서 Fluid Framework 대상 그룹을 사용하여 사용자를 식별하는 데 사용할 수 있습니다. `{ id: <user_id>, name: <user_name>, additionalDetails: { email: <email>, date: <date>, }, }`
아이엣	number, UNIX 타임스탬프	"발급 시간"은 이 토큰에 대한 인증이 발생한 시간을 나타냅니다.
특급	number, UNIX 타임스탬프	"exp"(만료 시간) 클레임은 JWT가 처리를 위해 수락되어서는 안 되는 만료 시간을 식별합니다. 토큰 수명은 1시간을 초과할 수 없습니다.
버전	문자열	액세스 토큰의 버전을 나타냅니다. 이어야 `1.0` 합니다.
JTI	문자열	선택 사항입니다. "jti"(JWT ID) 클레임은 JWT에 대한 고유 식별자를 제공합니다. 식별자 값은 동일한 값이 실수로 다른 데이터 개체에 할당될 가능성이 무시할 수 있도록 하는 방식으로 할당되어야 합니다. 문서 만들기에 동일한 토큰을 사용했기 때문에 오류를 방지하기 위해 이 클레임을 사용하는 것이 좋습니다.

샘플 Azure Fluid Relay 토큰

{ 
  "alg": "HS256",  
  "typ": "JWT" 
}.{ 
  "documentId": "746c4a6f-f778-4970-83cd-9e21bf88326c", 
  "scopes": [ "doc:read", "doc:write", "summary:write" ],   
  "iat": 1599098963,  
  "exp": 1599098963,  
  "tenantId": "AzureFluidTenantId",  
  "ver": "1.0",
  "jti": "d7cd6602-2179-11ec-9621-0242ac130002"
}.[Signature]

Azure Fluid Relay 토큰을 생성하려면 어떻게 해야 합니까?

jsonwebtoken npm 패키지를 사용하고 이 메서드를 사용하여 토큰에 서명할 수 있습니다.

export function getSignedToken(
    tenantId: string,
    documentId: string,
    tokenLifetime: number = 60 * 60,
    ver: string = "1.0") {
        jwt.sign(
            {
                documentId, 
                user: {
                    displayName: "displayName", 
                    id: "userId", 
                    name: "userName" 
                }, 
                scopes: ["doc:read", "doc:write", "summary:write"], 
                iat: Math.round((new Date()).getTime() / 1000), 
                exp: Math.round((new Date()).getTime() / 1000) + tokenLifetime, //set the expiry date based on your needs but max-limit is one hour.
                tenantId, 
                ver,
                jti: uuid(), 
            },
            "<tenant_key>");
    }