Overview
|
After successfully authorizing a client, the Enterprise Gateway 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.
It may be useful to refer to the following example of a signed SAML
authorization assertion 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>
| |
| | |
|
|
General Configuration
|
Configure the following field:
Name:
Enter an appropriate name for the filter.
|
Assertion Details
|
Configure the following fields on the Assertion Details tab:
Issuer Name:
Select the certificate containing the Distinguished Name (DName) that
you want 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 Enterprise Gateway (that generate
the assertion) and the machines that consume the assertion. The specified
time is subtracted from the time at which the Enterprise Gateway generates the
assertion.
SAML Version:
You can create SAML 1.0, 1.1, and 2.0 attribute assertions. Select
the appropriate version from the drop-down list.
Important Note:
SAML 1.0 recommends the use of the
http://www.w3.org/TR/2001/REC-xml-c14n-20010315 XML Signature
Canonicalization algorithm. When inserting signed SAML 1.0 assertions
into XML documents, it is quite likely that subsequent signature
verification of these assertions will fail. This is due to the side
effect of the algorithm including inherited namespaces into canonical
XML calculations of the inserted SAML assertion that were not present
when the assertion was generated.
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.
Please see section 5.4.2 of the oasis-sstc-saml-core-1.0.pdf
and section 5.4.2 of 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 .
|
Assertion Location
|
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 drop-down list.
XPath Location:
If you wish 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
drop-down 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 Configuring
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 drop-down
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 circuit.
|
Subject Confirmation Method
|
The settings on the Subject Confirmation Method tab determines
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 Enterprise Gateway,
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 Enterprise Gateway includes the key used to prove that the
Enterprise Gateway is the holder of the key, or it includes
a reference to the key.
|
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key |
Bearer |
The subject of the assertion is the bearer of the assertion.
|
urn:oasis:names:tc:SAML:1.0:cm:bearer |
SAML Artifact |
The subject of the assertion is the user that presented a SAML
Artifact to the Enterprise Gateway.
|
urn:oasis:names:tc:SAML:1.0:cm:artifact |
Sender Vouches |
Use this confirmation method to assert that the Enterprise Gateway 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.
|
urn:oasis:names:tc:SAML:1.0:cm:bearer |
Note that you can also leave the Method field
blank, in which case no <ConfirmationMethod>
block is inserted into the assertion.
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.
Asymmetric Key:
If you want to use an asymmetric key as proof that the Enterprise Gateway is the
holder-of-key entity, you must select the Asymmetric Key
radio button, and then configure the following fields on the
Asymmetric tab:
-
Private Key from Certificate Store:
If you want 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.
-
Private Key from Message Attribute:
Alternatively, the key may have already been used by a previous
filter in the circuit, 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.
Symmetric Key:
If you want to use a symmetric key as proof that the Enterprise Gateway is the
holder of key, select the Symmetric Key radio button,
and then configure the fields on the Symmetric tab:
-
Generate Symmetric Key:
If you select this option, the Enterprise Gateway generates a
symmetric key, which is then included in the message before it
is sent to the client.
-
Symmetric Key in Message Attribute:
If a previous filter (for example, a Sign Message
filter) has already used a symmetric key, you can reuse this key as
proof that the Enterprise Gateway is the holder-of-key entity. You must enter
the name of the message attribute in the field provided.
-
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, therefore, 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 Enterprise Gateway 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.
Key Info:
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 if you do not wish to 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 a URI to point
to the key material and a ValueType attribute to
indicate the type of reference used. For example, if the STR refers
to an encrypted key, you should select EncryptedKey from
the dropdown, whereas if it refers to a BinarySecurityToken , you
should select X509v3 from the dropdown. Other options are
available to enable more specific security requirements.
|
Advanced
|
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.
|
|