사용자 지정 JWT 인증

인증 및 권한 부여

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

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

JWT 인증 작동 방식

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

클릭하여 확대

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의 서명과 일치하는지 확인합니다. 일치하는 경우 사용자가 인증됩니다.

구성

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

{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "config": {
      "audience": "<JWT Audience>",
      "requireAnyAudience": <boolean>,
      "signingAlgorithm": "<JWT Signing Algorithm>",
      "useJWKURI": <boolean>,
      "jwkURI": "<JWK or JWKS URL>",
    },
    "secret_config": {
      "signingKeys": [
        "<Signing Key Secret Name>",
        ...
      ]
    },
    "metadata_fields": [
      {
        "required": <boolean>,
        "name": "<JWT Field Path>",
        "field_name": "<Metadata Field Name>",
      },
      ...
    ],
    "disabled": <boolean>
  }
}

인증 방법

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비트 값 중 하나를 사용하는 것이 좋습니다.

App Services UI

앱 서비스 CLI

1. 서명 알고리즘을 다음과 같이 설정합니다:

   

2. JWT에 서명할 서명 키를 하나 이상 생성합니다. 이 작업을 수행하려면 키 이름을 입력하고 (나중에 참고용으로만 사용) 256비트 서명 키를 지정합니다.

   

"config": {
  "signingAlgorithm": "<JWT Signing Algorithm>",
},
"secret_config": {
  "signingKeys": [
    "<Signing Key Secret Name>",
    ...
  ]
}

경고

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

Use a JWK URI

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

참고

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

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

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

App Services UI

앱 서비스 CLI

타사 JWKS 엔드포인트의 URL을 지정합니다.

"config": {
  "useJWKURI": <boolean>,
  "jwkURI": "<JWK or JWKS URL>"
}

메타데이터 필드

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

참고

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

중요

JSON web token 및 메타데이터 필드 문자 제한

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

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

필드	설명
Required required	true인 경우 제공자와 연결된 모든 사용자에 대해 메타데이터 필드가 필요합니다. 외부 시스템에서 반환된 JWT에는 Path로 지정된 필드에 값이 할당되어 있어야 합니다.
Path name	메타데이터 필드 의 값이 포함된 JSON web token 의 필드 이름 또는 경로입니다. 내장된 객체 에서 필드 의 경로를 지정하려면 점 표기법 을 사용합니다. JSON web token 의 필드 이름 자체에 마침표(.) 문자가 포함된 경우 백슬래시(\)를 사용하여 마침표를 이스케이프 처리합니다. 예를 예시, 이름이 http://example.com/id 인 경우 http://example\.com/id 를 사용합니다.
Field Name field_name	선택 사항입니다. JWT 경로에 매핑되는 사용자 객체 data 문서의 메타데이터 필드 이름입니다. 이 필드 이름은 64자 미만이어야 합니다. 기본값 규칙 이 필드를 지정하지 않으면 이름은 값이 포함된 JWT 필드 이름으로 기본 설정됩니다. 이 필드를 지정하지 않고 경로 값에 점 표기법을 사용하는 경우 기본 이름은 표기법의 마지막 부분이 됩니다. 예를 들어, location.primary.city 경로를 지정하는 경우 이름의 기본값은 city입니다.

App Services UI

앱 서비스 CLI

메타데이터 필드를 정의하려면 Add Field을 클릭하고 JWT의 메타데이터 필드와 사용자 객체의 해당 필드 이름 간의 매핑을 지정합니다.

사용자 지정 JSON web token 인증 구성 파일 에서 메타데이터 필드 를 정의하려면 해당 필드 에 대한 항목을 metadata_fields 배열 에 추가합니다. 각 항목은 다음 형식의 문서 여야 합니다.

{
  required: <boolean>,
  name: "<field path>",
  field_name: "<metadata field name>"
}

백슬래시(\)를 사용하여 JSON web token 키에서 마침표(.) 문자를 이스케이프 처리합니다.

예를 예시, 이 JSON 객체 에서는 경로 이름의 "nested_key" 을(를) valid\.json\.key\.nested_key)로 나타냅니다.

{ "valid.json.key": {
    "nested_key": "val"
  }
}

예시

외부 인증 시스템은 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 값을 지정하는 경우 해당 값을 대신 사용하도록 제공자를 구성할 수 있습니다.

App Services UI

앱 서비스 CLI

다음 두 필드를 구성합니다.

필드	설명
Audience	클라이언트 JWT에서 찾을 것으로 예상되는 대상 또는 대상에 대한 단일 값 또는 쉼표로 구분된 값 목록입니다.
Require	여러 오디언스를 제공하는 경우 각 오디언스를 처리하는 방법을 지정해야 합니다. 옵션은 다음과 같습니다. 모든 대상: JWT에는 목록에 있는 모든 청중이 포함되어야 합니다. 이러한 잠재고객 중 하나: JWT는 목록에서 하나의 잠재고객만 포함하면 됩니다.

잠재고객을 설정하다 하려면 config.audience 을(를) 구성합니다. 구성하는 두 가지 필드가 있습니다.

필드	설명
audience	클라이언트 JSON web token 에서 찾을 것으로 예상되는 하나 이상의 대상을 지정하는 문자열 배열 입니다.
requireAnyAudience	부울. false인 경우 JSON web token 에 나열된 모든 대상이 포함되어야 합니다. true인 경우 JSON web token 에는 나열된 대상 중 하나 이상만 포함되어야 합니다.

"config": {
  "audience": [
    "<JWT Audience>",
  ],
  "requireAnyAudience": <boolean>,
}

JWT 인증 사용

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