The Security Assertion Markup Language (SAML) specification defines formats and protocols that enable applications to exchange XML-formatted information for authentication and authorization.

A "security assertion" is a trusted token that describes an attribute of an app, an app user, or some other participant in a transaction. Security assertions are managed and consumed by two types of entities:

  • Identity providers: Generate security assertions on behalf of participants
  • Service providers: Validate security assertions through trusted relationships with identity providers

The API platform can act as an identity provider and as a service provider. It acts as an identity provider by generating assertions and attaching them to request messages, making those assertions available for processing by backend services. It acts as a service provider by validating assertions on inbound request messages.

Inbound authentication and authorization

The SAML policy type enables API proxies to validate SAML assertions that are attached to inbound SOAP requests. The SAML policy validates incoming messages that contain a digitally-signed SAML assertion, rejects them if they are invalid, and sets variables that allow additional policies, or the backend services itself, to further validate the information in the assertion.

Sample

The following is a sample policy of type ValidateSAMLAssertion.

<ValidateSAMLAssertion name="SAML">
  <TrustStore>TrustStoreName</TrustStore>
  <ValidateSigner>true</ValidateSigner>
  <RemoveAssertion>false</RemoveAssertion>
  <AssertionLocation>xpath</AssertionLocation>
  <Message>request</Message>
  <IgnoreContentType>false</IgnoreContentType>
</ValidateSAMLAssertion>

Policy processing:

  1. The policy checks the inbound message to verify that the request's media type is XML, by checking if the content type matches the formats text/(.*+)?xml or application/(.*+)?xml. If the media type is not XML, or if "IgnoreContentType" is not set, then the policy will raise a fault.
  2. The policy will parse the XML. If parsing fails then it will raise a fault.
  3. The policy will validate the XML digital signature, using the values of TrustStore and ValidateSigner as described above. If validation fails then it will raise a fault.
  4. If present, the policy will check the current timestamp against the NotBefore and NotOnOrAfter elements in the assertion, as described in SAML Core section 2.5.1.
  5. Any additional rules for processing the "Conditions" as described in SAML Core section 2.5.1.1.

Once the policy has completed without raising a fault, the developer of the proxy can be sure of the following:

  • The digital signature on the assertion is valid and was signed by a trusted CA
  • The assertion is valid for the current time period
  • The subject and issuer of the assertion will be extracted and set in flow variables. It is the responsibility of other policies to use these values for additional authentication, such as checking that the subject name is valid, or passing it to a target system for validation.

Other policies, such as ExtractVariables, may be used to parse the raw XML of the assertion for more complex validation.

Supported versions of SAML

The SAML policy type supports SAML assertions that match version 2.0 of the SAML Core Specification and Version 1.0 of the WS-Security SAML Token Profile specification.

Outbound token generation

The SAML policy type enables API proxies to attach SAML assertions to outbound XML requests. Those assertions are then available to enable backend services to apply further security processing for authentication and authorization.

Sample

<GenerateSAMLAssertion name="SAML">
  <AssertionLocation>xpath</AssertionLocation>
  <Message>request</Message>
  <IgnoreContentType>false</IgnoreContentType>
  <KeyStore>
    <Name>keystorename</Name>
    <Alias>alias</Alias>
  </KeyStore>
  <Subject ref="reference">subject name</Subject>
  <Issuer ref="reference">issuer name</Issuer>
  <Template>
    <!-- A lot of XML goes here, in CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

Policy processing:

  1. If the message is not XML, and IgnoreContentType is not set to true, then raise a fault.
  2. If "Template" is set, then process the template as described for the AssignMessage policy. If any variables are missing and IgnoreUnresolvedVariables is not set, then raise a fault.
  3. If "Template" is not set, then construct an assertion that includes the values of the Subject and Issuer parameters or their references.
  4. Sign the assertion using the specified key.
  5. Add the assertion to the message at the specified XPath.

Configuring a ValidateSAMLAssertion policy

Field Name Description
name
The name of the policy instance. The name must be unique in the organization. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

 

TrustStore
The name of the TrustStore that contains trusted X.509 certificates used to validate digital signatures on SAML assertions.
ValidateSigner
A boolean that can be set to true or false. When true, the policy validates the digital signature on the SAML assertion against the digital certificates in the TrustStore named in the TrustStore element.
RemoveAssertion
A boolean that can be set to true or false. When true, the SAML assertion will be stripped from the request message before the message is forwarded to the backend service.
AssertionLocation
An XPath expression that indicates the element on the inbound XML document from which the policy can extract the SAML assertion.
Message
The target of the policy. Valid values are message, request, and response. When set to message, the policy conditionally retrieves the message object based on the attachment point of the policy. When attached to the request Flow, the policy resolves message to request, and when attached to the response Flow, the policy resolves message to response. Note that ValidateSAMLAssertion can only be attached to the ProxyEndpoint request Flow.
IgnoreContentType
A boolean that can be set to true or false. By default, the assertion will not be generated if the content type of the message is not an XML Content-type. If this is set to true then the message will be treated as XML regardless of the Content-type.

Configuring a GenerateSAMLAssertion policy

Field Name Description
name
description
AssertionLocation
An XPath expression that indicates the element on the outbound XML document to which the policy will attach the SAML assertion.
Message
The target of the policy. Valid values are message, request, and response. When set to message, the policy conditionally retrieves the message object based on the attachment point of the policy. When attached to the request Flow, the policy resolves message to request, and when attached to the response Flow, the policy resolves message to response. Note that GenerateSAMLAssertion can only be attached to the TargetEndpoint request Flow. SO, when using the GenerateSAMLAssertion policy, you should set this value to request.
IgnoreContentType
A boolean that can be set to true or false. By default, the assertion will not be generated if the nedia type of the message is not an XML Content-type. If this is set to true then the message will be treated as XML regardless of the Content-type.
KeyStore
The name of the KeyStore that contains the private key and the alias of the private key used to digitally sign SAML assertions.
Subject
The unique identifier of the subject of the SAML assertion. If the optional ref attribute is present, then the value of Subject will be assigned at runtime based on the specified variable. If the optional ref attribute is present, then the value of Subject will be used.
Issuer
The unique identifier of the identity provider. If the optional ref attribute is present, then the value of Issuer will be assigned at runtime based on the specified variable. If the optional ref attribute is present, then the value of Issuer will be used.
Template
If present, then the assertion will be generated by running this template, replacing everything denoted {} with the corresponding variable, and then digitally signing the result. The template is processed following the AssignMessage policy rules. See Generate or modify messages using AssignMessage.

Policy-specific variables

There are many pieces of information that may be specified in a SAML assertion. The SAML assertion itself is XML that can be parsed using the ExtractMessage policy and other mechanisms in order to implement more complex validations.

See Extract message content using ExtractVariables.

`

Variable Description
saml.id The SAML assertion ID
saml.issuer The "Issuer" of the assertion, converted from its native XML type to a string
saml.subject The "Subject" of the assertion, converted from its native XML type to a string
saml.valid Returns true or false based on the result of the validity check
saml.attribute.{attribute_name} The value of the named "Attribute" present in the assertion, converted from its native XML to a string
saml.attributeNames The names of all the "Attributes" present in the assertion, in a comma-separated list
saml.issueInstant IssueInstant
saml.subjectFormat Subject format
saml.scmethod Subject confirmation method
saml.scdaddress Subject confirmation data address
saml.scdinresponse Subject confirmation data in response
saml.scdrcpt Subject confirmation data recipient
saml.authnSnooa AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef AuthnStatement AuthnContextClassRef
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex AuthnStatement Session Index

Policy-specific error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)