WSFED TC Interop Scenarios - OASIS



An OASIS White Paper

WSFED TC Interop Scenarios

Phase 1

Version ED-01

October 31, 2007

Editors Marc Goodner; Sidd Shenoy; Lloyd Burch

For OASIS WSFED TC

OASIS (Organization for the Advancement of Structured Information Standards) is a not-for-profit, international consortium that drives the development, convergence, and adoption of e-business standards. Members themselves set the OASIS technical agenda, using a lightweight, open process expressly designed to promote industry consensus and unite disparate efforts. The consortium produces open standards for Web services, security, e-business, and standardization efforts in the public sector and for application-specific markets. OASIS was founded in 1993. More information can be found on the OASIS website at .

The purpose of the Web Services Federation (WSFED) Technical Committee (TC) is to extend the basic federation capabilities enabled by Web service Security specifications (WS-Security, WS-SecureConversation, WS-Trust, and WS-SecurityPolicy) to provide advanced federation capabilities. This includes, but is not limited to: structure and acquisition of federation metadata; sign- out notifications; the use of pseudonym and identity mapping services and attribute services in conjunction with Security Token Services; claims-based authorization; and protection of a principal's privacy with respect to claims asserted in security tokens. In addition, the TC will define an HTTP serialization mechanism allowing the richness of WS-Trust security token based mechanisms for SOAP Web services - brokered trust relationships and distributed authentication and authorization - to be used in browser-based scenarios.

Table of Contents

Table of Contents 3

1. Introduction 4

1.1 Namespaces 4

2. WSFED Browser Scenario 5

Step 1 – GET Resource 6

Step 2 – Redirect to Resource IP/STS [OPTIONAL] 6

Step 3 – GET Resource Challenge [OPTIONAL] 7

Step 4 – Redirect to Requestor IP/STS 7

Step 5 – Requestor IP/STS Challenge 7

Step 6 – Return Requestor Token 8

Step 7 – POST Requestor Token 8

Step 8 – Return Resource Token [OPTIONAL] 9

Step 9 – POST Resource Token [OPTIONAL] 9

Step 10 – Return Result 10

Details of the RequestSecurityTokenResponse element 10

Details of the Returned Security Token Signature 10

Additional Guidance for Passive Scenarios 11

Appendix 12

Security Token Details 12

Supported Claims 15

1. Introduction

This document describes basic interop scenarios for WS-Federation 1.2. WS-Federation does not specify a token type for carrying claims. These interop scenarios use SAML 1.1 tokens and detail the format of those tokens.

1.1 Namespaces

Unless overridden by a namespace declaration inside an XML fragment, this document uses the following namespaces:

|Prefix |Namespace |

|s | |

|s11 | |

|wsa | |

|ds | |

|e | |

|k | |

|o | |

|wsu | |

|saml |urn:oasis:names:tc:SAML:1.0:assertion |

|wsp | |

|sc | |

|wst | |

|sp | |

|fed | |

2. WSFED Browser Scenario

This scenario uses a web browser as the requestor that attempts to access a resource, such as a web page, that requires authentication. The authentication request is passed back to the requestor’s browser to trigger an authentication request to the resource’s IP/STS. The requestor’s is then redirected from the resource IP/STS to the requestor’s own IP/STS. A token is then issued and passed back to the resource IP/STS. This completes the authentication of the requestor and the resource, such as a web page, is then returned.

This is all achieved with a browser client by mapping WS-Trust exchanges to HTTP using headers and redirects as defined in WS-Federation. The detailed flow used in this scenario is captured in Figure 29 from section 13.3 and message examples from Appendix B of WS-Federation (copied below).

This scenario depicts an initial federated flow. There are multiple ways to configure this scenario, such as combining the Resource and Resource STS, so the flow can vary. This document covers all steps in the above flow. The only steps that are required in all configurations are 1, 4/5, 6/7 and 10. All other steps are optional. Note that subsequent flows from the requestor to the resource realm may be optimized. The steps below describe the above interaction diagram. In the message examples below the following URLs are used:

|Item |URL |

|Resource Realm | |

|Resource | |

|Resource's IP/STS | |

|Account | |

|Resource | |

HTTPS is REQUIRED for all message exchanges in this interop scenario.

A SAML 1.1 token is to be returned in this scenario. The token must contain the claims Group and Common Name defined in the appendix, any value is acceptable. Details for returning the RST and token signing for this scenario are also covered below.

There is also additional general guidance for supporting passive scenarios that follows the explicit detailed examples for this scenario.

Step 1 – GET Resource

The requestor browser accesses a resource, typically using the HTTP GET method. The resource for this scenario is implementation specific; a web page would be a sensible choice.

GET HTTP/1.1

Step 2 – Redirect to Resource IP/STS [OPTIONAL]

At the resource, the requestor's request is redirected to the IP/STS associated with the target resource. The redirected URL MAY contain additional information reflecting agreements which the resource and its IP/STS have established; however, this (redirection target) URL MUST be used throughout the protocol as the URL for the resource's IP/STS. Typically, this occurs using a standard HTTP 302 error code.

It is RECOMMENDED that the resource STS provide confidentiality (e.g. using encryption or HTTP/S) of the information.

HTTP/1.1 302 Found (

Location:

The resource can optionally check for a previously written artifact/cookie and, if present, skip to Step 10.

Step 3 – GET Resource Challenge [OPTIONAL]

Upon receipt of the redirection, the IP/STS must determine the requestor realm. This requestor realm could be cached in an artifact/cookie from an earlier exchange, it could be known to or fixed by the resource, or the requestor MAY be prompted to enter or select their realm (step 3.1).

GET HTTP/1.1

Step 3.1 – UI to determine realm [OPTIONAL]

This is an optional step. If the resource IP/STS cannot determine the requestor’s realm, then the IP/STS MAY prompt the requestor for realm information.

[Implementation Specific Traffic]

Step 4 – Redirect to Requestor IP/STS

The resource IP/STS redirects to the requestor’s IP/STS in order to validate the requestor. Typically, this is done using a HTTP 302 redirect.

As in step 2, additional information MAY be passed to reflect the agreement between the two IP/STS’s.

The requestor IP/STS SHOULD provide information confidentiality or use HTTP/S or some other transport-level security mechanism.

HTTP/1.1 302 Found (

Location:

The Resource IP/STS MAY check for a previously written artifact/cookie and, if present, skip to Step 8.

Step 5 – Requestor IP/STS Challenge

The requestor's IP/STS now authenticates the requestor to establish a sign in.

GET HTTP/1.1

Step 5.1 - UI to Collect Authentication Data [OPTIONAL]

Validation of the requestor MAY involve displaying some UI in this optional step.

[Implementation Specific Traffic]

Step 6 – Return Requestor Token

Once requestor information has been successfully validated, a security token response (RSTR) is formatted and sent to the resource IP/STS.

Processing continues at the resource IP/STS via a redirect.

While an IP/STS MAY choose to return a pointer to token information using wresultptr, it is RECOMMENDED that, whenever possible to return the security token (RSTR) using a POST method to reduce the number of overall messages. This MAY be done using requestor-side scripting (shown below).

HTTP/1.1 200 OK

...

Working...

POST

setTimeout('document.forms[0].submit()', 0);

Step 7 – POST Requestor Token

Resource's IP/STS receives and validates the requestor's security token (RSTR).

POST HTTP/1.1 (

...(

(

wa=wsignin1.0 (

wctx=

wresult=...

Step 8 – Return Resource Token [OPTIONAL]

The resource's IP/STS performs a federated authentication/authorization check (validation against policy). After a successful check, the resource's IP/STS can issue a security token for the resource. The resource IP/STS redirects to the resource.

It should be noted that the optional wctx parameter specifies the opaque context information (if any) passed in with the original request and is echoed back here. This mechanism is an optional way for the IP/STS to have state returned to it.

At this point the resource's IP/STS MAY choose to set an artifact/cookie to indicate the sign-in state of the requestor (which likely includes the requestor’s realm).

HTTP/1.1 200 OK

...

Working...

POST

setTimeout('document.forms[0].submit()', 0);

Step 9 – POST Resource Token [OPTIONAL]

The resource receives the security token (RSTR) from the resource IP/STS. On successful validation the resource processes the request (per policy).

The security token SHOULD be passed using an HTML POST using the syntax previously described.

POST HTTP/1.1 (

... (

(

wa=wsignin1.0 (

wresult=...

Step 10 – Return Result

The resource MAY establish a artifact/cookie indicating the sign-in state of the requestor when it returns the result of the resource request. The resource returned in this scenario is the choice of the implementer, a web page indicating success would be a sensible choice.

[Implementation Specific Traffic]

Details of the RequestSecurityTokenResponse element

The RequestSecurityTokenResponse element that is included as the wresult parameter in the SignIn response MUST contain a RequestedSecurityToken element which MUST contain a SAML assertion. (I.e. the only child of RequestedSecurityToken MUST be saml:Assertion.)

The RequestSecurityTokenResponse element MAY include a wsp:AppliesTo / wsa:EndpointReference / wsa:Address element that specifies the Resource Realm URI. Note that this data is redundant – if present, it must duplicate the information in the signed token’s saml:Audience element.

See additional details on the SAML 1.1 token format for use in this scenario in the Appendix Security Token Details.

Details of the Returned Security Token Signature

The security token MUST contain an enveloped signature. The signature MUST be performed over canonicalized XML. The signature MUST be produced using the Requestor STS private key, which MUST correspond to either a certificate included as part of KeyInfo or an X.509 SKI included in the KeyInfo. Note that in the above example the certificate is included directly in KeyInfo (via the X509Data element). This is the RECOMMENDED approach. Referencing the X509 cert via an SKI will also be supported as part of the Passive Requestor Interoperability Profile (the xml snippet below illustrates this approach).

31d97bd7

The X509SKI element contains the base64 encoded plain (i.e., non-DER-encoded) value of an X509 V.3 SubjectKeyIdentifier extension. If the SubjectKeyIdentifier field is not present in the certificate, the certificate itself must be included directly in KeyInfo (see the above example).

Note that the returned security token is unencrypted (The entire RSTR is sent over SSL3.0/TLS).

Take care to include appropriate transforms in Signature/Reference/Transforms. For example, all SAML tokens following the rules above must contain the enveloped signature and EXCLUSIVE c14n transforms.

Additional Guidance for Passive Scenarios

Requesting Security Tokens

The parameters to request security tokens are encoded in a query string as specified in [WS-Federation]. The message will contain parameters as detailed below. Parameters enclosed in braces are OPTIONAL.

wa=wsignin1.0

wtrealm=resource realm URI

[wreply=Resource IP/STS Url]

[wctx=anything]

[wct=ISO8601 UTC]

The REQUIRED wa parameter is common to all SignIn messages and is fixed.

The REQUIRED wtrealm parameter MUST contain a URI that the Resource IP/STS and Requestor IP/STS have agreed to use to identify the realm of Resource IP/STS in messages to Requestor IP/STS. Note that this parameter is not required for redirected requests within the same realm.

The OPTIONAL wreply parameter specifies the URL to which this message’s response will be POSTed (see Returning Security Tokens).

The OPTIONAL wctx parameter is provided for Resource IP/STS’s use and MUST be returned by Requestor IP/STS unchanged.

The OPTIONAL wct parameter, if present, MUST contain the current time in UTC using the ISO8601 format (e.g. “2007-10-31T12:00:00Z”). This field may not be available if the requestor is coming via a portal link. Individual implementations of Requestor IP/STS MAY require this field to be present.

Returning Security Tokens

A security token is returned via SignIn message that MUST arrive via HTTP POST and MUST be protected by SSL/TLS. The parameters to the message are encoded in the POST body as specified in [WS-Federation]. The message will contain parameters as detailed below. Parameters enclosed in braces are OPTIONAL.

Note the absence of the optional wreq parameter specified in [WS-Federation]. This parameter is intended to host a RequestSecurityTokenResponse element or a full SOAP message. This parameter is absent because a RequestSecurityTokenResponse MUST be used.

wa=wsignin1.0

wresult=RequestSecurityTokenResponse

[wctx=wctx from the request]

The REQUIRED wa parameter is common to all SignIn messages and is fixed.

The REQUIRED wresult parameter MUST contain a RequestSecurityTokenResponse element, as detailed below.

The OPTIONAL wctx parameter MUST be identical to the wctx parameter from the incoming SignIn message that evoked this response.

Home Realm Discovery

To complete the protocol for requesting a token, it is necessary to redirect the Web requestor from the resource IP/STS to the requestor’s IP/STS. Determining the realm which manages the requestor’s identity, and the location of requestor’s IP/STS, is referred to as Home Realm Discovery. This frequently involves interaction with the user. There are situations – particularly when users only access resources via portals and never directly via bookmarked URLs – when it can be advantageous to include the requestor’s home realm in the request to avoid the requirement for human interaction. The following parameter MAY be specified for this purpose.

[whr=string]

The OPTIONAL whr parameter indicates the IP/STS address for the requestor. This may be specified directly as a URL or indirectly as an identifier (e.g. urn: or uuid:). In the case of an identifier the recipient is expected to know how to translate this to a URL. When the whr parameter is used the resource, or resource IP/STS, typically removes the parameter and writes a cookie to the client browser to remember this setting for future requests. Then, the request proceeds in the same way as if whr had not been specified.

It is also possible to use the whr parameter to implement a Home Realm Discovery Service. A resource IP/STS MAY redirect to the discovery service which through implementation-specific methods determines the user’s home realm. The discovery service MUST redirect back to the URL specified by the wreply parameter. If the context parameter is specified it MUST also be specified. If the discovery service was able to determine the home realm, it is returned using the whr parameter. This parameter SHOULD contain the same URI that the requestor IP/STS for the user’s home realm uses for the wtrealm parameter when it makes token requests to other federated partners. This value can be used to lookup the URL for the requestor IP/STS for properly redirecting the token request. If the discovery service is unable to determine the home realm then the whr parameter is not specified and the home realm must be discovered by other means.

Appendix

Security Token Details

This section details the requirements for SAML 1.1 tokens to be used in these scenarios. As a quick recap, the high level schema of a SAML assertion is shown below:

The returned SAML Assertion MUST use the un-extended SAML 1.0 schema (urn:oasis:names:tc:SAML:1.0:assertion). Assertion/@MajorVersion MUST be 1 Assertion/@MinorVersion MUST be 1. Note that SAMLV1.1 assertions use the urn:oasis:names:tc:SAML:1.0:assertion namespace). The returned SAML assertion MUST specify AssertionId, Issuer, and IssueInstant attributes on the Assertion element. The assertion MUST contain a Conditions element, which MUST specify the NotBefore and NotOnOrAfter attributes . The Conditions element MUST also contain an AudienceRestrictionCondition which restricts the audience to Resource STS.

AudienceRestrictionCondition MUST contain one and only one Audience element that specifies the Resource STS URI. Note that according to the above schema definition the Conditions element is optional. However to comply with the Passive Requestor Interoperbility Profile, the Conditions element is required. The Advice element SHOULD NOT be present in assertions conforming to this profile.

Assertion Statements

The two extensibility points for SAML statements: Statement & SubjectStatement (see above schema) will not be supported in the Passive Requestor Interoperbility Profile. Similarly the AuthorizationStatement will not be supported in this profile.

The only two statements that will be supported as part of the Passive Requestor Interoperability Profile are: and . Other statements in SAML assertions will be ignored.

AuthenticationStatement

A SAML assertion conformant with the Passive Requestor Interoperability Profile MUST contain one and only one AuthenticationStatment. An AuthenticationStatement MUST have a Subject element. If an AttributeStatement is present, the Subject element in the AuthenticationStatement MUST match Subject element in the AttributeStatement.

The AuthenticationMethod & AuthenticationInstant attributes MUST be specified. However, the optional AuthenticationStatement elements: SubjectLocality & AuthorityBinding will NOT be supported as part of the Passive Requestor Interoperability Profile.

AttributeStatement

A SAML assertion MAY have at most 1 attribute statement (SAML assertion may have no attribute statements) An AttributeStatement MUST have a Subject element. The Subject element MUST match the Subject element in the AuthenticationStatement. An AttributeStatement MUST contain one or more Attribute elements. Each Attribute element encapsulates a name/value claim. The Attribute element MUST have AttributeName and the corresponding AttributeNamespace attributes specified. The AttributeName attribute specifies the name of the claim, and one or more AttributeValue elements specify the value or values of the claim.

To ensure out-of-the-box interoperability, implementations conforming to the Passive Requestor Interoperability Profile SHOULD use the following namespace URL as the default value for AttributeNamespace for all claims in the Attribute element:



The AttributeName string value MUST NOT be included in the AttributeNamespace URI value. This will require implementations to process both the AttributeName and AttributeNamespace values to determine the claim being asserted.

Purchasing Agent

Subject

The Subject element used by the AuthenticationStatement & AttributeStatement MUST specify the NameIdentifer element (in the SAML 1.1 definition, this element is optional, see schema snippet below).

The SubjectConfirmation element, if specified MAY be ignored. If specified, it is RECOMMENDED that the SubjectConfirmation include a ConfirmationMethod element with the URI for the Bearer confirmation method:

URI: urn:oasis:names:tc:SAML:1.0:cm:bearer

For reference, the high level schema of a Subject element is shown below:

Furthermore the NameIdentifer element MUST specify the Format attribute (this attribute is also optional in SAML 1.1). The Format values MUST be one of the values defined in the table below in the section on supported claims.

Subject/NameIdentifier/@NameQualifier MUST NOT be present.

For reference, the high level schema of a NameIdentifer element is shown below:

Supported Claims

The WS-Federation Passive Requestor Interoperability Profile was created and distributed to participants involved in WS-Federation interoperability testing. Within that document there were common claim types defined. We will continue to use those claim types in the WSFED TC interop testing. This appendix contains those claim types, their associated mappings to WS-Federation’s Offered Claim Types, Common Claims Dialect and mapping to SAML 1.1 assertions for use in the WSFED TC interop scenarios defined above.

Normative language from the PRIP document is carried forward here; this document remains non-normative.

The claim types supported in the WSFED TC interop scenarios are defined below. They all follow the name/value pattern. However, four claim types have been identified through usage that provides specific and useful semantics.

• EmailAddress

• UPN

• CommonName

• Group

One extensibility claim type is also supported.

• NameValue

Email Address Claim Type

EmailAddress claim type is used to identify a specific security principal via an email address, and conforms to "addr-spec" as defined in IETF RFC 2822. The value MUST be unique such that it can be used for identification and authorization.

Offered Claim Type Example

Email Address

Email Address description

Authorization Common Claims Dialect Example

SAML 1.1 Example

EmailAddress claim type can be used in the Subject/NameIdentifier element of an AuthenticationStatement or AttributeStatement. The value of the Format attribute SHOULD be URI: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

johnd@

EmailAddress claim type can be used in the Attribute element of an AttributeStatement. The value of the AttributeNamespace attribute SHOULD be URL: . The value for AttributeName MUST be “EmailAddress”.

johnd@

User Principal Name (UPN)

UPN claim type is used to identify a specific security principal via a User Principal Name. The value MUST be unique such that it can be used for identification and authorization.

Offered Claim Type Example

User Principal Name

User Principal Name description

Authorization Common Claims Dialect Example

SAML 1.1 Example

UPN claim type can be used in the Subject/NameIdentifier element of an AuthenticationStatement or AttributeStatement. The value of the Format attribute SHOULD be URI:

johndoe@humanresource.

UPN claim type can be used in the Attribute element of an AttributeStatement. The value of the AttributeNamespace attribute SHOULD be URL: . The value for AttributeName MUST be “UPN”.

johndoe@humanresource.

Common Name

CommonName claim type is used to identify a security principal via a CN value consistent with X.500 naming conventions. The value of this claim is not necessarily unique and SHOULD NOT be used for authorization purposes. It is suitable for displaying a friendly name for personalization.

Offered Claim Type Example

Common Name

Common Name description

Authorization Common Claims Dialect Example

SAML 1.1 Example

CommonName claim type can be used in the Subject/NameIdentifier element of an AuthenticationStatement or AttributeStatement. The value of the Format attribute SHOULD be URI:

john doe

CommonName claim type can be used in the Attribute element of an AttributeStatement. The value of the AttributeNamespace attribute SHOULD be URL: . The value for AttributeName MUST be “CommonName”.

John Doe

Group Claim Type

Group claim type is used to indicate the association of the subject with other security principals. Interpretation of that association is application specific, but is typically treated as “group or role membership.”

Offered Claim Type Example

Group

Group description

Authorization Common Claims Dialect Example

SAML 1.1 Example

Group claim type MUST NOT be used in the Subject/NameIdentifier element.

Group claim type can only be used in the Attribute element of an AttributeStatement. The value of the AttributeNamespace attribute SHOULD be URL: . The value for AttributeName MUST be “Group”.

AccountManagers

NameValue Claim Type

NameValue claim type is an extensibility point to enable applications to define their name/value claims.

Offered Claim Type Example

Any

Specific to offered Name/Value

Authorization Common Claims Dialect Example

SAML 1.1 Example

NameValue claim type MUST NOT be used in the Subject/NameIdentifier element.

NameValue claim type can only be used in the Attribute element of an AttributeStatement. The value of the AttributeNamespace attribute SHOULD be URL: . The value for AttributeName is app specific.

rocketV

-----------------------

6

9

20

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download