Software Design Document SAMLv2 IDP Proxying Federation Manager 7.5 Version 0.2 Please send comments to: dev@opensso.dev.java.net This document is subject to the following license: COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0 http://www.opensource.org/licenses/cddl1.php
Contents 1 Introduction......1 1.1 Document Status......1 1.2 Revision History...1 1.3 Summary...1 1.4 Scope...1 1.5 Context......1 1.6 Glossary...2 1.7 References...2 2 Overview......3 2.1 Use Case 1:...3 2.2 Use Case 2:...4 2.3 Use Case 3:...5 2.4 Use case 4:...5 3 Design Considerations...7 3.1 Assumptions and Dependencies...7 3.2 Goals and Guidelines...7 3.3 Development Method...7 4 Architectural Strategies...8 5 System Architecture...9 5.1 SAMLv2 IDP proxing in single sign on case without introduction cookie (persistent)...9 5.2 SAMLv2 IDP proxying in single sign on case with introduction cookie (persistent)...10 5.3 SAMLv2 IDP proxying in single sign on (transient)...13 5.4 SAMLv2 IDP proxing in single logout case...14 6 Detailed System Architecture...16 6.1 SAMLv2 metadata changes......16 6.2 SPI......17 com.sun.identity.saml2.profile Interface SAML2IDPProxy...17 getpreferredidp...17 6.3 IDP proxying in SSO...18 6.4 IDP Proxying in SLO...18 7 Appendices......19 Copyright 2007 Sun Microsystems, Inc. All rights reserved. iii
, Version iv Copyright 2007 Sun Microsystems, Inc. All rights reserved.
1 Introduction 1.1 Document Status Project Name FM 7.5 Document Title SAMLv2 IDP Proxying Date of Issue April 5, 2007 Current Version 0.2 Author Wei Sun Issuing Organization Sun Microsystems, Inc. Feedback E-mail dev@opensso.dev.java.net 1.2 Revision History Date Version Author Comments March 28, 2007 0.1 Wei Sun Initial draft April 5, 2007 0.2 Wei Sun Incorporated comments from Burt and Qingwen 1.3 Summary The functionality being developed is to enable SAMLv2 IDP proxying feature. It gives the capability of identity provider to proxy the authentication requests from service provider to various identity providers to which the user has authenticated. Hence it provides a seamless access to all the trusted providers. 1.4 Scope The current implementation scope is limited to SAMLv2 based SSO. Similar feature has been implemented in IDFF based SSO. 1.5 Context This feature is defined in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) v2.0. It is part of Authentication Request Protocol section. A set of processing rule defined in the specification MUST be implemented. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 1
, Version Introduction 1.6 Glossary COT Circle Of Trust. A federation of service providers and identity providers that have business relationships and operational agreements and with whom users can transact business in a secure and apparently seamless environment. IDP SP Identity Provider : system entity that manages identity information on behalf of Principals and provides assertions of Principal authentication to other providers. Service Provider : typically a website providing services and/or goods. SAMLv2 Security Assertion Markup language Version 2 SSO Assertion Single Sign On : encompasses the capability to authenticate with an Identity Provider and have that authentication honored by Service Providers. SAML term representing security information (authn, authz or attribute) typically sent from a IDP to a SP - typically as a XML document. 1.7 References [1] OASIS SAMLv2 specification [2] Identity Federation Use Case: Dynamic Proxying [3] Federation Manager 7.5 Software Requirement Specification [4] SAMLv2 IDP proxying SRS 2 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
2 Overview SAMLv2 core specification states: If an identity provider that receives an <AuthnRequest> has not yet authenticated the presenter or cannot directly authenticate the presenter, but believes that the presenter has already authenticated to another identity provider or a non-saml equivalent, it may respond to the request by issuing a new <AuthnRequest> on its own behalf to be presented to the other identity provider, or a request in whatever non-saml format the entity recognizes. The original identity provider is termed the proxying identity provider. Upon the successful return of a <Response> (or non-saml equivalent) to the proxying provider, the enclosed assertion or non-saml equivalent MAY be used to authenticate the presenter so that the proxying provider can issue an assertion of its own in response to the original <AuthnRequest>, completing the overall message exchange [1]. Goal: The identity provider proxying allows the identity providers (IDP) to proxy the authentication request from a service provider (SP) to different identity provider that has authenticated the user already. 2.1 Use Case 1: This use case is designed for IDP proxying while single sign on without introduction cookie. Pre Condition: SP1 has successfully federated to IDP1. SP2 has successfully federated to IDP2. (Refer to Figure 1). introduction cookie is not enabled for SP1. IDP1 IDP2 trust trust SP1 SP2 Processing: Figure 1 The user accesses the resource hosted by SP1. SP1 sends <AuthnRequest> to IDP1 for authentication (persistent case). No user session in IDP1 and IDP proxying feature is enabled for SP1. IDP1 shall pick up an IDP from a list of IDP specified in the configuration. For instance IDP2 is picked up. IDP1 forms a <AuthnRequest> and sends to IDP2. If the user has authenticated to IDP2, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. If the user has not authenticated to IDP2, Copyright 2007 Sun Microsystems, Inc. All rights reserved. 3
, Version Overview IDP2 asks the user to authenticate. Upon successfully login, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. IDP1 forms <AuthnResponse> and sends to SP1. SP1 checks the current policy setting against <AuthnResponse> information and grants the user access to the resource hosted by SP1. Refer to Figure 2. Success Scenario: The user gains access to SP1. Error condition: SP1 and IDP1 receive <AuthnResponse> with an error <Status> and may gets a second-level <StatusCode> of AuthnFailed or UnknownPrincipal. IDP1 trust IDP2 trust trust SP1 Figure 2 SP2 2.2 Use Case 2: This use case is designed for IDP proxying while single sign on with introduction cookie. Pre Condition: SP1 has successfully federated to IDP1. SP2 has successfully federated to IDP2. (Refer to Figure 1). introduction cookie is enabled for SP1. Processing: The user accesses the resource hosted by SP1. SP1 sends <AuthnRequest> to IDP1 for authentication (persistent case). No user session in IDP1. IDP proxying feature is enabled for SP1 and introduction cookie is enabled. IDP1 redirects to SAMLv2 IDP discovery URL. SAMLv2 IDP discovery returns the preferred IDP's provider id. For instances, it turns IDP2's provider id. IDP1 forms a <AuthnRequest> and sends to IDP2. If the user has authenticated to IDP2, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. If the user has not authenticated to IDP2, IDP2 asks the user to authenticate. Upon successfully login, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. IDP1 forms <Assertion> and sends to SP1. SP1 checks the current policy setting against <Assertion> information and grants the user access to the resource hosted by SP1. Refer to Figure 2. 4 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
Overview, Version Success Scenario: The user gains access to SP1. Error condition: SP1 and IDP1 receive <AuthnResponse> with an error <Status> and may gets a second-level <StatusCode> of AuthnFailed or UnknownPrincipal. 2.3 Use Case 3: Use case 2 is similar to use case1. The only difference is IDP1 does not contain any user information. It only acts as IDP proxy. The user information only stores in IDP2. Processing: The user accesses the resource hosted by SP1. SP1 sends <AuthnRequest> to IDP1 for authentication (transient case). IDP proxying feature is enabled for SP1. IDP1 shall pick up an IDP from a list of IDP specified in the configuration or get preferred IDP provider ID by asking idp discovery url. For instance IDP2 is picked up. IDP1 forms a <AuthnRequest> and sends to IDP2. If the user has authenticated to IDP2, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. If the user has not authenticated to IDP2, IDP2 asks the user to authenticate. Upon successfully login, IDP2 sends <AuthnResponse> which contains <Assertion> to IDP1. IDP1 forms <Assertion> and sends to SP1. SP1 checks the current policy setting against <Assertion> information and grants the user access to the resource hosted by SP1. Refer to Figure 2. Success Scenario: The user gains access to SP1. Error condition: SP1 and IDP1 receive <AuthnResponse> with an error <Status> and may gets a second-level <StatusCode> of AuthnFailed or UnknownPrincipal. 2.4 Use case 4: Processing: This use case is designed for IDP proxying while single logout. The user initiates an <LogoutRequest> from SP1 to IDP1. IDP1 would check IDPSession and find out the partner providers. The partner provider is formed due to the single sign on process with SP1. IDP1 sends <LogoutRequest> to each partner providers. Partner provider terminates the user session and sends <LogoutResponse> to IDP1. Upon received all <LogoutResponse> from partner providers. IDP1 forms <LogoutResponse> and sends to SP1. SP1 terminates its user session. Success Scenario: The user successfully log out from SP1, IDP1 and IDP2. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 5
, Version Overview Error condition: SP1 and IDP1 receive <LogoutResponse> with top-level <StatusCode> indicating error. 6 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
Design Considerations, Version 3 Design Considerations 3.1 Assumptions and Dependencies SP and IDP MUST have capability to set up the trust base. SP and IDP MUST achieve single sign on via SAMLv2 protocol (persistent and transient). SP and IDP MUST achieves single logout via SAMLv2 protocol. The extended config metadata should define the attributes needed for this feature. There should be APIs to access those attributes defined in the extended config metadata. 3.2 Goals and Guidelines The goal is to provide capacity of IDP proxying capability to Federation Manager 7.5. The following deliverable should be expected: -- saml2.jar should include this feature. -- need to modify samlv2 extended config metadata template to include the attributes needed by this feature. --SAML v2 console should be able to edit the attributes needed by this feature. --Javadoc for the SPI should be published. 3.3 Development Method Development of this feature set will follow OpenSSO mandated development process and guidelines. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 7
, Version Architectural Strategies 4 Architectural Strategies This feature is intended to integrate in the existing SAMLv2 frame work. The user should follow the normal single sign on and single logout process. The following points we need address during the implementation: (a) We should be able to configure SAMLv2 IDP proxying feature. (b) We should provide SPI for picking up the preferred IDP. (c) The implementation of this feature should be integrated in the existing SAMLv2 single sign on and single logout flow. (d) The implementation shall be able to turn off IDP proxying per each connection request. For instance, if the configuration of a SP has IDP proxying enabled, user should be able to pass a parameter such as idpproxy=false to SSO init URL and IDP proxying would not happen for this connection. 8 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
System Architecture, Version 5 System Architecture The following diagram shows the sequence of message exchange and processing for SAMLv2 IDP proxying. Each sequence diagram is related to the use case listed in section 2. 5.1 SAMLv2 IDP proxing in single sign on case without introduction cookie (persistent) Copyright 2007 Sun Microsystems, Inc. All rights reserved. 9
, Version System Architecture 1. The user accesses the resource hosted by SP1. 2. SP1 creates <AuthnRequest> 3. SP1 sends <AuthnRequest> to IDP1 for authentication (persistent case). No user session in IDP1 and IDP proxying feature is enabled for SP1. 4. IDP1 processes the <AuthnRequest> such as signature validation etc. 5. IDP1 picks up an IDP from a list of IDP specified in the configuration. For instance IDP2 is picked up. 6. IDP1 forms an <AuthnRequest> 7. IDP1 sends the <AuthnRequest> to IDP2. 8. If the user has authenticated to IDP2 previously. IDP2 creates <AuthnResponse> which contains <Assertion>. If the user has not authenticated to IDP2, IDP2 asks the user to authenticate. Upon successfully login. IDP2 creates <AuthnResponse>. 9. IDP2 sends <AuthnResponse> to IDP1 10. IDP1 forms a new <AuthnResponse> 11. IDP1 sends the <AuthnResponse> to SP1. 12. SP1 checks the current policy setting against <AuthnResponse> information and grants the user access to the resource hosted by SP1. 5.2 SAMLv2 IDP proxying in single sign on case with introduction cookie (persistent) 10 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
System Architecture, Version Copyright 2007 Sun Microsystems, Inc. All rights reserved. 11
, Version System Architecture 1. The user accesses the resource hosted by SP1. 2. SP1 creates <AuthnRequest> 3. SP1 sends <AuthnRequest> to IDP1 for authentication (persistent case). No user session in IDP1. IDP proxying feature is enabled for SP1 and introduction cookie is enabled. 4. IDP1 processes the <AuthnRequest> including signature validation. 5. IDP1 redirects to SAMLv2 IDP discovery URL. 6. SAMLv2 IDP discovery returns the preferred IDP's provider id. For instances, it turns IDP2's provider id. 7. IDP1 forms an <AuthnRequest> 12 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
System Architecture, Version 8. IDP1 sends <AuthnRequest> to IDP2. 9. If the user has authenticated to IDP2 previously. IDP2 creates <AuthnReponse> which contains <Assertion>. If the user has not authenticated to IDP2, IDP2 asks the user to authenticate. Upon successfully login. IDP2 creates <AuthnResponse>. 10. IDP2 sends <AuthnResponse> to IDP1. 11. IDP1 forms a new <AuthnResponse> 12. IDP1 sends <AuthnResponse> to SP1. 13. SP1 checks the current policy setting against <AuthnResponse> information and grants the user access to the resource hosted by SP1. 5.3 SAMLv2 IDP proxying in single sign on (transient) The sequence diagram is the same as 5.1 and 5.2. The only difference is IDP1 does not contain any user information. It only acts as IDP proxy. The user information only stores in IDP2. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 13
, Version System Architecture 5.4 SAMLv2 IDP proxing in single logout case 1. The user initiates logout to SP1 2. SP1 creates <logoutrequest> 3. SP1 sends <LogoutRequest> to IDP1. 4. IDP1 would check IDPSession and find out the partner providers. The partner provider is formed due to the single sign on process with SP1. 5. IDP1 sends <LogoutRequest> to each partner providers. For instance, IDP2 is one of the partner 14 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
System Architecture, Version provider. 6. Partner provider IDP2 terminates the user session 7. IDP2 sends <LogoutResponse> to IDP1. 8. Upon received all <LogoutResponse> from partner providers. IDP1 terminates the user session 9. IDP1 forms <LogoutResponse> and sends to SP1. 10. SP1 terminates its user session. 11. Redirect to Login page Copyright 2007 Sun Microsystems, Inc. All rights reserved. 15
, Version Detailed System Architecture 6 Detailed System Architecture 6.1 SAMLv2 metadata changes The following attributes should be included in SAMLv2 extended config MetaData: <Attribute name=enableidpproxy> <Value>false</Value> </Attribute> <Attribute name=idpproxylist> <Value></Value> </Attribute> <Attribute name=idpproxycount> <Value>-1</Value> </Attribute> <Attribute name=useintroductionforidpproxy> <Value>false</Value> </Attribute> This is specified for a service provider. EnabledIDProxy: is the key to turn SAMLv2 IDP proxy feature on or off. IdpProxyList: specifies the identity providers trusted by the requester (SP) to authenticate the presenter (user). IdpProxyCount: specifies the number of proxying indirections permissible between the identity provider that receives this <AuthnRequest> and the identity provider who ultimately authenticates the principals. A count of zero means no proxying. UseIntroductionForIDPProxy: if the key is on, samlv2 introduction cookie would be used to pick up a preferred IDP verse going through the idp proxy list. 16 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
Detailed System Architecture, Version 6.2 SPI com.sun.identity.saml2.profile Interface SAML2IDPProxy public interface SAML2IDPProxy This interface SAML2IDPProxy is used to find a preferred Identity Authenticating provider to proxy the authentication request. Method Summary String getpreferredidp(authnrequest authnrequest, String hostproviderid, HttpServletRequest request, HttpServletResponse response) Returns the preferred IDP. Method Detail getpreferredidp String getpreferredidp(authnrequest authnrequest, String hostproviderid, String realm, HttpServletRequest request, HttpServletResponse response) throws SAML2Exception Returns the preferred IDP. Parameters: authnrequest - original authnrequest hostproviderid - ProxyIDP providerid. realm-realm request - HttpServletRequest response - HttpServletResponse Returns: providerid of the authenticating provider to be proxied. null to disable the proxying and continue for the local authenticating provider. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 17
, Version Detailed System Architecture Throws: SAML2Exception - if error occurs. 6.3 IDP proxying in SSO In current SAMLv2 implementation, SPSSOFederate class is the class which performs the required processing logic for sending Authentication Request from SP to IDP. We should change AuthnRequest creation to include idp proxying elements/attributes based on the extended meta configuration. The AuthnRequest arrives on the IDP site: IDPSSOFederate class. It should be able to act on SP role and recreate the AuthnRequest. This class should call SAML2IDPProxy SPI to find out the authentication IDP's provider id and send it to the authentication IDP. Once the authentication IDP sends back the AuthnReponse to IDPSSOFederate (SP role). It should be able to switch it role to IDP and forward the AuthnResponse to the real requester (SP). 6.4 IDP Proxying in SLO In current SAMLv2 implementation, SPSingleLogout class is the class which initiates the LogoutRequest from SP to IDP. The LogoutRequest arrives on the IDP site: IDPSingleLogout class. It should find the partner provider based on federation session. Partner provider are those providers who have previously federated via this IDP proxy. Now IDPSingleLogout class acts on SP role, and creates new LogoutRequest to each partner provider. After collecting all the LogoutResponse from each IDP. IDPSingleLogout acts on IDP role again and send back LogoutResponse to original SP. 18 Copyright 2007 Sun Microsystems, Inc. All rights reserved.
Appendices, Version 7 Appendices TBD Copyright 2007 Sun Microsystems, Inc. All rights reserved. 19