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

Data API Builder는 JWT(JSON Web Token) 유효성 검사를 사용하여 사용자 지정 인증 공급자를 통해 타사 ID 공급자를 지원합니다. 조직에서 Okta, Auth0 또는 다른 OAuth 2.0/OpenID Connect 규격 ID 공급자를 사용하는 경우 이 방법을 사용합니다.

인증 흐름

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

사전 요구 사항

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

빠른 참조

1단계: ID 공급자 구성

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

수집할 값

Okta 예제

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

Auth0 예제

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

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

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

CLI

# 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: 역할로 그룹 추가

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

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

Auth0에서는 사용자 지정 클레임에 네임스페이스가 지정된 충돌 방지 이름(예: https://example.com/roles)을 사용해야 합니다. 예약된 이름과 충돌하는 namespace가 없는 클레임은 별도의 알림 없이 토큰에서 제외됩니다. 자세한 내용은 Auth0 설명서에서 사용자 지정 클레임 만들기 를 참조하세요.

Data API 빌더는 네임스페이스가 지정된 변형이 아니라 정확한 클레임 이름 roles을 예상합니다. Auth0에서 이름이 지정되지 roles 않은 클레임을 허용하는지 여부는 테넌트 구성에 따라 달라집니다.

1. Auth0 대시보드에서 작업>라이브러리로 이동합니다.

2. 새 작업(로그인 후 트리거)을 만듭니다.

3. 역할을 포함하는 코드를 추가합니다.

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

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

5. jwt.io디코딩된 액세스 토큰을 확인하고 클레임이 roles 있는지 확인합니다.

5단계: 구성 테스트

1. 데이터 API 작성기 시작:

   dab start
   

2. ID 공급자로부터 토큰을 획득합니다. 공급자의 SDK 또는 Postman과 같은 도구를 사용합니다.

3. jwt.io 토큰을 검사하여 다음을 확인합니다.

   • 클레임이 aud 구성된 대상과 일치
   • 클레임이 구성된 발급자iss와 일치합니다.
   • 클레임에 roles 예상 값이 포함되어 있습니다.

4. API를 호출합니다.

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

5. 사용자 지정 역할을 사용하려면 헤더를 포함합니다.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의 이러한 측면의 유효성을 검사합니다.

Troubleshooting

일반적인 발급자 형식

전체 구성 예제

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": ["*"]
        }
      ]
    }
  }
}

관련 콘텐츠

• 권한 부여 개요
• Microsoft Entra ID 인증 구성
• 테스트를 위한 시뮬레이터 인증 구성
• 런타임 구성 참조