BasicAuthentication 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

정책 아이콘

소개

라스트 마일 보안의 경우 경량 기본 인증을 사용할 수 있습니다. 정책은 사용자 이름과 비밀번호를 사용하고, Base64는 이를 인코딩하고, 결과 값을 변수에 작성합니다. 결과 값은 Basic Base64EncodedString 형식입니다. 이 값은 일반적으로 Authorization 헤더와 같이 HTTP 헤더에 작성됩니다.

이 정책을 사용하면 Base64로 인코딩된 문자열에 저장된 사용자 인증 정보를 사용자 이름과 비밀번호로 디코딩할 수도 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

동영상: 이 동영상에서는 기본 인증 정책을 사용하여 사용자 이름과 비밀번호를 base64로 인코딩하는 방법을 보여줍니다.

동영상: 이 동영상에서는 기본 인증 정책을 사용하여 base64로 인코딩된 사용자 이름과 비밀번호를 디코딩하는 방법을 보여줍니다.

샘플

아웃바운드 인코딩

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

위의 샘플 정책 구성에서 인코딩할 사용자 이름과 비밀번호는 <User> 및 <Password> 요소의 ref 속성에서 지정한 변수에서 파생됩니다. 이 정책이 실행되기 전에 변수를 설정해야 합니다. 일반적으로 변수는 키-값 맵에서 읽은 값으로 채워집니다. 키-값 맵 작업 정책을 참조하세요.

이렇게 하면 <AssignTo> 요소에 지정된 대로 승인이라는 HTTP 헤더가 백엔드 서버로 전송되는 아웃바운드 요청 메시지에 추가됩니다.

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

<User> 및 <Password> 값은 Base64 인코딩 전에 콜론을 사용하여 연결됩니다.

다음 항목이 포함된 키-값 맵이 있다고 가정합니다.

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername
  }, {
    "name" : "password",
    "value" : "MyPassword
  } ],
  "name" : "BasicAuthCredentials"
}

BasicAuthentication 정책 앞에 아래의 KeyValueMapOperations 정책을 연결하면 키-값 저장소에서 <User> 및 <Password> 요소의 값을 추출하여 credentials.username 및 credentials.password 변수에 채웁니다.

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

인바운드 디코딩

<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

이 정책 샘플에서 정책은 <Source> 요소에 지정된 대로 Authorization HTTP 헤더에서 사용자 이름과 비밀번호를 디코딩합니다. Base64로 인코딩된 문자열은 Basic Base64EncodedString. 형식이어야 합니다.

정책은 디코딩된 사용자 이름을 request.header.username 변수에 작성하고 디코딩된 비밀번호를 request.header.password 변수에 작성합니다.

기본 인증 정책 정보

이 정책에는 두 가지 작업 모드가 있습니다.

  • 인코딩: 변수에 저장된 사용자 이름과 비밀번호를 Base64 인코딩합니다.
  • 디코딩: Base64 인코딩 문자열에서 사용자 이름과 비밀번호를 디코딩합니다.

사용자 이름과 비밀번호는 일반적으로 키-값 저장소에 저장된 다음 런타임 시 키-값 저장소에서 읽습니다. 키-값 저장소 사용에 대한 자세한 내용은 키-값 맵 작업 정책을 참조하세요.

요소 참조

요소 참조는 BasicAuthentication 정책의 요소 및 속성을 설명합니다.

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source> 
</BasicAuthentication>

<BasicAuthentication> 속성

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성 설명 기본값 Presence
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:

 false 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 true 선택사항
async

이 속성은 지원이 중단되었습니다.

 false 지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence 선택사항
유형 문자열

<Operation> 요소

정책이 사용자 인증 정보를 Base64로 인코딩 또는 디코딩할지 결정합니다.

<Operation>Encode</Operation>
기본값: 해당 사항 없음
Presence: 필수
유형:

문자열.

유효한 값으로 다음이 포함되어 있습니다.

  • 인코딩
  • 디코딩

<IgnoreUnresolvedVariables> 요소

true로 설정하면 변수를 확인할 수 없는 경우 정책에서 오류를 생성하지 않습니다. BasicAuthentication 정책의 컨텍스트에서 사용되는 경우 일반적으로 이는 false로 설정됩니다. 지정된 변수에 사용자 이름이나 비밀번호를 찾을 수 없는 경우 일반적으로 오류를 생성하는 것이 유용하기 때문입니다.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
기본값: true
Presence: 선택사항
유형:

부울

<User> 요소

  • 인코딩의 경우 <User> 요소를 사용하여 사용자 이름이 포함된 변수를 지정합니다. 사용자 이름과 비밀번호 값은 Base64 인코딩 전에 콜론을 사용하여 연결됩니다.
  • 디코딩의 경우 디코딩된 사용자 이름이 작성되는 변수를 지정합니다.
<User ref="request.queryparam.username" />
기본값: 해당 사항 없음
Presence: 필수
유형:

해당 사항 없음

속성

속성 설명 기본값 Presence
ref

정책이 동적으로 사용자 이름을 읽거나(인코딩) 사용자 이름을 쓰는(디코딩) 변수입니다.

 해당 사항 없음 필수

<Password> 요소

  • 인코딩의 경우 <Password> 요소를 사용하여 비밀번호가 포함된 변수를 지정합니다.
  • 디코딩의 경우 디코딩된 비밀번호가 작성되는 변수를 지정합니다.
<Password ref="request.queryparam.password" />
기본값: 해당 사항 없음
Presence: 필수
유형:

해당 사항 없음

속성

속성 설명 기본값 Presence
ref

정책이 동적으로 비밀번호를 읽거나(인코딩) 비밀번호를 쓰는(디코딩) 변수입니다.

 해당 사항 없음 필수

<AssignTo> 요소

이 정책에서 생성된 인코딩된 값 또는 디코딩된 값으로 설정할 대상 변수를 지정합니다.

다음 예시에서는 정책이 메시지의 Authorization 헤더를 생성된 값으로 설정해야 함을 나타냅니다.

<AssignTo createNew="false">request.header.Authorization</AssignTo>
기본값: 해당 사항 없음
Presence: 필수
유형:

문자열

속성

속성 설명 기본값 Presence
createNew 변수가 이미 설정된 경우 정책이 변수를 덮어쓸지 결정합니다.

'false'인 경우 변수에 대한 할당은 현재 변수가 설정되지 않은(null) 경우에만 발생합니다.

'true'이면 변수에 대한 할당이 항상 발생합니다.

일반적으로 이 속성을 'false'(기본값)로 설정합니다.

 false 선택사항

<Source> 요소

디코딩의 경우 Base64로 인코딩된 문자열이 포함된 변수이며 Basic Base64EncodedString 형식입니다. 예를 들어 승인 헤더에 해당하는 request.header.Authorization을 지정합니다.

<Source>request.header.Authorization</Source>
기본값: 해당 사항 없음
Presence: 디코딩 작업에 필수입니다.
유형:

해당 사항 없음

흐름 변수

정책이 실패할 경우 다음 흐름 변수가 설정됩니다.

  • BasicAuthentication.{policy_name}.failed(true 값 있음)

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 원인 수정
steps.basicauthentication.InvalidBasicAuthenticationSource 500 수신된 Base64로 인코딩된 문자열에 유효한 값이 포함되어 있지 않거나 헤더 형식이 잘못된 경우(예: Basic으로 시작하지 않음) 디코딩 중입니다.
steps.basicauthentication.UnresolvedVariable 500 디코딩 또는 인코딩에 필요한 소스 변수가 없습니다. 이 오류는 IgnoreUnresolvedVariables가 false인 경우에만 발생할 수 있습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 발생 상황 수정
UserNameRequired 이름이 지정된 작업에는 <User> 요소가 있어야 합니다.
PasswordRequired 이름이 지정된 작업에는 <Password> 요소가 있어야 합니다.
AssignToRequired 이름이 지정된 작업에는 <AssignTo> 요소가 있어야 합니다.
SourceRequired 이름이 지정된 작업에는 <Source> 요소가 있어야 합니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 장소 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. BasicAuthentication.BA-Authenticate.failed = true

오류 응답 예시

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

오류 규칙 예시

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

스키마

관련 주제

키 값 맵 작업 정책