Contents
After successfully authorizing a client, the API Gateway Explorer can insert a Security Assertion Markup Language (SAML) authorization assertion into the SOAP message. Assuming all other security filters in the policy are successful, the assertion will eventually be consumed by a downstream web service.
The following example of a signed SAML authorization assertion might be useful when configuring this filter.
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://.../soap/envelope/"> <soap:Header xmlns:wsse="http://.../secext"> <wsse:Security> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" AssertionID="oracle-1056130475340" Id="oracle-1056130475340" IssueInstant="2003-06-20T17:34:35Z" Issuer="CN=Sample User,...........,C=IE" MajorVersion="1" MinorVersion="0"> <saml:Conditions NotBefore="2003-06-20T16:20:10Z" NotOnOrAfter="2003-06-20T18:20:10Z"/> <saml:AuthorizationDecisionStatement Decision="Permit" Resource="http://www.oracle.com/service"> <saml:Subject> <saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.0:assertion#X509SubjectName"> sample </saml:NameIdentifier> </saml:Subject> </saml:AuthorizationDecisionStatement> <dsig:Signature xmlns:dsig="http://.../xmldsig#" id="Sample User"> <!-- XML SIGNATURE INSIDE ASSERTION --> </dsig:Signature> </saml:Assertion> </wsse:Security> </soap:Header> <soap:Body> <ns1:getTime xmlns:ns1="urn:timeservice"> </ns1:getTime> </soap:Body> </soap:Envelope>
Configure the following fields on the Assertion Details tab:
Issuer Name:
Select the certificate containing the Distinguished Name (DName) to use
as the Issuer of the SAML assertion. This DName is
included in the SAML assertion as the value of the Issuer
attribute of the <saml:Assertion>
element. For an example,
see the sample SAML assertion above.
Expire In:
Specify the lifetime of the assertion in this field. The lifetime of the assertion lasts from the time of insertion until the specified amount of time has elapsed.
Drift Time:
The Drift Time is used to account for differences in the clock times of the machine hosting the API Gateway Explorer (that generate the assertion) and the machines that consume the assertion. The specified time is subtracted from the time at which the API Gateway Explorer generates the assertion.
SAML Version:
You can create SAML 1.0, 1.1, and 2.0 attribute assertions. Select the appropriate version from the list.
![]() |
Important |
---|---|
SAML 1.0 recommends the use of the |
For this reason, Oracle recommend that SAML 1.1 or 2.0 is used when
signing assertions as they both uses the exclusive canonical algorithm
http://www.w3.org/2001/10/xml-exc-c14n#
, which safeguards
inserted assertions from such changes of context in the XML document.
For more information, see the oasis-sstc-saml-core-1.0.pdf
and the sstc-saml-core-1.1.pdf
documents,
both of which are available at
http://www.oasis-open.org.
Resource:
Enter the resource for which you want to obtain the authorization
assertion. You should specify the resource as a URI (for example,
http://www.oracle.com/TestService
). The name
of the resource is then included in the assertion.
Action:
You can specify the operations that the user can perform on
the resource using the Action field. This entry is
a comma-separated list of permissions. For example, the following is
a valid entry: read,write,execute
.
The options on the Assertion Location tab specify where the SAML assertion is inserted in the message. By default, the SAML assertion is added to the WS-Security block with the current SOAP actor/role. The following options are available:
Append to Root or SOAP Header:
Appends the SAML assertion to the message root for a non-SOAP XML message, or to the SOAP Header for a SOAP message. For example, this option may be suitable for cases where this filter may process SOAP XML messages or non-SOAP XML messages.
Add to WS-Security Block with SOAP Actor/Role:
Adds the SAML assertion to the WS-Security block with the specified SOAP actor (SOAP 1.0) or role (SOAP 1.1). By default, the assertion is added with the current SOAP actor/role only, which means the WS-Security block with no actor. You can select a specific SOAP actor/role when available from the list.
XPath Location:
To insert the SAML assertion at an arbitrary location in
the message, you can use an XPath expression to specify the exact
location in the message. You can select XPath expressions from the
list. The default is the First WSSE Security Element
,
which has an XPath expression of //wsse:Security
. You can
add, edit, or remove expressions by clicking the relevant button. For
more details, see the Configure XPath expressions topic.
You can also specify how exactly the SAML assertion is inserted using the following options:
-
Append to node returned by XPath expression (the default)
-
Insert before node returned by XPath expression
-
Replace node returned by XPath expression
Insert into Message Attribute:
Specify a message attribute to store the SAML assertion from the
list (for example, saml.assertion
). Alternatively, you can
also enter a custom message attribute in this field (for example,
my.test.assertion
). The SAML assertion can then be
accessed downstream in the policy.
The settings on the Subject Confirmation Method tab determine
how the <SubjectConfirmation>
block of the
SAML assertion is generated. When the assertion is consumed by a
downstream Web service, the information contained in the
<SubjectConfirmation>
block can be used
to authenticate either the end-user that authenticated to the API Gateway Explorer,
or the issuer of the assertion, depending on what is configured.
The following is a typical <SubjectConfirmation>
block:
<saml:SubjectConfirmation> <saml:ConfirmationMethod> urn:oasis:names:tc:SAML:1.0:cm:holder-of-key </saml:ConfirmationMethod> <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"> <dsig:X509Data> <dsig:X509SubjectName>CN=oracle</dsig:X509SubjectName> <dsig:X509Certificate> MIICmzCCAY ...... mB9CJEw4Q= </dsig:X509Certificate> </dsig:X509Data> </dsig:KeyInfo> </saml:SubjectConfirmation> </saml:SubjectConfirmation>
The following configuration fields are available on the Subject Confirmation Method tab:
Method:
The selected value determines the value of the
<ConfirmationMethod>
element. The following
table shows the available methods, their meanings, and their
respective values in the <ConfirmationMethod>
element:
Method | Meaning | Value |
---|---|---|
Holder Of Key | The API Gateway Explorer includes the key used to prove that the API Gateway Explorer is the holder of the key, or it includes a reference to the key. | urn:oasis:names:tc:SAML:1.0:cm:
|
Bearer | The subject of the assertion is the bearer of the assertion. | urn:oasis:names:tc:SAML:1.0:cm:
|
SAML Artifact | The subject of the assertion is the user that presented a SAML artifact to the API Gateway Explorer. | urn:oasis:names:tc:SAML:1.0:cm:
|
Sender Vouches | Use this confirmation method to assert that the API Gateway Explorer is acting on behalf of the authenticated end-user. No other information relating to the context of the assertion is sent. It is recommended that both the assertion and the SOAP Body must be signed if this option is selected. These message parts can be signed by using the Sign Message filter (see XML signature generation). | urn:oasis:names:tc:SAML:1.0:cm:
|
![]() |
Note |
---|---|
You can also leave the Method field
blank, in which case no |
Holder-of-Key Configuration:
When you select Holder-of-Key
as the SAML subject confirmation
in the Method field, you must configure how information about
the key is included in the message. There are a number of configuration options
available depending on whether the key is a symmetric or asymmetric key.
To use an asymmetric key as proof that the API Gateway Explorer is the holder-of-key entity, you must select the Asymmetric Key radio button, and then configure the following fields on the Asymmetric tab:
-
Certificate from Store:
To select a key that is stored in the certificate store, select this option and click the Signing Key button. On the Select Certificate screen, select the box next to the certificate that is associated with the key that you want to use.
-
Certificate from Message Attribute:
Alternatively, the key may have already been used by a previous filter in the policy (for example, to sign a part of the message). In this case, the key is stored in a message attribute. You can specify this message attribute in this field.
To use a symmetric key as proof that the API Gateway Explorer is the holder of key, select the Symmetric Key radio button, and then configure the fields on the Symmetric tab:
-
Generate Symmetric Key, and Save in Message Attribute:
If you select this option, the API Gateway Explorer generates a symmetric key, which is included in the message before it is sent to the client. By default, the key is saved in the
symmetric.key
message attribute. -
Symmetric Key in Message Attribute:
If a previous filter (for example, a Sign Message filter) has already used a symmetric key, you can to reuse this key as proof that the API Gateway Explorer is the holder-of-key entity. You must enter the name of the message attribute in the field provided, which defaults to
symmetric.key
. -
Encrypt using Certificate from Certificate Store:
When a symmetric key is used, you must assume that the recipient has no prior knowledge of this key. It must be included in the message so that the recipient can validate the key. To avoid meet-in-the-middle style attacks, where a hacker could eavesdrop on the communication channel between the API Gateway Explorer and the recipient and gain access to the symmetric key, the key must be encrypted so that only the recipient can decrypt the key. One way of doing this is to select the recipient's certificate from the certificate store. By encrypting the symmetric key with the public in the recipient's certificate, the key can only be decrypted by the recipient's private key, to which only the recipient has access. Select the Signing Key button and then select the recipient's certificate on the Select Certificate dialog.
-
Encrypt using Certificate from Message Attribute:
Alternatively, if the recipient's certificate has already been used (perhaps to encrypt part of the message) this certificate is stored in a message attribute. You can enter the message attribute in this field.
-
Symmetric Key Length:
Enter the length (in bits) of the symmetric key to use.
-
Key Wrap Algorithm:
Select the algorithm to use to encrypt (wrap) the symmetric key.
The Key Info tab must be configured regardless of whether you have elected to use symmetric or asymmetric keys. It determines how the key is included in the message. The following options are available:
-
Do Not Include Key Info:
Select this option to not include a
<KeyInfo>
section in the SAML assertion. -
Embed Public Key Information:
If this option is selected, details about the key are included in a
<KeyInfo>
block in the message. You can include the full certificate, expand the public key, include the distinguished name, and include a key name in the<KeyInfo>
block by selecting the appropriate boxes. When selecting the Include Key Name field, you must enter a name in the Value field, and then select the Text Value or Distinguished Name Attribute radio button, depending on the source of the key name. -
Put Certificate in Attachment:
Select this option to add the certificate as an attachment to the message. The certificate is then referenced from the
<KeyInfo>
block. -
Security Token Reference:
The Security Token Reference (STR) provides a way to refer to a key contained in a SOAP message from another part of the message. It is often used in cases where different security blocks n a message use the same key material and it is considered an overhead to include the key more than once in the message.
When this option is selected, a
<wsse:SecurityTokenReference>
element is inserted into the<KeyInfo>
block. It references the key material using aURI
to point to the key material and aValueType
attribute to indicate the type of reference used. For example, if the STR refers to an encrypted key, you should selectEncryptedKey
from the list, whereas if it refers to aBinarySecurityToken
, you should selectX509v3
from the list. Other options are available to enable more specific security requirements.
Configure the following fields on the Advanced tab:
Select Required Layout Type:
WS-Policy and SOAP Message Security define a set of rules that
determine the layout of security elements that appear in the WS-Security
header within a SOAP message. The SAML assertion is inserted into
the WS-Security header according to the layout option selected here.
The available options correspond to the WS-Policy Layout assertions of
Strict
, Lax
, LaxTimestampFirst
,
and LaxTimestampLast
.
Insert SAML Attribute Statement:
You can specify to insert a SAML attribute statement into the generated
SAML authorization assertion. If this option is selected, a SAML
attribute assertion is generated using attributes stored in the
attribute.lookup.list
message attribute and
subsequently inserted into the assertion. The
attribute.lookup.list
attribute must have been
populated previously by an attribute lookup filter for the
attribute statement to be generated successfully.
Indent:
Select this method to ensure that the generated signature is properly indented.
Security Token Reference:
The generated SAML authorization assertion can be encapsulated within a
<SecurityTokenReference>
block. The following
example demonstrates this:
<soap:Header> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext" soap:actor="oracle"> <wsse:SecurityTokenReference> <wsse:Embedded> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" AssertionID="oracle-1056130475340" Id="oracle-1056130475340" IssueInstant="2003-06-20T17:34:35Z" Issuer="CN=Sample User,...........,C=IE" MajorVersion="1" MinorVersion="0"> <saml:Conditions NotBefore="2003-06-20T16:20:10Z" NotOnOrAfter="2003-06-20T18:20:10Z"/> <saml:AuthorizationDecisionStatement Decision="Permit" Resource="http://www.oracle.com/service"> <saml:Subject> <saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.0:assertion#X509SubjectName"> sample </saml:NameIdentifier> </saml:Subject> </saml:AuthorizationDecisionStatement> <dsig:Signature xmlns:dsig="http://.../xmldsig#" id="Sample User"> <!-- XML SIGNATURE INSIDE ASSERTION --> </dsig:Signature> </saml:Assertion> </wsse:Embedded> </wsse:SecurityTokenReference> </wsse:Security> </soap:Header>
To add the SAML assertion to a
<SecurityTokenReference>
block as in the
example above, select the Embed SAML assertion within Security
Token Reference option. Otherwise, select
No Security Token Reference.