BasicAuthentication-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

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.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

Hinweis: Diese Richtlinie erzwingt nicht die Basisauthentifizierung für Anfragen an einen API-Proxy. Instead, you use it to Base64 encode/decode credentials, typically when connecting to a backend server or using a service callout policy, such as the Service Callout policy, that requires Basic Authentication.

Hinweis: Die folgenden Videos zeigen den klassischen Proxy-Editor in der Apigee-UI. Apigee führt eine neue Version des Proxy-Editors ein, die ein anderes Design als die in den Videos gezeigte klassische Version hat.

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.

Warnung: Die Basisauthentifizierung bietet keine Vertraulichkeit. Senden Sie Anmeldedaten immer über eine TLS-Verbindung (HTTPS) an Ihren Back-End-Dienst.

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	Presence
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. Siehe auch: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf	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	Verworfen

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

Standard	– Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Presence	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:	true
Präsenz:	Optional
Typ:	Boolesch

<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	Presence
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	Presence
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	Presence
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")

Hinweis:Wenn Sie Variablen mit den Namen BasicAuthentication.{policy_name}.fault.cause und BasicAuthentication.{policy_name}.fault.name sehen: sie werden derzeit nicht von Apigee verwendet.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die 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	Diverse Fehlerkorrekturen
steps.basicauthentication.InvalidBasicAuthenticationSource	500	Bei einer Decodierung, wenn der eingehende Base64-codierte String keinen gültigen Wert enthält oder der Header fehlerhaft ist (beispielsweise beginnt nicht mit Basic).
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	Diverse Fehlerkorrekturen
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

Hinweis: Bei der Fehlerbehandlung besteht die Best Practice darin, den Teil errorcode der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring. Er kann sich ändern.

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

Beispiel: Die neuesten Schemas finden Sie in unseren GitHub-Repository-Beispielen.

Weitere Informationen

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