Zasady SAMLAssertion

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X.
informacje.

Co

  • Przychodzące uwierzytelnianie i autoryzacja: potwierdzanie asercji SAML zasada
    Typ zasady SAML umożliwia serwerom proxy interfejsu API walidację asercji SAML podłączonych do przychodzące żądania SOAP. Zasada SAML weryfikuje wiadomości przychodzące zawierające podpisane cyfrowo asercja SAML, odrzuca je, jeśli są nieprawidłowe, i ustawia zmienne, które zezwalanie na dodatkowe zasady lub same usługi backendu w celu dalszej weryfikacji informacji. w sferze asercji.
  • Generowanie tokena wychodzącego: generowanie zasad asercji SAML
    Typ zasady SAML umożliwia serwerom proxy interfejsu API dołączanie potwierdzeń SAML do wychodzących żądań XML. Następnie dostępne są asercje, aby umożliwić usługom backendu możliwość stosowania dalszych zabezpieczeń uwierzytelnianie i autoryzacja.

Przykłady

Wygeneruj asercję SAML

<GenerateSAMLAssertion name="SAML" ignoreContentType="false">
  <CanonicalizationAlgorithm />
  <Issuer ref="reference">Issuer name</Issuer>
  <KeyStore>
    <Name ref="reference">keystorename</Name>
    <Alias ref="reference">alias</Alias>
  </KeyStore>
  <OutputVariable>
    <FlowVariable>assertion.content</FlowVariable>
    <Message name="request">
      <Namespaces>
        <Namespace prefix="test">http://www.example.com/test</Namespace>
      </Namespaces>
      <XPath>/envelope/header</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, in CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

Generowanie potwierdzenia SAML

Weryfikacja asercji SAML

<ValidateSAMLAssertion name="SAML" ignoreContentType="false">
  <Source name="request">
    <Namespaces>
      <Namespace prefix='soap'>http://schemas.xmlsoap.org/soap/envelope/</Namespace>
      <Namespace prefix='wsse'>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</Namespace>
      <Namespace prefix='saml'>urn:oasis:names:tc:SAML:2.0:assertion</Namespace>
    </Namespaces>
    <AssertionXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</AssertionXPath>
    <SignedElementXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</SignedElementXPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

Weryfikowanie asercji SAML


Odwołanie do elementu

Wygeneruj asercję SAML

Nazwa pola Opis
name atrybut Nazwa instancji zasady. Nazwa musi być unikalna w Twojej organizacji. Nazwa może zawierać tylko te znaki: A-Z0-9._\-$ %. Interfejs zarządzania wymusza jednak dodatkowe ograniczenia, takie jak: automatycznie usuwa znaki niealfanumeryczne.
ignoreContentType atrybut Wartość logiczna, która może być ustawiona na true lub false. Domyślnie atrybut asercja nie zostanie wygenerowana, jeśli typem treści wiadomości nie jest XML Content-Type (Typ treści). Jeśli ustawisz wartość true, komunikat będzie traktowany jako XML. niezależnie od typu treści.
Issuer
Unikalny identyfikator dostawcy tożsamości. Jeśli opcjonalny ref będzie podany, więc wartość Issuer zostanie przypisana w czasie działania na podstawie określonej zmiennej. Jeśli opcjonalny atrybut ref nie jest dostępny, zostanie użyta wartość Issuer.
KeyStore
Nazwa magazynu kluczy zawierającego klucz prywatny i alias klucza prywatnego używane do cyfrowego podpisywania asercji SAML.
OutputVariable
FlowVariable
Message Cel zasady. Prawidłowe wartości to message, request, i response. Gdy zasada ma wartość message, zasada warunkowo pobiera obiekt wiadomości na podstawie punktu załącznika zasady. Po podłączeniu do w przepływie żądania, zasada powoduje, że message przesyła żądanie, a po podłączeniu w przepływie odpowiedzi, zasada nakazuje message.
XPath Wyrażenie XPath wskazujące element w wychodzącym dokumencie XML, do którego zasada dołączy potwierdzenie SAML.
SignatureAlgorithm SHA1 lub SHA256
Subject
Unikalny identyfikator podmiotu potwierdzenia SAML. Jeśli opcjonalny element Jeśli istnieje atrybut ref, wartość Temat zostanie przypisana na poziomie na podstawie określonej zmiennej. Jeśli opcjonalny atrybut ref to obecna, zostanie użyta wartość Subject.
Template
Jeśli ten szablon jest dostępny, potwierdzenie zostanie wygenerowane przez uruchomienie tego szablonu, zastępując wszystko jest oznaczone odpowiednią zmienną {}, a następnie cyfrowo podpisać wynik. Szablon jest przetwarzany zgodnie z regułami zasady AssignMessage. Zobacz Przypisywanie Zasady dotyczące wiadomości.

Weryfikacja asercji SAML

Nazwa pola Opis
name atrybut
Nazwa instancji zasady. Nazwa musi być unikalna w organizacji. Nazwa może zawierać tylko te znaki: A-Z0-9._\-$ %. Interfejs zarządzania wymusza jednak dodatkowe ograniczenia, takie jak automatyczne usuwając znaki niealfanumeryczne.
ignoreContentType atrybut Wartość logiczna, która może być ustawiona na true lub false. Domyślnie atrybut asercja nie zostanie wygenerowana, jeśli typem treści wiadomości nie jest XML Content-Type (Typ treści). Jeśli ustawisz wartość true, komunikat będzie traktowany jako XML. niezależnie od typu treści.
Source Cel zasady. Prawidłowe wartości to message, request, i response. Gdy zasada ma wartość message, zasada warunkowo pobiera obiekt wiadomości na podstawie punktu załącznika zasady. Po podłączeniu do w przepływie żądania, zasada powoduje, że message przesyła żądanie, a po podłączeniu w przepływie odpowiedzi, zasada nakazuje message.
XPath
Wycofano. Dziecko konta Source. Używaj AssertionXPath i SignedElementXPath.
AssertionXPath
Dziecko konta Source. Wyrażenie XPath, które wskazuje element w przychodzący dokument XML, z którego zasada może wyodrębnić potwierdzenie SAML.
SignedElementXPath
Dziecko konta Source. Wyrażenie XPath, które wskazuje element w przychodzący dokument XML, z którego zasada może wyodrębnić podpisany element. Ten może być inny lub taki sam jak ścieżka XPath dla elementu AssertionXPath.
TrustStore
Nazwa magazynu TrustStore, który zawiera zaufane certyfikaty X.509 używane do weryfikacji podpisów cyfrowych w asercjach SAML.
RemoveAssertion
Wartość logiczna, która może być ustawiona na true lub false. Kiedy true, potwierdzenie SAML zostanie usunięte z wiadomości żądania przed wiadomość jest przekazywana do usługi backendu.

Zastosowanie

Specyfikacja SAML (Security Assertion Markup Language) definiuje formaty i protokoły, pozwalają aplikacjom na wymianę informacji w formacie XML na potrzeby uwierzytelniania autoryzacji.

„Potwierdzenie zabezpieczeń” to zaufany token opisujący atrybut aplikacji, użytkownika lub innego uczestnika transakcji. 2 potwierdzenia zabezpieczeń są zarządzane i wykorzystywane przez typy podmiotów:

  • Dostawcy tożsamości: generuj potwierdzenia zabezpieczeń w imieniu uczestników
  • Dostawcy usług: weryfikuj potwierdzenia bezpieczeństwa za pomocą zaufanych relacji z tożsamością usługodawcy

Platforma interfejsów API może działać jako dostawca tożsamości i usługodawca. Pełni ona rolę dostawcy tożsamości przez generowanie asercji i dołączanie ich do żądań wiadomości, dzięki czemu te asercje dostępne do przetwarzania przez usługi backendu. Jest to dostawca usług, który: weryfikacji asercji w wiadomościach przychodzących.

Typ zasad SAML obsługuje asercje SAML zgodne z wersją 2.0 funkcji SAML Core Specyfikacja i wersja 1.0 specyfikacji profilu tokenów SAML WS-Security.

Wygeneruj asercję SAML

Przetwarzanie zasad:

  1. Jeśli komunikat nie jest w formacie XML, a parametr ignoreContentType nie ma wartości true, zgłosić błąd.
  2. Jeśli "Szablon" a następnie przetwórz szablon zgodnie z opisem zasady AssignMessage. Jeśli brakuje jakichś zmiennych, a parametr ignoreUnresolvedvariables nie jest ustawiony, zgłoś błąd.
  3. Jeśli "Szablon" nie jest ustawiona, utwórz asercję, która zawiera wartości argumentu Parametry podmiotu i wystawcy lub ich odwołania.
  4. Podpisz asercję za pomocą podanego klucza.
  5. Dodaj potwierdzenie do wiadomości w podanej ścieżce XPath.

Weryfikacja asercji SAML

Przetwarzanie zasad:

  1. Zasada sprawdza wiadomość przychodzącą, aby zweryfikować, czy typ mediów żądania to XML. sprawdzanie, czy typ treści pasuje do formatów text/(.*+)?xml lub application/(.*+)?xml Jeśli typem nośnika jest inny niż XML i <IgnoreContentType> nie jest skonfigurowany, zasada będzie zgłaszać błąd.
  2. Zasada przeanalizuje kod XML. Jeśli analiza się nie uda, spowoduje to zgłoszenie błędu.
  3. Zasada wyodrębnia podpisany element i asercję przy użyciu odpowiednich ścieżek XPath (<SignedElementXPath> i <AssertionXPath>). Jeśli żadna z tych ścieżek nie zwróci elementu, zasada zwróci błąd.
  4. Zasada sprawdzi, czy asercja jest taka sama jak podpisany element. element podrzędny elementu podpisanego. Jeśli tak nie jest, zasada powoduje zgłoszenie błędu.
  5. Jeśli <NotBefore> lub <NotOnOrAfter> w asercji są obecne elementy, zasada sprawdzi bieżącą sygnaturę czasową te wartości są opisane w sekcji 2.5.1 SAML Core.
  6. Te zasady będą miały zastosowanie do wszystkich dodatkowych reguł przetwarzania „Warunków” zgodnie z opisem w sekcji 2.5.1.1 SAML Core.
  7. Zasada sprawdzi podpis cyfrowy XML przy użyciu wartości <TrustStore> i <ValidateSigner>, jak opisano powyżej. Jeśli weryfikacja się nie powiedzie, zasada zwróci błąd.

Po zakończeniu działania zasad bez zgłaszania błędu deweloper serwera proxy może mieć pewność, spośród następujących:

  • Podpis cyfrowy na potwierdzeniu jest prawidłowy i został podpisany przez zaufany urząd certyfikacji
  • Potwierdzenie jest prawidłowe dla bieżącego okresu
  • Podmiot i wydawca asercji zostaną wyodrębnione i ustawione w zmiennych przepływu. Jest innych zasad za używanie tych wartości na potrzeby dodatkowego uwierzytelniania, takich jak sprawdzając poprawność nazwy podmiotu lub przekazując ją do systemu docelowego w celu weryfikacji.

Do analizowania nieprzetworzonego kodu XML asercji można używać innych zasad, takich jak ExtractZmienne do bardziej złożonej weryfikacji.


Zmienne przepływu

Potwierdzenie SAML może zawierać wiele informacji. SAML Sama asercja to kod XML, który może być przeanalizowany przy użyciu zasady Extractvariables i innych za pomocą bardziej złożonych mechanizmów weryfikacji.

Zmienna Opis
saml.id Identyfikator asercji SAML
saml.issuer W sekcji „Wystawca” asercji, skonwertowaną z natywnego typu XML na ciąg znaków
saml.subject Pole „Subject” asercji, skonwertowaną z natywnego typu XML na ciąg znaków
saml.valid Zwraca wartość prawda lub fałsz na podstawie wyniku sprawdzania poprawności
saml.issueInstant IssueInstant
saml.subjectFormat Format tematu
saml.scmethod Metoda potwierdzenia obiektu
saml.scdaddress Adres danych potwierdzenia podmiotu
saml.scdinresponse Dane potwierdzenia podmiotu w odpowiedzi
saml.scdrcpt Odbiorca danych potwierdzenia podmiotu
saml.authnSnooa Parametr AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef Odwołanie klasy kontekstu uwierzytelniania
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex Indeks sesji AuthnStatement

Informacje o błędzie

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
SourceNotConfigured One or more of the following elements of the Validate SAML Assertion policy is not defined or empty: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured If the <TrustStore> element is empty or not specified in the ValidateSAMLAssertion policy, then the deployment of the API proxy fails. A valid Trust Store is required.
NullKeyStoreAlias If the child element <Alias> is empty or not specified in the <Keystore> element of Generate SAML Assertion policy, then the deployment of the API proxy fails. A valid Keystore alias is required.
NullKeyStore If the child element <Name> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid Keystore name is required.
NullIssuer If the <Issuer> element is empty or not specified in the Generate SAML Assertion policy, then the deployment of the API proxy fails. A valid <Issuer> value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault. The fault name is the last part of the fault code. fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed For a validate SAML assertion policy configuration, the error prefix is ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Example error response

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Example fault rule

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

Powiązane artykuły

Wyodrębnianie zmiennych: Wyodrębnianie zmiennych