문서 메뉴

문서 홈Atlas App Services

사용자 지정 JWT 인증

이 페이지의 내용

  • 인증 및 권한 부여
  • JWT 인증 작동 방식
  • 구성
  • 인증 방법
  • 서명 키 수동 지정하기
  • JWK URI 사용
  • 메타데이터 필드
  • 오디언스
  • JWT 인증 사용
  • Realm SDK
  • API 서비스

사용자 지정 JWT 인증 제공자를 사용하면 사용자가 타사 시스템(Atlas App Services 외부)의 인증 자격 증명으로 로그인하고 해당 토큰을 사용하여 App Services의 데이터 및 서비스에 액세스할 수 있습니다. 외부 시스템은 서명된 JSON Web Token(JWT) 을 반환해야 합니다. 인증된 사용자의 고유 ID 값을 포함합니다.

타사 JWT 제공자는 사용자를 인증하고 JWT를 반환합니다. App Services는 JWT를 사용하여 애플리케이션의 사용자를 식별하고 해당 요청에 권한을 부여합니다.

App Services는 서드파티 제공자가 사용하는 인증 방법에 구애받지 않습니다. 외부 인증 시스템의 요구 사항이나 인증 방법에 어떠한 제한도 두지 않습니다. 예를 들어 시스템에서 사용자에게 다중 인증(MFA)을 수행하거나, 특정 자격 증명을 제공하거나, 기타 방식으로 신원을 확인하도록 요구할 수 있습니다.

JWT 인증과 토큰 구조의 복잡성에 대해 자세히 알아볼 수 있는 온라인 리소스가 많이 있습니다. App Services와 관련하여 다음 다이어그램은 사용자가 Device Sync 앱에 로그인하는 프로세스 흐름을 제공합니다. 다이어그램 아래 단계에 자세한 내용이 나와 있습니다.

사용자 지정 JWT 인증 아키텍처 다이어그램.
클릭하여 확대

App Services를 사용한 JWT 인증은 일반적으로 다음 단계를 따릅니다.

  1. 사용자는 제공자가 요구하는 모든 수단을 통해 인증 제공자에 로그인합니다.

  2. 인증이 성공하면 해당 제공자가 JWT를 클라이언트 앱에 반환하게 됩니다.

  3. 이 클라이언트 앱은 App Services 앱에 로그온하여 JWT 자격 증명을 제공합니다.

  4. App Services는 JWT를 구문 분석하고 디코딩합니다.

  5. App Services에서 서명 키를 수동으로 제공한 경우, App Services는 JWT의 서명 키가 지정한 서명 키 중 하나와 일치하는지 확인합니다. 일치하는 경우 사용자가 인증됩니다.

  6. 앱 서비스가 JWK(JSON 웹 키) URI를 사용하도록 구성한 경우, 앱 서비스는 타사 공급업체의 JWK API에 JWT 및 공개 키를 전달합니다.

    1. 제공자는 서명을 디코딩 및 확인하고 JWK를 반환합니다.

    2. App Services는 JWK의 서명이 JWT의 서명과 일치하는지 확인합니다. 일치하는 경우 사용자가 인증됩니다.

중요

액세스 토큰은 항상 30분 후에 만료됩니다

사용자 지정 JWT 토큰이 exp 키를 통해 다른 만료를 지정하더라도 App Services는 항상 30분 액세스 토큰 만료를 지정합니다. App Services에서 사용자 지정 JWT 토큰 exp를 확인하여 30분 만료를 발행하기 전에 토큰이 여전히 유효한지 확인합니다. App Services 액세스 토큰에 대한 자세한 내용은 사용자 세션 관리를 참조하세요.

UI에서 또는 CLI를 사용하여 사용자 정의 JWT 인증을 구성합니다. 아래에서 선호하는 방법을 선택하세요.

Verification Method 필드는 App Services가 JWT 공급자로부터 반환된 JWT의 유효성 검사 방법을 결정합니다. 본인이 제공한 서명 키를 사용하여 App Services가 JWT의 유효성을 검사하거나 타사 제공자가 발급한 JSON 웹 키(JWK) URI를 사용하여 유효성을 검사하도록 구성할 수 있습니다.

하나 이상의 서명 키를 사용하여 JWT의 유효성을 검사하도록 앱을 구성할 수 있습니다. 제공해야 하는 설정은 다음 두 가지입니다.

필드
설명
Signing Algorithm
config.signingAlgorithm

외부 시스템이 JWT에 서명하는 데 사용하는 암호화 방법입니다. 사용자 지정 인증은 다음 알고리즘 중 하나를 사용하여 서명된 JWT를 지원합니다.

  • HS256

  • RS256

Signing Key
secret_config.signingKeys

최대 3개의 Secrets(시크릿)으로 이루어진 목록입니다. 각 시크릿에는 타사 인증 시스템에서 JWT를 서명할 때 사용되는 서명 키가 한 개씩 담겨 있습니다. 이 키는 ASCII 문자, 숫자, 밑줄 및 하이픈만 포함할 수 있으며 길이가 32~512자여야 합니다. 다음은 유효한 256비트 서명 키입니다.

231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f

참고

어떤 값을 사용해야 할지 잘 모르겠다면 keygen.io 와 같은 무작위 키 생성기 웹사이트를 방문해 256보세요. 생성된 비트 값 중 하나를 사용합니다.

경고

Signing Key는 비밀 키입니다. 이 키를 가진 사람은 누구든지 앱에 대해 유효한 사용자 자격 증명을 발급할 수 있습니다. 공개적으로 액세스할 수 있는 위치(예: git 저장소, 메시지 보드 또는 코드 내)에는 절대 저장되지 않도록 하세요.

일부 외부 인증 시스템은 JSON 웹 키 세트 를 제공합니다. (JWKS)는 시스템이 JWT에 서명하는 데 사용하는 서명 알고리즘과 서명 키를 설명합니다. 서명 알고리즘과 키를 수동으로 지정하는 대신 JWKS를 사용하여 제공자를 구성할 수 있습니다. 반환된 JWKS에는 kid JWKS의 키 ID를 지정하는 헤더가 포함되어야 합니다. JWKS는 최대 3개의 서명 키를 지정할 수 있으며 RS256 알고리즘을 사용해야 합니다.

참고

JWK와 JWKS는 Atlas App Services에서 동의어로 사용됩니다.

제공해야 하는 값은 단 하나뿐입니다.

  • JWK URI은(는) JWK 또는 JWKS 서비스를 호스팅하는 서드파티 URL입니다. 이 옵션을 선택하면 App Services는 자동으로 암호화를 필수 RS256 메서드로 설정합니다.

Metadata Fields 각 내부 App Services 사용자를 설명하는 추가 데이터입니다. App Services는 타사 JWT에 포함된 필드 값에서 각 메타데이터 필드의 값을 결정합니다. 예를 들어 사용자의 name 필드를 설정하면 App Services는 JWT에서 해당 필드를 사용자의 표시 이름으로 사용합니다.

참고

App Services는 사용자가 로그인할 때마다 사용자의 메타데이터를 새로 고치고 사용자 메타데이터data 객체에 있는 필드를 노출합니다.

중요

JWT 및 메타데이터 필드 문자 제한

JWT 토큰의 길이는 토큰의 메타데이터 필드 수와 각 필드의 크기에 따라 늘어납니다. App Services는 JWT 토큰의 길이를 1 백만자로 제한하고 각 메타데이터 필드의 길이를 4096 자로 제한합니다. 이러한 제한을 초과하면 App Services에서 오류를 기록하고 티켓이 처리되지 않습니다.

각 메타데이터 필드에 대해 지정해야 하는 세 가지 값은 다음과 같습니다.

필드
설명
Required
필수
true인 경우 제공자와 연결된 모든 사용자에 대해 메타데이터 필드가 필요합니다. 외부 시스템에서 반환된 JWT에는 Path로 지정된 필드에 값이 할당되어 있어야 합니다.
Path
이름
메타데이터 필드의 값이 포함된 JWT 필드의 이름 또는 경로입니다. 포함된 객체에서 필드의 경로를 지정하려면 점 표기법을 사용합니다.
Field Name
field_name

선택 사항입니다. JWT 경로에 매핑되는 사용자 객체 data 문서의 메타데이터 필드 이름입니다. 이 필드 이름은 64자 미만이어야 합니다.

기본값 규칙

  • 이 필드를 지정하지 않으면 이름은 값이 포함된 JWT 필드 이름으로 기본 설정됩니다.

  • 이 필드를 지정하지 않고 경로 값에 점 표기법을 사용하는 경우 기본 이름은 표기법의 마지막 부분이 됩니다. 예를 들어, location.primary.city 경로를 지정하는 경우 이름의 기본값은 city입니다.

예제

외부 인증 시스템은 user_data 필드의 각 사용자에 대한 추가 정보가 포함된 JWT를 반환합니다.

(JWT JSON)
{
"aud": "myapp-abcde",
"exp": 1516239022,
"sub": "24601",
"user_data": {
"name": "Jean Valjean",
"aliases": [
"Monsieur Madeleine",
"Ultime Fauchelevent",
"Urbain Fabre"
]
}
}

각 사용자의 사용자 객체user_data 필드의 값을 포함하려면 App Services 구성에서 다음 메타데이터 필드를 지정합니다.

경로
필드 이름
user_data.name
name
user_data.aliases
aliases

이제 사용자 객체에는 다음 필드가 포함됩니다.

(USER METADATA OBJECT)
{
"id": "59fdd02846244cdse5369ebf",
"type": "normal",
"data": {
"name": "Jean Valjean",
"aliases": [
"Monsieur Madeleine",
"Ultime Fauchelevent",
"Urbain Fabre"
]
},
identities: [
{
"id": "24601",
"provider_type": "custom-token",
"data": {
"name": "Jean Valjean",
"aliases": [
"Monsieur Madeleine",
"Ultime Fauchelevent",
"Urbain Fabre"
]
},
}
]
}

JWT의 Audience는 토큰의 의도된 수신자를 지정합니다. JWT는 aud 클레임에서 오디언스를 설명합니다. App Services는 aud에 제공자가 구성된 앱의 앱 ID가 포함될 것으로 예상합니다. 하지만 외부 인증 시스템 JWT가 다른 aud 값을 지정하는 경우 해당 값을 대신 사용하도록 제공자를 구성할 수 있습니다.

Realm SDK나 API 서비스 중 하나를 사용해 새로운 JWT 사용자를 등록하고 사용자를 로그인할 수 있습니다.

사용자 지정 JWT 인증을 이용한 등록 및 로그인 방법에 대한 코드 예제는 선호 언어 및 플랫폼에 대한 Realm SDK 설명서를 참조하세요.

사용자 지정 JWT 제공자를 사용하여 데이터 API 요청을 인증할 수 있습니다. 사용자에게 서비스를 사용하기 전에 계정을 만들도록 요구하거나 요청에 기존 사용자와 일치하지 않는 유효한 JWT가 포함된 경우 새 사용자 계정을 자동으로 만들도록 API 엔드포인트를 구성할 수 있습니다. 서비스 API와 함께 JWT를 사용하는 방법에는 두 가지가 있습니다.

  • jwtTokenString 요청 헤더에 직접 JWT를 지정합니다.

  • JWT로 사용자 세션을 시작하고 세션 액세스 토큰을 Authorization 헤더 베어러 토큰으로 포함시킵니다.

자세한 내용은 데이터 API 요청 인증을 참조하세요.

← 사용자 지정 기능 인증