‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

خط‌مشی‌های SAMLAssertion

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

چه

اصالت‌سنجی و صدور مجوز ورودی: خط‌مشی «اعتبارسنجی بیانیه SAML»
نوع خط‌مشی SAML پراکسی‌های API را قادر می‌سازد بیانیه‌های SAML پیوست‌شده به درخواست‌های SOAP ورودی را اعتبارسنجی کنند. خط‌مشی SAML پیام‌های ورودی را که حاوی ادعای SAML با امضای دیجیتال هستند اعتبارسنجی می‌کند، درصورت نامعتبر بودن آن‌ها را رد می‌کند، و متغیرهایی را تنظیم می‌کند که به خط‌مشی‌های اضافی یا خود سرویس‌های زیرینه اجازه می‌دهد اطلاعات موجود در ادعا را بیشتر اعتبارسنجی کنند.
تولید کد خروجی: تولید خط‌مشی «اظهارات SAML»
نوع خط‌مشی SAML به پراکسی‌های API امکان می‌دهد اظهارات SAML را به درخواست‌های XML خروجی پیوست کنند. سپس این ادعاها دردسترس قرار می‌گیرند تا خدمات زیرینه بتوانند پردازش امنیتی بیشتری برای اصالت‌سنجی و صدور مجوز اعمال کنند.

نمونه‌ها

تولید ادعای 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>

درحال تولید ادعای SAML

تأیید درستی ادعای 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>

درحال اعتبارسنجی ادعای SAML

مرجع عنصر

تولید ادعای SAML

نام فیلد	شرح
‫`name` مشخصه	نام نمونه خط‌مشی. نام باید در سازمان منحصربه‌فرد باشد. نویسه‌هایی که می‌توانید در نام استفاده کنید به این موارد محدود می‌شود: `A-Z0-9._\-$ %`. بااین‌حال، «واسط کاربر مدیریت» محدودیت‌های بیشتری را اعمال می‌کند، برای نمونه نویسه‌هایی را که الفبایی عددی نیستند به‌طور خودکار برمی‌دارد.
‫`ignoreContentType` مشخصه	بولی که می‌تواند روی `true` یا `false` تنظیم شود. به‌طور پیش‌فرض، اگر نوع محتوای پیام از نوع «نوع محتوای» XML نباشد، ادعا تولید نخواهد شد. اگر این مقدار روی `true` تنظیم شود، پیام به‌عنوان XML درنظر گرفته می‌شود صرف‌نظر از نوع محتوا.
`Issuer`	شناسه یکتای ارائه‌دهنده هویت. اگر مشخصه اختیاری `ref` وجود داشته باشد، مقدار «صادرکننده» در زمان اجرا براساس متغیر مشخص‌شده اختصاص داده خواهد شد. اگر مشخصه اختیاری `ref` وجود نداشته باشد، از مقدار «صادرکننده» استفاده خواهد شد.
`KeyStore`	نام «محل ذخیره کلید» که حاوی کلید خصوصی و نام مستعار کلید خصوصی است که برای امضای دیجیتالی ادعاهای SAML استفاده می‌شود.
`OutputVariable`
`FlowVariable`
`Message`	هدف خط‌مشی. مقادیر معتبر عبارت‌اند از `message`، `request`، و `response`. وقتی روی `message` تنظیم شود، خط‌مشی به‌صورت شرطی شیء پیام را براساس نقطه پیوست خط‌مشی بازیابی می‌کند. وقتی به جریان درخواست پیوست می‌شود، خط‌مشی `message` را به درخواست تبدیل می‌کند، و وقتی به جریان پاسخ پیوست می‌شود، خط‌مشی `message` را به پاسخ تبدیل می‌کند.
`XPath`	عبارت XPath که عنصر سند XML خروجی را نشان می‌دهد که خط‌مشی ادعای SAML را به آن پیوست می‌کند.
`SignatureAlgorithm`	SHA1 یا SHA256
`Subject`	شناسه یکتای موضوع ادعای SAML. اگر مشخصه اختیاری `ref` وجود داشته باشد، مقدار «موضوع» در زمان اجرا براساس متغیر مشخص‌شده اختصاص داده خواهد شد. اگر مشخصه اختیاری `ref` وجود داشته باشد، از مقدار «موضوع» استفاده خواهد شد.
`Template`	اگر وجود داشته باشد، ادعا با اجرای این الگو، جایگزینی همه موارد نشان‌داده‌شده با `{}` با متغیر مربوطه، و سپس امضای دیجیتالی نتیجه تولید خواهد شد. الگو براساس قوانین خط‌مشی «تخصیص پیام» پردازش می‌شود. اختصاص دادن خط‌مشی پیام را ببینید. عنصر `<Template>` از ویژگی جایگزینی رشته پویا به‌نام الگوسازی پیام پشتیبانی می‌کند. الگوسازی پیام فقط زمانی پشتیبانی می‌شود که امضای خط‌مشی `GenerateSamlAssertion` باشد.

اعتبارسنجی ادعای SAML

نام فیلد	شرح
‫`name` مشخصه	نام نمونه خط‌مشی. نام باید در سازمان منحصربه‌فرد باشد. نویسه‌هایی که می‌توانید در نام استفاده کنید به این موارد محدود می‌شود: `A-Z0-9._\-$ %`. بااین‌حال، «واسط کاربر مدیریت» محدودیت‌های بیشتری را اعمال می‌کند، مثلاً به‌طور خودکار نویسه‌هایی را که الفبایی عددی نیستند برمی‌دارد.
‫`ignoreContentType` مشخصه	بولی که می‌تواند روی `true` یا `false` تنظیم شود. به‌طور پیش‌فرض، اگر نوع محتوای پیام از نوع «نوع محتوای» XML نباشد، ادعا تولید نخواهد شد. اگر این گزینه روی `true` تنظیم شود، پیام صرف‌نظر از نوع محتوا به‌عنوان XML درنظر گرفته می‌شود.
`Source`	هدف خط‌مشی. مقادیر معتبر عبارت‌اند از `message`، `request`، و `response`. وقتی روی `message` تنظیم شود، خط‌مشی به‌صورت شرطی شیء پیام را براساس نقطه پیوست خط‌مشی بازیابی می‌کند. وقتی به جریان درخواست پیوست می‌شود، خط‌مشی `message` را به درخواست تبدیل می‌کند، و وقتی به جریان پاسخ پیوست می‌شود، خط‌مشی `message` را به پاسخ تبدیل می‌کند.
`XPath`	منسوخ. فرزند `Source`. از `AssertionXPath` و `SignedElementXPath` استفاده کنید.
`AssertionXPath`	فرزند `Source`. عبارت XPath که عنصر موجود در سند XML ورودی را نشان می‌دهد که خط‌مشی می‌تواند ادعای SAML را از آن استخراج کند.
`SignedElementXPath`	فرزند `Source`. عبارت XPath که عنصر را در سند XML ورودی نشان می‌دهد که خط‌مشی می‌تواند عنصر امضاشده را از آن استخراج کند. این ممکن است با XPath برای `AssertionXPath` متفاوت یا یکسان باشد.
`TrustStore`	نام TrustStore که حاوی گواهینامه‌های X.509 مورداعتمادی است که برای اعتبارسنجی امضاهای دیجیتالی در ادعاهای SAML استفاده می‌شود.
`RemoveAssertion`	بولی که می‌تواند روی `true` یا `false` تنظیم شود. وقتی `true`، ادعای SAML قبل‌از اینکه پیام به سرویس زیرینه هدایت شود از پیام درخواست جدا خواهد شد.

یادداشت‌های استفاده

مشخصات «زبان نشانه‌گذاری ادعای امنیتی» (SAML) قالب‌ها و پروتکل‌هایی را تعریف می‌کند که برنامه‌ها را قادر می‌سازد اطلاعات با قالب XML را برای اصالت‌سنجی و مجوز مبادله کنند.

«ادعای امنیتی» یک کد مطمئن است که ویژگی‌های برنامه، کاربر برنامه، یا شرکت‌کننده دیگری در تراکنش را توصیف می‌کند. ادعاهای امنیتی توسط دو نوع نهاد مدیریت و مصرف می‌شوند:

ارائه‌دهندگان هویت: اظهارات امنیتی را ازطرف شرکت‌کنندگان تولید می‌کنند
ارائه‌دهندگان خدمات: ادعاهای امنیتی را ازطریق روابط مورداعتماد با ارائه‌دهندگان هویت اعتبارسنجی کنید

پلاتفرم API می‌تواند به‌عنوان ارائه‌دهنده هویت و به‌عنوان ارائه‌دهنده خدمات عمل کند. این سرویس با تولید ادعاها و پیوست کردن آن‌ها به پیام‌های درخواست، به‌عنوان ارائه‌دهنده هویت عمل می‌کند و این ادعاها را برای پردازش توسط سرویس‌های زیرینه دردسترس قرار می‌دهد. این سرویس با اعتبارسنجی ادعاهای پیام‌های درخواست ورودی به‌عنوان رساننده خدمات عمل می‌کند.

نوع خط‌مشی SAML از ادعاهای SAML که با نسخه ۲.۰ «مشخصات اصلی SAML» و نسخه ۱.۰ «مشخصات نمایه نشان WS-Security SAML» مطابقت دارند پشتیبانی می‌کند.

تولید ادعای SAML

پردازش خط‌مشی:

اگر پیام XML نباشد و IgnoreContentType روی true تنظیم نشده باشد، خطایی ایجاد کنید.
اگر «الگو» تنظیم شده باشد، الگو را همان‌گونه که برای خط‌مشی AssignMessage توضیح داده شده است پردازش کنید. اگر متغیری وجود نداشته باشد و IgnoreUnresolvedVariables تنظیم نشده باشد، خطا ایجاد کنید.
اگر «الگو» تنظیم نشده است، ادعایی بسازید که شامل مقادیر پارامترهای «موضوع» و «صادرکننده» یا ارجاع‌های آن‌ها باشد.
ادعا را بااستفاده از کلید مشخص‌شده امضا کنید.
ادعای موردنظر را در XPath مشخص‌شده به پیام اضافه کنید.

اعتبارسنجی ادعای SAML

پردازش خط‌مشی:

این خط‌مشی پیام ورودی را بررسی می‌کند تا تأیید کند نوع رسانه درخواست XML است، با بررسی اینکه آیا نوع محتوا با قالب‌های text/(.*+)?xml یا application/(.*+)?xml مطابقت دارد یا نه. اگر نوع رسانه XML نباشد و <IgnoreContentType> تنظیم نشده باشد، خط‌مشی خطا ایجاد می‌کند.
خط‌مشی XML را تجزیه خواهد کرد. اگر تجزیه ناموفق باشد، خطا ایجاد می‌کند.
خط‌مشی بااستفاده از XPaths مربوطه عنصر امضاشده و ادعا را استخراج می‌کند مشخص‌شده (<SignedElementXPath> و <AssertionXPath>). اگر هریک از این مسیرها عنصری را برنگرداند، خط‌مشی خطا ایجاد می‌کند.
خط‌مشی تأیید می‌کند که «ادعا» همان عنصر امضاشده است، یا فرزند عنصر امضاشده است. اگر این درست نباشد، خط‌مشی خطا ایجاد می‌کند.
اگر هریک از عناصر <NotBefore> یا <NotOnOrAfter> در ادعا وجود داشته باشد، خط‌مشی مُهر زمان فعلی را با این مقادیر بررسی می‌کند، همان‌طور که در بخش ۲.۵.۱ «هسته SAML» توضیح داده شده است.
خط‌مشی هر قانون اضافه‌ای را برای پردازش «شرایط» همان‌گونه که در بخش ۲.۵.۱.۱ «هسته SAML» توضیح داده شده است اعمال خواهد کرد.
این خط‌مشی امضای دیجیتال XML را بااستفاده از مقدار فروشگاه اعتماد (<TrustStore>) که در بالا توضیح داده شد اعتبارسنجی می‌کند. اگر اعتبارسنجی ناموفق باشد، خط‌مشی خطایی را ایجاد می‌کند.

وقتی خط‌مشی بدون ایجاد خطا تکمیل شد، توسعه‌دهنده کارگزار می‌تواند از موارد زیر مطمئن باشد:

امضای دیجیتال در ادعا معتبر است و توسط یک «مرجع صدور گواهی» مورد اعتماد امضا شده است
ادعا برای دوره زمانی فعلی معتبر است
موضوع و صادرکننده ادعا استخراج و در متغیرهای جریان تنظیم خواهد شد. استفاده از این مقادیر برای اصالت‌سنجی اضافی، مانند بررسی معتبر بودن نام موضوع، یا انتقال آن به سیستم هدف برای اعتبارسنجی، برعهده خط‌مشی‌های دیگر است.

از خط‌مشی‌های دیگر، مثل ExtractVariables، می‌توان برای تجزیه کردن XML خام ادعا برای اعتبارسنجی پیچیده‌تر استفاده کرد.

متغیرهای جریان

اطلاعات زیادی وجود دارد که ممکن است در ادعای SAML مشخص شود. خود ادعای SAML یک XML است که می‌تواند بااستفاده از خط‌مشی ExtractVariables و دیگر سازوکارها تجزیه شود تا اعتبارسنجی‌های پیچیده‌تر پیاده‌سازی شود.

متغیر	شرح
`saml.id`	شناسه ادعای SAML
`saml.issuer`	«صادرکننده» ادعا، تبدیل‌شده از نوع XML بومی به رشته
`saml.subject`	«موضوع» ادعا، تبدیل‌شده از نوع XML بومی آن به رشته
`saml.valid`	براساس نتیجه بررسی اعتبار، درست یا نادرست برمی‌گرداند
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	قالب موضوع
`saml.scmethod`	روش تأیید موضوع
`saml.scdaddress`	نشانی داده‌های تأیید موضوع
`saml.scdinresponse`	داده‌های تأیید موضوع در پاسخ
`saml.scdrcpt`	گیرنده داده‌های تأیید موضوع
`saml.authnSnooa`	AuthnStatement SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	نمایه جلسه AuthnStatement

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطایی را که Edge وقتی این خط‌مشی باعث بروز خطا می‌شود تنظیم می‌کند شرح می‌دهد. این اطلاعات برای دانستن اینکه آیا قوانین خطا را برای مدیریت خطاها توسعه می‌دهید یا نه مهم است. برای کسب اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدو رسیدگی به اشکالات را ببینید.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پراکسی حاوی این خط‌مشی را مستقر می‌کنید.

نام خطا	علت	رفع اشکال
`SourceNotConfigured`	یک یا چند عنصر از عناصر زیر در خط‌مشی «ادعای SAML را اعتبارسنجی کنید» تعریف نشده یا خالی است: `<Source>`،‏ `<XPath>`، `<Namespaces>`،‏ `<Namespace>`.
`TrustStoreNotConfigured`	اگر عنصر `<TrustStore>` خالی باشد یا در خط‌مشی ValidateSAMLAssertion مشخص نشده باشد، استقرار پراکسی API ناموفق خواهد بود. ‫Trust Store معتبر الزامی است.
`NullKeyStoreAlias`	اگر عنصر فرزند `<Alias>` در عنصر `<Keystore>` خط‌مشی «تولید ادعای SAML» خالی باشد یا مشخص نشده باشد، استقرار میانای برنامه‌سازی کاربردی با شکست مواجه می‌شود. نام مستعار Keystore معتبر الزامی است.
`NullKeyStore`	اگر عنصر فرزند `<Name>` خالی باشد یا در عنصر `<Keystore>` خط‌مشی GenerateSAMLAssertion مشخص نشده باشد، استقرار پراکسی API ناموفق خواهد بود. نام Keystore معتبر الزامی است.
`NullIssuer`	اگر عنصر `<Issuer>` خالی باشد یا در خط‌مشی «تولید ادعای SAML» مشخص نشده باشد، استقرار پراکسی API ناموفق خواهد بود. مقدار `<Issuer>` معتبر لازم است.

متغیرهای خطا

این متغیرها زمانی تنظیم می‌شوند که خطای زمان اجرا رخ دهد. برای اطلاعات بیشتر، آنچه باید درباره خطاهای خط‌مشی بدانیدرا ببینید.

متغیر	مکان	مثال
`fault.name="fault_name"`	‫`fault_name` نام گسل است. نام خطا آخرین بخش کد خطا است.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	برای پیکربندی خط‌مشی ادعای SAML معتبر، پیشوند خطا `ValidateSAMLAssertion` است.	`GenerateSAMLAssertion.failed = true`

نمونه پاسخ خطا

توجه: برای مدیریت خطا، روال مطلوب این است که بخش errorcode از پاسخ خطا را به‌دام بیندازید. به نوشتار faultstring تکیه نکنید، زیرا ممکن است تغییر کند.

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

قانون خطای نمونه

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

موضوعات مرتبط

درحال استخراج متغیرها: استخراج متغیرها خط‌مشی