Express와 Amazon Verified Permissions 통합

Verified Permissions Express 통합은 Express.js 애플리케이션에서 권한 부여를 구현하는 미들웨어 기반 접근 방식을 제공합니다. 이 통합을 통해 기존 라우팅 핸들러를 수정하지 않고도 세분화된 권한 부여 정책을 사용하여 API 엔드포인트를 보호할 수 있습니다. 통합은 요청을 가로채고, 정의된 정책에 따라 요청을 평가하고, 승인된 사용자만 보호된 리소스에 액세스할 수 있도록 하여 권한 부여 검사를 자동으로 처리합니다.

이 주제에서는 정책 스토어 생성부터 권한 부여 미들웨어 구현 및 테스트에 이르기까지 Express 통합을 설정하는 방법을 안내합니다. 이 단계를 따르면 코드 변경을 최소화하면서 Express 애플리케이션에 강력한 권한 부여 제어를 추가할 수 있습니다.

이 주제 전체에서 다음 GitHub리포지토리가 참조됩니다.

• cedar-policy/authorization-for-expressjs - Express.js용 Cedar 권한 부여 미들웨어

• verifiedpermissions/authorization-clients-js - JavaScript에 대한 Verified Permissions 권한 부여 클라이언트

• verifiedpermissions/examples/express-petstore - Express.js 미들웨어를 사용한 구현 예제

사전 조건

Express 통합을 구현하기 전에 다음을 갖추어야 합니다.

• Verified Permissions에 액세스할 수 있는 AWS 계정

• Node.js 및 npm 설치됨

• Express.js 애플리케이션

• OpenID Connect(OIDC) 자격 증명 공급자(예: Amazon Cognito)

• AWS CLI 적절한 권한으로 구성됨

통합 설정

1단계: 정책 스토어 생성

AWS CLI다음을 사용하여 정책 스토어를 생성합니다.

aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"

참고

후속 단계에서 사용할 수 있도록 응답에 반환된 정책 스토어 ID를 저장합니다.

2단계: 종속성 설치

Express 애플리케이션에 필요한 패키지를 설치합니다.

npm i --save @verifiedpermissions/authorization-clients-js
npm i --save @cedar-policy/authorization-for-expressjs

권한 부여 구성

1단계: Cedar 스키마 생성 및 업로드

스키마는 애플리케이션의 엔터티 유형과 사용자가 수행할 수 있는 작업을 포함하여 애플리케이션에 대한 권한 부여 모델을 정의합니다. 스키마의 네임스페이스를 정의하는 것이 좋습니다. 이 예제에서는 YourNamespace을 사용합니다. 스키마를 Verified Permissions 정책 스토어에 연결하면 정책이 추가되거나 수정되면 서비스가 스키마에 대해 정책을 자동으로 검증합니다.

@cedar-policy/authorization-for-expressjs 패키지는 애플리케이션의 OpenAPI 사양을 분석하고 Cedar 스키마를 생성할 수 있습니다. 특히 경로 객체는 사양에 필요합니다.

OpenAPI 사양이 없는 경우 express-openapi-generator 패키지의 빠른 지침에 따라 OpenAPI 사양을 생성할 수 있습니다.

OpenAPI 사양에서 스키마를 생성합니다.

npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace YourNamespace --mapping-type SimpleRest

그런 다음와 함께 사용할 Cedar 스키마의 형식을 지정합니다 AWS CLI. 필요한 특정 형식에 대한 자세한 내용은 섹션을 참조하세요Amazon Verified Permissions 정책 스토어 스키마. 스키마 형식을 지정하는 데 도움이 필요한 경우 verifiedpermissions/examples GitHub리포지토리prepare-cedar-schema.sh에 라는 스크립트가 있습니다. 다음은 v2.cedarschema.forAVP.json 파일에서 Verified Permissions 형식의 스키마를 출력하는 해당 스크립트에 대한 호출 예제입니다.

./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json

형식이 지정된 스키마를 정책 스토어에 업로드하고를 정책 스토어 IDpolicy-store-id로 바꿉니다.

aws verifiedpermissions put-schema \
  --definition file://v2.cedarschema.forAVP.json \
  --policy-store-id policy-store-id

2단계: 권한 부여 정책 생성

정책이 구성되지 않은 경우 Cedar는 모든 권한 부여 요청을 거부합니다. Express 프레임워크 통합은 이전에 생성된 스키마를 기반으로 예제 정책을 생성하여이 프로세스를 부트스트랩하는 데 도움이 됩니다.

프로덕션 애플리케이션에서이 통합을 사용하는 경우 코드형 인프라(IaaC) 도구를 사용하여 새 정책을 생성하는 것이 좋습니다. 자세한 내용은 AWS CloudFormation으로 Amazon Verified Permissions 리소스 생성 단원을 참조하십시오.

샘플 Cedar 정책 생성:

npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json

그러면 /policies 디렉터리에 샘플 정책이 생성됩니다. 그런 다음 사용 사례에 따라 이러한 정책을 사용자 지정할 수 있습니다. 예시:

// Defines permitted administrator user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|administrator",
    action,
    resource
);

// Defines permitted employee user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|employee",
    action in
        [YourNamespace::Action::"GET /resources",
         YourNamespace::Action::"POST /resources",
         YourNamespace::Action::"GET /resources/{resourceId}",
         YourNamespace::Action::"PUT /resources/{resourceId}"],
    resource
);

와 함께 사용할 정책의 형식을 지정합니다 AWS CLI. 필요한 형식에 대한 자세한 내용은 AWS CLI 참조의 create-policy를 참조하세요. 정책 형식 지정에 도움이 필요한 경우 verifiedpermissions/examples GitHub리포지토리convert_cedar_policies.sh에 라는 스크립트가 있습니다. 다음은 해당 스크립트에 대한 호출입니다.

./scripts/convert_cedar_policies.sh

형식이 지정된 정책을 Verified Permissions에 업로드하여 policy_1.json를 정책 파일의 경로 및 이름으로 바꾸고를 정책 스토어 IDpolicy-store-id로 바꿉니다.

aws verifiedpermissions create-policy \
  --definition file://policies/json/policy_1.json \
  --policy-store-id policy-store-id

3단계: 자격 증명 공급자 연결

기본적으로 Verified Permissions 권한 부여자 미들웨어는 사용자 정보를 가져오기 위해 API 요청의 권한 부여 헤더 내에 제공된 JSON 웹 토큰(JWT)을 읽습니다. Verified Permissions는 권한 부여 정책 평가를 수행하는 것 외에도 토큰을 검증할 수 있습니다.

userPoolArn 및를 사용하여 clientId다음과 identity-source-configuration.txt 같은 이름의 ID 소스 구성 파일을 생성합니다.

{
    "cognitoUserPoolConfiguration": {
        "userPoolArn": "arn:aws:cognito-idp:region:account:userpool/pool-id",
        "clientIds": ["client-id"],
        "groupConfiguration": {
            "groupEntityType": "YourNamespace::UserGroup"
        }
    }
}

다음 AWS CLI 명령을 실행하여 자격 증명 소스를 생성하고를 정책 스토어 IDpolicy-store-id로 바꿉니다.

aws verifiedpermissions create-identity-source \
  --configuration file://identity-source-configuration.txt \
  --policy-store-id policy-store-id \
  --principal-entity-type YourNamespace::User

권한 부여 미들웨어 구현

권한 부여 미들웨어를 포함하도록 Express 애플리케이션을 업데이트합니다. 이 예제에서는 자격 증명 토큰을 사용하지만 액세스 토큰도 사용할 수 있습니다. 자세한 내용은의 authorization-for-expressjs를 참조하세요GitHub.

const { ExpressAuthorizationMiddleware } = require('@cedar-policy/authorization-for-expressjs');

const { AVPAuthorizationEngine } = require('@verifiedpermissions/authorization-clients');

const avpAuthorizationEngine = new AVPAuthorizationEngine({
    policyStoreId: 'policy-store-id',
    callType: 'identityToken'
});

const expressAuthorization = new ExpressAuthorizationMiddleware({
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, '../v4.cedarschema.json'), 'utf8'),
    },
    authorizationEngine: avpAuthorizationEngine,
    principalConfiguration: { type: 'identityToken' },
    skippedEndpoints: [],
    logger: {
        debug: (s) => console.log(s),
        log: (s) => console.log(s),
    }
});

// Add the middleware to your Express application
app.use(expressAuthorization.middleware);

통합 테스트

다른 사용자 토큰을 사용하여 API 엔드포인트에 요청하여 권한 부여 구현을 테스트할 수 있습니다. 권한 부여 미들웨어는 정의된 정책을 기준으로 각 요청을 자동으로 평가합니다.

예를 들어 권한이 다른 다른 사용자 그룹을 설정한 경우:

• 관리자: 모든 리소스 및 관리 기능에 대한 전체 액세스 권한

• 직원: 리소스를 보고, 생성하고, 업데이트할 수 있습니다.

• 고객: 리소스만 볼 수 있음

다른 사용자로 로그인하고 다양한 작업을 시도하여 권한 정책이 예상대로 작동하는지 확인할 수 있습니다. Express 애플리케이션의 터미널에서 권한 부여 결정에 대한 추가 세부 정보를 제공하는 로그 출력을 볼 수 있습니다.

문제 해결

권한 부여에 실패한 경우 다음을 시도하세요.

• 정책 스토어 ID가 올바른지 확인

• 자격 증명 소스가 올바르게 구성되었는지 확인

• 정책 형식이 올바른지 확인

• JWT 토큰이 유효한지 확인

다음 단계

기본 통합을 구현한 후 다음을 고려하세요.

• 특정 권한 부여 시나리오에 대한 사용자 지정 매퍼 구현

• 권한 부여 결정을 위한 모니터링 및 로깅 설정

• 다른 사용자 역할에 대한 추가 정책 생성