BasicAuthentication-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur Apigee X-Dokumentation.
Weitere Informationen

Was

Ermöglicht die Verwendung der einfachen Basisauthentifizierung für die Sicherheit der letzten Meile. Die Richtlinie verwendet einen Nutzernamen und ein Passwort, codiert sie mit Base64 und schreibt den resultierenden Wert in eine Variable. Der resultierende Wert hat das Format Basic Base64EncodedString. In der Regel schreiben Sie diesen Wert in einen HTTP-Header, z. B. den Header Authorization.

Sie können mit der Richtlinie auch Anmeldedaten, die in einem Base64-codierten String gespeichert sind, in Nutzernamen und Passwort umwandeln.

Video:In diesem Video wird gezeigt, wie Sie mithilfe der Basisauthentifizierungsrichtlinie einen Nutzernamen und ein Passwort base64-codieren.

Video:In diesem Video wird gezeigt, wie Sie mithilfe der Basisauthentifizierungsrichtlinie einen Base64-codierten Nutzernamen und Passwort decodieren.

Beispiele

Ausgehende Codierung

<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>

In der Beispielkonfiguration der Beispielrichtlinie werden Nutzername und Passwort, die codiert werden sollen, von den Variablen abgeleitet, die durch die Attribute ref für die Elemente <User> und <Password> angegeben werden. Die Variablen müssen festgelegt werden, bevor diese Richtlinie ausgeführt wird. Normalerweise werden die Variablen mit Werten gefüllt, die aus einer Schlüssel/Wert-Zuordnung gelesen werden. Siehe Richtlinie für die Schlüssel/Wert-Zuordnung.

Bei dieser Konfiguration wird der im Element <AssignTo> angegebene HTTP-Header Autorisierung hinzugefügt. Er wird der ausgehenden Anfragenachricht hinzugefügt, die an das Back-End gesendet wird Server:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Die Werte <User> und <Password> werden mit einem Doppelpunkt vor der Base64-Codierung verkettet.

Sie haben eine Schlüssel/Wert-Zuordnung mit folgendem Eintrag:

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

Hängen Sie vor der BasicAuthentication-Richtlinie folgende KeyValueMapOperations-Richtlinien an, um die Werte für die Elemente <User> und <Password> aus dem Schlüssel/Wert-Speicher zu extrahieren und in die Variablen credentials.username und credentials.password einzufügen.

<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>
      

Eingehende Decodierung

<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>

In diesem Richtlinienbeispiel enthält die Richtlinie den Nutzernamen und das Passwort aus dem HTTP-Header Authorization, wie durch das Element <Source> angegeben. Der Base64-codierte String muss das Format Basic Base64EncodedString. haben.

Die Richtlinie schreibt den decodierten Nutzernamen in die Variable request.header.username und das entschlüsselte Passwort in die Variable request.header.password.


Informationen zur Basisauthentifizierungsrichtlinie

Die Richtlinie verfügt über zwei Betriebsmodi:

  • Codieren: Base64 codiert einen in Variablen definierten Nutzernamen und Passwort
  • Decodieren: Decodiert den Nutzernamen und das Passwort aus einem Base64-codierten String.

Der Nutzername und das Passwort werden normalerweise in Form eines Schlüssel/Wert-Speichers gespeichert und dann zur Laufzeit aus dem Schlüssel/Wert-Speicher gelesen. Weitere Informationen zur Verwendung des Schlüssel/Wert-Speichers finden Sie in der Richtlinie für Schlüsselwertzuordnungsvorgänge.

Elementverweis

Die Elementreferenz beschreibt die Elemente und Attribute der Richtlinie "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>-Attribute

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

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut Beschreibung Standard Präsenz
name

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

Erforderlich
continueOnError

Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird.

false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

true Optional
async

Dieses Attribut wurde verworfen.

false Veraltet

<DisplayName>-Element

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<DisplayName>Policy Display Name</DisplayName>
Standardeinstellung

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.

Präsenz Optional
Typ String

<Operation>-Element

Legt fest, ob die Richtlinie Base64 codiert oder Anmeldedaten decodiert.

<Operation>Encode</Operation>
Standard:
Präsenz: Erforderlich
Typ:

String.

Gültige Werte sind:

  • Codieren
  • Decodieren

<IgnoreUnresolvedVariables>-Element

Ist true festgelegt, so gibt die Richtlinie keinen Fehler aus, wenn eine Variable nicht aufgelöst werden kann. Wird sie im Zusammenhang mit einer BasicAuthentication-Richtlinie verwendet, ist diese Einstellung normalerweise auf false gesetzt, da es in der Regel sinnvoll ist, einen Fehler zu melden, wenn in den angegebenen Variablen kein Nutzername oder Passwort gefunden wird.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
Standard: wahr
Präsenz: Optional
Typ:

Boolean

<User>-Element

  • Verwenden Sie zur Codierung das Element <User>, um die Variable anzugeben, die den Nutzernamen enthält. Die Werte für Nutzername und Passwort werden vor der Base64-Codierung mit einem Doppelpunkt verkettet.
  • Bei der Decodierung müssen Sie die Variable angeben, in die der decodierte Nutzername geschrieben wird.
<User ref="request.queryparam.username" /> 
Standard:
Präsenz: Erforderlich
Typ:

Attribute

Attribut Beschreibung Standard Präsenz
Ref

Die Variable, aus der die Richtlinie den Nutzernamen (codieren) dynamisch liest oder den Nutzernamen (decodieren) schreibt.

Erforderlich

<Password>-Element

  • Verwenden Sie zur Codierung das Element <Password>, um die Variable anzugeben, die das Passwort enthält.
  • Bei der Decodierung müssen Sie die Variable angeben, in die das decodierte Passwort geschrieben wird.
<Password ref="request.queryparam.password" />
Standard:
Präsenz: Erforderlich
Typ:

Attribute

Attribut Beschreibung Standard Präsenz
Ref

Die Variable, aus der die Richtlinie das Passwort (codieren) dynamisch liest oder das Passwort (decodieren) schreibt

Erforderlich

<AssignTo>-Element

Gibt die Zielvariable an, die mit dem von dieser Richtlinie generierten codierten oder decodierten Wert festgelegt werden soll.

Im folgenden Beispiel wird angezeigt, dass die Richtlinie den Authorization-Header der Nachricht auf den generierten Wert festlegen muss:

<AssignTo createNew="false">request.header.Authorization</AssignTo>
Standard:
Präsenz: Erforderlich
Typ:

String

Attribute

Attribut Beschreibung Standard Präsenz
createNew Bestimmt, ob die Richtlinie die Variable überschreiben soll, falls die Variable bereits festgelegt ist.

Bei "falsch" tritt die Zuweisung zur Variable nur auf, wenn die Variable derzeit nicht festgelegt ist (null).

Bei "wahr" wird die Zuweisung zur Variable immer durchgeführt.

Normalerweise setzen Sie dieses Attribut auf "falsch" (Standardeinstellung).

false Optional

<Source>-Element

Zur Decodierung der Variablen mit dem Base64-codierten String im Format Basic Base64EncodedString. Beispiel: Geben Sie request.header.Authorization entsprechend dem Header Authorisierung an.

<Source>request.header.Authorization</Source>
Standard:
Präsenz: Erforderlich für den Decodierungsvorgang.
Typ:

Ablaufvariablen

Folgende Ablaufvariable wird festgelegt, falls die Richtlinie fehlschlägt:

  • BasicAuthentication.{policy_name}.failed (mit dem Wert "wahr")

Fehlerreferenz

Dieser Abschnitt beschreibt die Fehlercodes und Fehlermeldungen, die zurückgegeben werden, und die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Beheben
steps.basicauthentication.InvalidBasicAuthenticationSource 500 Bei einer Decodierung, wenn der eingehende Base64-codierte String keinen gültigen Wert enthält oder der Header fehlerhaft ist (z. B. nicht mit "Basic" beginnen)
steps.basicauthentication.UnresolvedVariable 500 Die erforderlichen Quellvariablen für die Decodierung oder Codierung sind nicht vorhanden. Dieser Fehler kann nur auftreten, wenn IgnoreUnresolvedVariables auf "false" gesetzt ist.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Tritt auf, wenn Folgendes eintritt Beheben
UserNameRequired Das Element <User> muss für den benannten Vorgang vorhanden sein.
PasswordRequired Das Element <Password> muss für den benannten Vorgang vorhanden sein.
AssignToRequired Das Element <AssignTo> muss für den benannten Vorgang vorhanden sein.
SourceRequired Das Element <Source> muss für den benannten Vorgang vorhanden sein.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. BasicAuthentication.BA-Authenticate.failed = true

Beispiel für eine Fehlerantwort

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

Beispiel für eine Fehlerregel

<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>

Schemas

Weitere Informationen

Schlüssel/Wert-Paar Map-Vorgangs-Richtlinie