This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
What
- Inbound authentication and authorization: Validate SAML Assertion
policy
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. - Outbound token generation: Generate SAML Assertion policy
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.
This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.
Samples
Generate SAML assertion
<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="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> </Namespaces> <XPath>/soap:Envelope/soap:Header/wsse:Security</XPath> </Message> </OutputVariable> <SignatureAlgorithm /> <Subject ref="reference">Subject name</Subject> <Template ignoreUnresolvedVariables="false"> <!-- A lot of XML goes here, within CDATA, with {} around each variable --> </Template> </GenerateSAMLAssertion>
Generating a SAML assertion
Validate SAML assertion
<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>
Validating a SAML assertion
Element reference
Generate SAML Assertion
Field Name | Description | ||
---|---|---|---|
name attribute |
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 Apigee UI enforces additional restrictions, such as
automatically removing characters that are not alphanumeric. |
||
ignoreContentType attribute |
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. |
||
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 not present, then the
value of Issuer will be used.
|
||
KeyStore |
The name of the KeyStore that contains the private key and the alias of the private key
used to digitally sign SAML assertions.
|
||
OutputVariable |
|||
FlowVariable |
|||
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. |
||
XPath |
An XPath expression that indicates the element on the outbound XML document to which the policy will attach the SAML assertion. | ||
SignatureAlgorithm |
SHA1 or SHA256 | ||
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.
|
||
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 AssignMessage policy.
|
Validate SAML Assertion
Field Name | Description |
---|---|
name attribute |
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 Apigee UI enforces additional restrictions, such as automatically
removing characters that are not alphanumeric.
|
ignoreContentType attribute |
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. |
Source |
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 . |
XPath |
Deprecated. Child of
Source . Use
AssertionXPath and SignedElementXPath .
|
AssertionXPath |
Child of
Source . An XPath expression that indicates the element on the
inbound XML document from which the policy can extract the SAML assertion.
|
SignedElementXPath |
Child of
Source . An XPath expression that indicates the element on the
inbound XML document from which the policy can extract the signed element. This
may be different or the same as the XPath for the AssertionXPath .
|
TrustStore |
The name of the TrustStore that contains trusted X.509 certificates used to validate
digital signatures on SAML assertions.
|
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.
|
Usage notes
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.
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.
Generate SAML Assertion
Policy processing:
- If the message is not XML, and IgnoreContentType is not set to
true
, then raise a fault. - 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.
- If "Template" is not set, then construct an assertion that includes the values of the Subject and Issuer parameters or their references.
- Sign the assertion using the specified key.
- Add the assertion to the message at the specified XPath.
Validate SAML Assertion
Policy processing:
- 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
orapplication/(.*+)?xml
. If the media type is not XML and<IgnoreContentType>
is not set, then the policy will raise a fault. - The policy will parse the XML. If parsing fails then it will raise a fault.
- The policy will extract the signed element and the assertion, using the respective XPaths
specified (
<SignedElementXPath>
and<AssertionXPath>
). If either of these paths do not return an element, then the policy will raise a fault. - The policy will verify that the Assertion is the same as the signed element, or is a child of the signed element. If this is not true, then the policy will raise a fault.
- If either of the
<NotBefore>
or<NotOnOrAfter>
elements are present in the assertion, the policy will check the current timestamp against these values, as described in SAML Core section 2.5.1. - The policy will apply any additional rules for processing the "Conditions" as described in SAML Core section 2.5.1.1.
- The policy will validate the XML digital signature, using the values of
<TrustStore>
and<ValidateSigner>
as described above. If validation fails, then the policy will raise a fault.
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.
Flow 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 ExtractVariables policy and other mechanisms in order to implement more complex validations.
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.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 |
Error reference
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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 ValidateSAMLAssertion
policy is not defined or empty: <Source> , <XPath> ,
<Namespaces> , <Namespace> .
|
build |
TrustStoreNotConfigured |
If the <TrustStore> element is empty or not specified in the
ValidateSAMLAssertion policy, then the deployment of the API proxy fails.
A valid truststore is required.
|
build |
NullKeyStoreAlias |
If the child element <Alias> is empty or not specified in the <Keystore>
element of GenerateSAMLAssertion policy, then the deployment of the API
proxy fails. A valid keystore alias is required.
|
build |
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.
|
build |
NullIssuer |
If the <Issuer> element is empty or not specified in the
GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A
valid <Issuer> value is required.
|
build |
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>
Related topics
Extracting variables: Extract Variables policy