사용자 지정 JWT 인증 구성(Okta, Auth0)

데이터 API 작성기에서는 사용자 지정 인증 공급자를 통해 타사 ID 공급자를 지원합니다. 조직에서 Okta, Auth0 또는 다른 OAuth 2.0/OpenID Connect 규격 ID 공급자를 사용하는 경우 이 방법을 사용합니다.

인증 흐름

사용자 지정 ID 공급자를 사용하면 클라이언트 앱이 사용자 인증을 처리한 다음, 데이터 API 작성기로 액세스 토큰을 보냅니다.

타사 ID 공급자를 사용하는 사용자 지정 JWT 인증 흐름의 그림입니다.

Phase	어떻게 되나요?
사용자 인증	사용자가 ID 공급자(Okta, Auth0 등)를 통해 로그인합니다.
토큰 획득	클라이언트 앱이 IdP에서 액세스 토큰을 받습니다.
API 호출	클라이언트가 `Authorization` 헤더에서 DAB로 토큰을 보냅니다.
Validation	DAB는 JWT(발급자, 대상 그룹, 서명)의 유효성을 검사합니다.
승인	DAB는 역할을 추출하고 사용 권한을 평가합니다.

필수 조건

ID 공급자가 있는 계정(Okta, Auth0 등)
ID 공급자에 등록된 애플리케이션
설치된 데이터 API 작성기 CLI(설치 가이드)
기존 dab-config.json에 엔터티가 하나 이상 있는 항목

빠른 참조

Setting	가치
Provider	`Custom`
유효성 검사에 필요	`iss`, `aud`, `exp`유효한 서명
권한 부여에 필요	`roles` 선택한 역할을 포함하는 클레임
토큰 헤더	`Authorization: Bearer <token>`
역할 클레임 유형	`roles` (수정됨, 구성할 수 없음)
역할 선택 헤더	`X-MS-API-ROLE`

1단계: ID 공급자 구성

정확한 단계는 공급자에 따라 달라집니다. 필요한 키 값은 다음과 같습니다.

수집할 값

가치	찾는 위치	사용 용도
발급자 URL	서비스 공급자의 설명서 또는 OAuth 메타데이터 엔드포인트	DAB `jwt.issuer` (JWT 기관으로 사용)
청중	애플리케이션의 클라이언트 ID 또는 사용자 지정 API 식별자	DAB `jwt.audience`

비고

DAB는 구성된 jwt.issuer를 JWT 권한 서버로 사용합니다. 서명 키는 표준 OpenID Connect 메타데이터(일반적으로)를 통해 자동으로 검색됩니다 <issuer>/.well-known/openid-configuration.

Okta 예제

Okta 관리 콘솔에 로그인합니다.
애플리케이션 애플리케이션>으로 이동합니다.
애플리케이션을 만들거나 선택합니다.
클라이언트 ID를 기록해 둡니다(대상 그룹으로 사용).
일반적으로 발급자는 https://<your-domain>.okta.com입니다.

Auth0 예제

Auth0 대시보드에 로그인합니다.
애플리케이션 API로> 이동합니다.
API를 만들거나 선택합니다.
식별자(대상 그룹으로 사용)를 적어둡니다.
귀하의 발급자는 https://<your-tenant>.auth0.com/입니다.

중요합니다

데이터 API 작성기에서는 역할 기반 권한 부여에 고정 클레임 유형을 roles 사용합니다. 이 값은 구성할 수 없습니다. ID 공급자가 다른 클레임(예: groups 또는 permissions)에서 역할을 내보내는 경우, 공급자가 roles 클레임을 함께 내보내도록 구성하거나 로그인 후 작업을 통해 값을 roles 클레임으로 복사해야 합니다.

2단계: 데이터 API 작성기 구성

인증 공급자를 Custom 설정하고 JWT 설정을 구성합니다.

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider Custom

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider Custom

REM Set the expected audience
dab configure ^
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

REM Set the expected issuer
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

결과 구성

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

3단계: 엔터티 권한 구성

ID 공급자가 할당하는 역할에 대한 권한을 정의합니다.

CLI

배쉬
명령 프롬프트

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow users with 'admin' role full access
dab update Book ^
  --permissions "admin:*"

결과 구성

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

4단계: ID 공급자에서 역할 구성

DAB는 roles 클레임에서 역할을 기대합니다. 이 클레임을 포함하도록 ID 공급자를 구성합니다.

Okta: 역할로 그룹 추가

Okta 관리 콘솔에서 보안>API로 이동합니다.
권한 부여 서버를 선택합니다.
클레임 탭으로 이동합니다.
클레임을 추가합니다.
- 이름: roles
- 토큰 유형에 포함: 액세스 토큰
- 값 형식: 그룹
- 필터: 포함할 그룹 선택

Auth0: 작업을 사용하여 역할 추가

Auth0 대시보드에서 작업>라이브러리로 이동합니다.
새 작업(로그인 후 트리거)을 만듭니다.
역할을 포함하는 코드를 추가합니다.

exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};

작업을 배포하고 로그인 흐름에 추가합니다.

팁 (조언)

Okta를 사용하여 JWT 클레임을 구성하는 방법에 대한 자세한 지침은 Okta의 SDK를 사용하여 고급 JWT 클레임 구현을 참조하세요.

5단계: 구성 테스트

데이터 API 작성기 시작:
```
dab start
```
ID 공급자로부터 토큰을 획득합니다. 공급자의 SDK 또는 Postman과 같은 도구를 사용합니다.
jwt.io 토큰을 검사하여 다음을 확인합니다.
- 클레임이 aud 구성된 대상과 일치
- 클레임이 구성된 발급자iss와 일치합니다.
- 클레임에 roles 예상 값이 포함되어 있습니다.

API를 호출합니다.

curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

사용자 지정 역할을 사용하려면 헤더를 포함합니다.X-MS-API-ROLE

curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: admin"

JWT 유효성 검사 세부 정보

데이터 API 작성기에서는 JWT의 이러한 측면의 유효성을 검사합니다.

확인	Description
서명	구성된 `jwt.issuer` 기관을 통해 검색된 서명 키를 사용하여 유효성 검사(OpenID Connect 메타데이터/JWKS)
발급자	구성과 정확히 일치 `jwt.issuer` 해야 합니다.
청중	`jwt.audience` 구성과 정확히 일치해야 합니다.
만료	토큰이 만료되어서는 안 됩니다(`exp` 클레임)
이전에는 유효하지 않음	토큰은 유효해야 합니다(`nbf` 클레임이 있는 경우).

Troubleshooting

증상	가능한 원인	해결 방법
`401 Unauthorized`	발급자 불일치	`iss` 클레임이 정확히 일치하는지 확인하세요 (후행 슬래시 포함).
`401 Unauthorized`	대상 그룹 불일치	클레임이 `aud` 구성된 값과 일치하는지 확인합니다.
`401 Unauthorized`	토큰이 만료됨	새 토큰 획득
`401 Unauthorized`	메타데이터를 사용할 수 없음	DAB에 연결할 수 있는지 확인 `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	토큰에 없는 역할	IdP 구성에 역할 추가
`403 Forbidden`	누락된 역할 주장	IdP를 `roles` 클레임을 포함하도록 구성
`403 Forbidden`	잘못된 클레임 이름	DAB는 클레임 형식 `roles` 을 사용합니다(수정됨, 구성할 수 없음)

중요합니다

DAB는 현재 모든 역할 검사에 클레임 유형을 roles 사용합니다. 이 값은 하드 코딩되어 있으며 , groups또는 다른 클레임 이름으로 변경할 permissions수 없습니다. ID 공급자를 구성하여, roles라는 이름의 클레임에서 역할 정보를 내보내도록 하세요.

일반적인 발급자 형식

Provider	발급자 형식
옥타 주	`https://<domain>.okta.com` 또는 `https://<domain>.okta.com/oauth2/default`
Auth0	`https://<tenant>.auth0.com/` (후행 슬래시에 유의)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
키클로크 주	`https://<host>/realms/<realm>`

전체 구성 예제

Okta 구성

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Auth0 구성

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-23

다음을 통해 공유

사용자 지정 JWT 인증 구성(Okta, Auth0)

인증 흐름

필수 조건

빠른 참조

1단계: ID 공급자 구성

수집할 값

Okta 예제

Auth0 예제

2단계: 데이터 API 작성기 구성

CLI

결과 구성

3단계: 엔터티 권한 구성

CLI

결과 구성

4단계: ID 공급자에서 역할 구성

Okta: 역할로 그룹 추가

Auth0: 작업을 사용하여 역할 추가

5단계: 구성 테스트

JWT 유효성 검사 세부 정보

Troubleshooting

일반적인 발급자 형식

전체 구성 예제

Okta 구성

Auth0 구성

관련 콘텐츠

피드백

추가 리소스