OpenSSO Architecture Overview1.0 AudienceThis document is designed to provide a overview of OpenSSO architecture. Finer details of each component are covered in individual documents. An effort has been made to structure the text to cater to the needs of both those who want just the big picture an d those who want to understand the internals. Please refer to OpenSSO docs [1] for a overview of the technical conceptual model and use cases that form the basis of a web access management product. This doc should not be used for product information the official product documentation [2] is more appropriate for this, especially the 'Technical Overview document, which provides a excellent introduction to customer visible aspects of OpenSSO.

2.0 30 Second (Elevator Pitch) ArchitectureOpenSSO provides complete and flexible access management and federation management capabilities, in the form of a simple lightweight Java EE application [3] thereby scaling horizontally and vertically as enterprise security needs change over time. The following services are provided : 1. 2. 3. 4. 5. 6. 7. Authentication Authorization (Policy) Session (SSO) Auditing/Logging Identity Repository access Federation Web Services Security

Figure 1 The server component of services 1 thru 5 is a simple Servlet receiving requests as XML and returning responses in XML. [FAM web.xml|OpenSSO Architecture Overview^web.xml] shows the Servlet mappings. Services (6) and (7) are based on federated identity and web services standards (OASIS SAML [3], Liberty Alliance [3], WS-Security [3], WS-Trust [3], WS-Federation [3]). The client component of each of these services is provided as a Java API. Services 1 thru 3 are available as a C API. These APIs allow applications and services to consume identity services offered by OpenSSO. A file called AMConfig.properties provides configuration for client APIs. Each service provides a public service provider interface (SPI) that allows the service to be extended. A browser based console and command line interfaces are supplied with the product to configure and manage OpenSSO. Local bootstrapping and per server configuration is provided via the bootstrap file. (Note - in earlier releases AMConfig.properties provided the bootstrap information, OpenSSO 8.0 onwards AMConfig.properties is only used to configure the client). Policy Agents (PAs) are provided as add-on components one for each container type that ease the protection of web based network resources (enterprise applications and services). PAs consume the public APIs mentioned above and take care of the integration with the specific container such that its presence is largely transparent to the contained protected resources. Please refer to [ 8] for a complete list of currently supported PAs. Appendix A summarizes all the external interfaces exposed by OpenSSO.

3.0 Design Goals3.1 Cater to Both Web and Non-Web-based Resources.There is often a misconception that OpenSSO caters to Web Access Management (WAM) only. While it is true that most OpenSSO deployments address the web single sign-on problem, the core design caters to both web and non-web applications.

3.2 SecurityRuntime security that enables resources to be protected as configured and OpenSSO services accessible to authorized entities only. Administration security to ensure only authorized updates to configuration, Deployment security that implements best practices for OpenSSO installation on misc operating systems, containers, etc. All actions : administration related and runtime access related are logged.

3.3 Ease of Deployment and AdministrationMinimum steps to get OpenSSO up and running.

3.4 Performance, Scalability and AvailabilityNo single point of failure, ability to scale horizontally and vertically

3.5 Distributed ArchitectureServer and client components can be deployed across the enterprise or across domain boundaries. As a result all APIs need to be remoteable. Exposure via Web Services is a key goal here to enable exposing Identity as a service in a SOA environment.

3.6 Flexibility & ExtensibilityEvery service needs to expose a service provider interface (SPI) that allows the framework to be expanded to spec ific deployment needs.

3.7 Open StandardsAdopt standards as far as possible.

3.8 Internationalization (i18n)All customer facing messages i18n'ed includes all APIs, CLIs and UI.

4.0 Common Service InfrastructureThis section describes the common design patters followed by all services.

4.1 Communication ProtocolClients (e.g. agents, applications using SDK) request OpenSSO services. ( Please note that in this context we are not referri ng to the "client" as in a useragent accessing a protected resource.) OpenSSO services issue notifications to registered clients to communicate events (e.g. session expiry, policy decision change, user profile change, configuration change etc) A mix of proprietary XML over https (Platform Low Level, or PLL) and SOAP is used for communication between clients (eg agents, SDK) and server. Following figure shows the basic communication between OpenSSO components.

Figure 2' [5] provides the common PLL DTD and related service specific DTDs. Figure 3 shows the class diagram representing the key elements in these DTDs. Clients send Requests to services; the PLLServlet on the OpenSSO server receives these requests and dispatches them to the ap propriate service handler. Service handlers process the request and format a Response that is then returned to the client. Please refer to the DTDs for specific operations supported by each service. Low -level design documents for each service explain each operation in detail.

Figure 3 A special configuration attribute : "com.iplanet.services.comm.server.pllrequest.maxContentLength" allows deployments to limit the size of the the network data payload (default value is 16K) as a simple mechanism to prevent network attacks on exposed interfaces via PLL.

4.2 Naming ServiceThe Naming Service is a special service that provides bootstrap information on the location of OpenSSO servers to the clients. The Naming service contains information on the location of each OpenSSO service. Example naming service URL : http://famserver.sun.com/fam/namingservice A request to the naming service returns the URLs of individual OpenSSO services : Eg: http://famserver.sun.com/fam/auth service http://famserver.sun.com/fam/sessionservice http://famserver.sun.com/fam/policyservice http://famserver.sun.com/fam/loggingservice

4.3 Client APIMost of the communication protocol and bootstrapping described earlier is encapsulated in APIs Java and C one for each service exposed. The APIs internally implement a cache that is kept in sync with the server in two ways :

a) Polling mode/lazy cache - cache entries go stale and are retrieved from the server reactively. b) Notifications mode the API explicitly registers for events and uses the events to sync the cache. All Client API access must carry proof of authentication before the request is served - please see description of SSOTOken and Authentication subsection on how this works. Access to a service via APIs is also resricted on the context and the user's roles and privileges.

4.4 SPIService Provider Interfaces make each OpenSSO service extensible. SPIs supplied by each service are listed in respective sections in this document. The SPIs are Java interfaces that are implemented by concrete classes and registered with the OpenSSO via configuration. Several plugin implementations are preregistered out-of-the-box. Specific deployments may choose to extend them or to replace them entirely.

4.5 ConfigurationConfiguration data needed for each OpenSSO service is specified in two ways : a) "bootstrap" a per-server flat file co-located on the server instance. b) A Configuration repository (eg Embedded or separate LDAP server) shared across all OpenSSO servers forming the same cluster. The core purpose of "bootstrap" is to locate the Configuration repository to store the configuration required at runtime.

4.6 Multiple Servers and SitesAs noted earlier, horizontal scalability is achieved by multiple OpenSSO servers acting as a cluster. Typically a load balancer is deployed to distribute load appropriately to the underlying servers. Servers may be distributed across geographic locations. To enable physical servers to be hidden behind load balancers and to allow geolocality for clients, OpenSSO supports the notion of a site which is essentially a group of colocated OpenSSO servers that are served via the same URL exposed by the fronting load balancer.

4.7 SSOTokens : The GlueUsers authenticate using credentials (eguserid/password, Radius, certificate, etc). Similarly misc distributed OpenSSO entities (clients & agents) also use their server credentials to authenticate to OpenSSO. The result of a successful authentication results in th e creation of a Session for the user/entity and a opaque handle (essentially a secure random number) known as an SSOToken. SSOToken becomes the basis for exchanging proof of authentication between OpenSSO entities. For example, a web based user authentication to aOpenSSO server results in creation of an SSOToken stored as a cookie in the user's browser. As the user visits different protected resources from this browser, the SSOToken is propagated to these resources they (via a embedded client API or agent) can then dereference the SSOToken by sending a validate request to a OpenSSO server that returns either an error or a copy of the session containing the prior authentication information such as auth level, auth module, instant of authn, idle time, etc (details in session id). Access to some OpenSSO services, such a s Policy and logging require presentation of both the SSOToken of the application as well as SSOToken of the user to allow only designated applications to access these services. Sessions (and hence SSOTokens) are invalidated when a user logs out or the session expires or a user in an administrative role invalidates a user's session.

4.8 Security : Credentials and DelegationTransport level communication between OpenSSO entities is secured with SSL. Some passwords and credentials need to be stored on local OpenSSO server systems (bootstrap and serverconfig.xml) : a) Configuration store location and userid+password. b) Digital signing keystore location and credentials to access it. c) SSOToken encryption key. OpenSSO relies on Operating System's filesystem security to protect access to these files. Some passwords and credentials need to be stored on the configuration store - for example, Identity Repository location and credentials are required to be able to search for users. Read access is sufficient unless OpenSSO is expected to be an interface to writing to user profile data and/or needs to provide 'User Management' features such as management of roles and groups. All passwords stored locally in files and in configuration directory are encrypted with a secret key using PBEWithMD5AndDES algorithm. Strength of credentials used by regular users to authenticate to OpenSSO relies on the underlying authentication framework. For example if LDAP directory (such as Sun Directory Server) is setup as the authentication mechanism, OpenSSO accepts userid and password from the users and verifies against the directory servers. It is recommended passwords are stored as 1 -way hash values in the direcrory and they follow a strictly enforced "password policy" that mandates : y y password strings be of minimum length (eg 8 characters) pasword contains at least one or more special characters

y y y

passwords do not contain substrings from userid passwords are checked against a history of past passwords to ensure passwords are not reused frequent password reset mechanisms OpenSSO relies on the underlying LDAP directory to enforce these policies. Please refer to Sun Directory Server 5.2 documentation for details. All errors related to violation of the password policies are reported as an exception by the LDAP server. OpenSSO prompts the user to fix the errors. Example flow : User's password has expired. Next time the user attempts to login via OpenSSOauthenticatio UI - OpenSSO receives a "password reset' exception from the directory - this triggers a password reset UI shown to the user - OpenSSO attempts to reset the password on the LDAP directory - LDAP directory checks password policy and returns an error if its violated. OpenSSO reports the error back to the user - to enter the proper password. The sequence continues until LDAP directory returns success. A realm is the administrative unit of administering OpenSSO. With the exception of initial bootstrap information that is configured at install-time the rest of OpenSSO configuration is accomplished via one the following mechanisms : a) the Admin Console GUI based interface to all OpenSSO components. b) Command Line Interfaces :amadm and fmadm. c) Administration APIs in effect both (a) and (b) are built using these APIs. Administrators are assigned roles that allow users assigned these roles to perform all or specific tasks in a realm. The realms form a hierarchy starting with the root realm created out of the box. Specific component configur ation can be attached to a realm, please refer to specific component documentation for details on how they leverage realm based delegation. Figure 4 depicts an example deployment that uses a hierarchy of realms to distribute administration responsibilities.

Figure 4 Table 1 shows the default privileges and roles they are assigned to. _Privilege_ 0 "None" - default 1 Read only access to data stores _Roles_ No access to any data - default for all regular users Custom roles can be added and assigned this provilege either for all realms or particular realms. Policy Administrator applies to policies in all realms. Realm Policy Administrator applies to policies in a particular realm. Realm Administrator access to all realms. Sub-realm Administrator access to a particular realm.

2 Read and write access only for policy properties

3 Read and write access to all realm and policy properties

4 Read and write access to all log files and enable/disablr logs and modify configuration 5 Read only access to all properties and services

Log/Audit Administrator

Custom roles can be added and assigned this privilege either for all realms or particular realms.

4.9 RepositoriesOpenSSO services needs to interact with miscellaneous backend stores. A common LDAP connection pooling facility allows efficient use of network resources. In a extreme deployment the following 4 distinct reposiotries can be configured : 1. 2. 3. 4. User repository(ies) - consumed by IDRepo service to provide profile information Configuration repository - consumed by the common configuration service to store service specific data Authentication store(s) - consumed by Authentication service as the authoritaiveautehntication source Policy Subjects store(s) - consumed by Policy service to evaluate policy subjects. In the simplest scenario a single LDAP repository is sufficient to cater to all the 4 kinds, however, the typical case tends to be configuration store to be separate from the rest of the stores that use the same corporate directory.

4.10 LoggingA common Logging service is invoked by all components - both residing on the server and those on the client. This allows the actual mechanism of logging (such as formatting (eg ELF/XML) and destination (egflatfile/RDBMS))to be seperated from contemts of the logs, which are specific to each component. The common log attributes for all kids of logs are : y y y y y y y y Timestamp Logged By (identity of a authorized user who created the log entry - typically client component) Userid (identity of the user who performed the action) IP Address (of the user agent used to access the component) Domain name (DNS domain of client where user authenticated from) Module name (authentication type of how the user authenticated) Message ID (unique identifier of the specificv log message) Log level (level of the message) Secure remote logging facilities (API and over the wire protocol) results in centralized logging. Administrators can control log levels, authorize the entities that are allowed to create log entries and configure secure logging. Secure logging follows a standard log digital signing mechanism to ensure logs are tamper proof. Logging API and SPI are based on jsr045 (JDK Logging) - it is enhanced for use in a secure environment. amverifyarchive CLI allows administrators to verify the authenticity of the secure logs. Please refer to low lev el design of the logging service for details.

4.11 Putting it togetherThe following figure shows a physical deployment of OpenSSO server and how things get bootstrapped at runtime. Start with the OpenSSO server installed in a Java EE container on the top left corner. Each arrow represents a pointer to the physical location of a component via a identified configuration parameter.

Physical_Deployment_and_config_bootstrapping} At startup the OpenSSO server (deployed as opensso.war in a Java EE application server) looks up a well known directory ($HOME/.openssocfg on the local host) to find the location of the bootstrap file on the local host. The bootstrap file contains the location of the configuration store (default : embedded ldap directory. The general format of the bootstrap file is as follows: ldap://ds-host:ds-port/server-instance-name?pwd=encrypted-amadmin-password& embeddedds=path-to-directory-service-installation&basedn=base-dn& dsmgr=directory-admin&dspwd=encrypted-directory-admin-password Once the server is able to access the configuration store - it then initializes all the services - that in turn may access different data stores. Please refer to Appendix A for a summary of configuration read by each service. Protection of the deployed WAR file and misc files on the local server are all protected using OS facilities - a typical deployment creates a special user (egamserver or root in the example above) and access is granted to privileged users only. The WAR itself may execute as this special user or may be assigned read only privileges to the config files. Debug and log files created on local server need appripriate write permission assigned to the WAR execution, and again special care needs to be taken so that non-privileged users do not have access to these files.The following figure provides a overview of each OpenSSO component interacts with each other in a typical SSO scenario.

Federation Service (described in Section 9.0 below) allows user authentication to be delegated to a trusted and compliant Identity Provider (IdP). OpenSSO working in this mode is termed a "Service Provider" (SP). A key design goal is to ensure all OpenSSO services, including agents based SSO work exactly the same way in the federated SSO case as with local authentication case. This is accomplished via invoking the Authentication Service to issue aSSOToken at the end of a successful federation protocol. A successful "federation protocol" is based on a signed xml fragment issued by an IDP being successfully validated at the SP end (some additional processing rules, defined by protocol specs, also need to be executed to deem the federated sso successful). If the assertion does not validate (ie signature verification fails or the additional processing rules fail) - authentication is deemed to have failed. When configured for Federation, in the interaction diagram above, "Authentication User Interface" is replaced with the appropriate "Federation Protocol". This protocol results in the configured IdP being invoked for user authentication; upon successful authentication, authentication resumes as depicted above. Upon failure, local authentication fails. Please refer to Federation LLDs for details.

5.0 Identity Repository Access ServiceThe Identity Repository (IDRepo) service allows OpenSSO to integrate a existing user repository, such as the corporate LDAP server. It provides an abstraction to access user profiles as well as group & role assignments consumed by client and other OpenSSO services. This abstraction is capable of spanning multiple repositories even of different types. The current implementation supports any LDAPv3 compliant repository (certified for Sun Directory Server and Active Directory). The IDRepo SPI can be used to build new adapters for repositories not currently supported.

Figure 5

6.0 Authentication ServiceThe Authentication service is based on Java Authentication and Authorization Service (JAAS). Several authentication modules are supplied out of the box, examples : LDAP, Radius, SecureID, Windows Desktop, Certificate, Active Directory. New authentication modules can be added using a JAAS based SPI. Figure 6 shows all the authentication subcomponents and how they work with core infrastructure pieces described earlier and other components. Following auth subcomponents are identified :

width='400' height='400' Figure 6 JSP Pages represent the UI pages that are shown to users to authenticate. These JSPs are completely customizable. The design follows the standard MVC pattern, the model supplied by the authentication client API. Authentication API :Remoteable interfaces. Notice the AuthenticationRequest in Figure 3 maps to the theAuthenticationRequest handler in Figure 6 that handles the XML sent over PLL. Distributed Authentication (DA) : DA is in effect an extension of OpenSSO that allows the the UI portion of authentication to be deployed separately from the server, typically in extranet situation where it is more desirable to deploy a proxy like DA in the DMZ instead of the entire OpenSSO server. DA uses the authentication client APIs to pass gathered credentials to the server for verification. Authentication Middle Tier : This forms the core of authentication service executing the common processing across authentication modules. It is driven by JAAS. A key responsibilities of this layer include identification of appropriate plan to authenticate the user (identify auth module, load appropriate JSP pages) and to to create the appropriate session for the authenticated user. Authentication SPI : The SPI is based on JAAS authentication module with some enhancements. Authentication Modules : The actual modules configured in the system. Authentication levels are globally defined numbers attached to each auth module. Mechanisms are provided to upgrade a users session by authenticating the user to the appropriate auth module that satisfies the requested auth level.

7.0 Session ServiceThe concept of SSOToken is described in an earlier section. Figure 7 shows Session subcomponents and their interaction. A session also serves as a efficient inter-process communication mechanism to communicate simple attributes related to the specific authenticated user.

Figure 7 width='400' Following attributes are populated by default : *Principal *Universal identifier *Time user authenticated *Authentication modules list (list of auth modules the user has autehnticated to) *Authentication level *Last accessed Time (idle timeout processing) *Max Time (hard limit at which the session is destroyed). Server side code can add new attributes to be shared with clients. Clients can also add custom attributes as long as those attributes are configured on the server end.

Session Persistence architecture is illustrated below :

Figure 8 width='400' It uses the efficient messaging capabilities of a Message Queue to push session information to a persistent store based on Be rkeley DB. Two key features are enabled with this : a) Session Failover : allows an alternative OpenSSO server to pick up a given user session when the server owning the original session fails. b) Session Constraints : allows deployments to specify constrains on sessions, such as 1 session per user.

8.0 Policy ServiceThe Policy Service provides the authorization service of OpenSSO. It is a rules based engine. A Policy comprises : Service name schema for the policy type that describes the syntax of policy (amPolicy.xml) y y y Rule : Resource, Action and Value. Subject(s) Condition(s Figure 9 shows how Policy service is built. Note the PolicyServiceRequestHandler maps with the PolicyRequest XML element in Figure 3.

Figure 9 width='400'

9.0 Federation ServicesFigure 10 illustrates the concepts common to all federation standards and how they interact with other OpenSSO components:

Figure 10' width='400' The following Web single sign-on protocols are implemented : y y y SAML1.1 ID-FF 1.2 SAML 2.0

y

WS-Federation 1.1 Following Web Service standards are provided :

y y

ID-WSF 1.1 WS-Security (WS-I BSP). [6] provides a complete list of use cases applicable to federation services. Below is a brief description of how federated SSO works. The OpenSSO Federation Service is a bunch of web based standard protocols and processing rules that enables single sign-on between two or more separate+independent domains. These domains together form a "Circle Of Trust" (COT). Each domain in a COT is identified by a unique entity id, a COT has at least one authenticating entity (IDP). The entities in a COT are designated one or more of the following roles:

y y

IDP (Identity Provider) responsible for authenticating a user, establishing the user identity and issuing an "assertion" to a relying party. SP (Service Provider) relying party that consumes an "assertion" from a trusted IDP. Assertion is typically a standards based signed XML blob that contains the following information :

y y y y y y y

Subject - identifies the authenticated user Authentication statements - info on how the user was authenticated Attribute statements (optional) - attributes of the user Validity - describes how long the assertion is valid Audience - SP this assertion is targetted for XML signature XML encryption (optional) "Metadata", expressed as a XML - encapsulates information about each entity in a COT - each entity publishes its metadata Metadata contains :

y y y y y

entityid protocol information : endpoints, profiles and bindings accepted by the entiity role (IDP/SP) played by the entity. PKI information - public keys used to sign/verify encrypt/decrypt protocol data - such as assertions. PKI forms the basis of trust between communicating entities. OpenSSO provides administration interfaces (GUI and CLI) to configure COTs in each domain. This involves : importing the remote entity metadata and to configure local metadata (ii) setting up Public/private keys in OpenSSOkeystore for signing and encrypting assertions. Eg :OpenSSO in IDP role - will setup a "hosted" IDP and "remote" SPs it needs to serve assertions to. Eg: OpenSSO in SP role - will setup a "hosted" SP and "remote" IDP that it will rely on for authentication. NOTE : Since the Federation protocols are standards based - the "remote" ends may not be OpenSSO at all - they may be other compliant products. NOTE : The end result of a federation protocol for an OpenSSO in SP role is successful creation of SSOToken - exactly the same way a local authentication would. OpenSSO in IDP role relies on the native Authentication Service to authenticate users. Virtual Federation is a recently added feature of OpenSSO. Virtual Federation addresses two key issues in deploying federation : more than one federation standard in a Circle of Trust and (ii) legacy applications and existing authentication mechanisms. Using off the shelf simple http POST and data signing, legacy applications can push authentication and attribute information to a local OpenSSO instance acting as an IDP that in turn can be communicated to remote partner aplications (SPs) via standard federation protocols listed above.

10.0 Web Services Security (WSS)A typical SOA based system uses SOAP based reusable services. OpenSSO provides implementation of Web Services Standards : Liberty Alliance ID-WSF and what are collectively called WS-* specifications to allow a web services client to securely access a web services server. A key aspect of WSS is the notion of a "Trusted Authority". A Trusted Authority brokers trust between communicating entities. O penSSO provides a trusted authority in the form of Liberty Discovery Service or a Secure Tiken Service (STS).

11.0 Agents

Agents are based on OpenSSO client APIs - they are designed to protect web resources with no code changes to the resource business logic. Based on the standard 'interceptor' design pattern, agents intercept each incoming request and perform the necessary security check (authentication, authorization and auditing) before allowing control to be passed on to the protected resource. Agents for Java EE containers are based on Servlet filter and JSR 196 specs. Other containers, such as Apache, IIS, PeopleSoft, SAP, etc ar e based on proprietary interfaces provided by each. One of the key design goals of agents is to be transparent to the protected resource and as a re sult provide information about the authenticated user in the native form - such as a JAAS Subject for Java EE containers, REMOTE_USER for Apache, etc.

12.0 Console and Command Line Interface (CLI)Console is a web based application typically hosted on the OpenSSO server instance. Alternatively it can be deployed separately. As described in earlier sectons, both Console and CLI need admin user authentication and the appropriate role to access adminiatration functions. The communication between these admiistration interfaces and OpenSSO servers use the public apis summarized in Appendix A.