Building Identity-Enabled Web Services

Print-friendly Version

Last October, the article Federated Identity: Single Sign-On Among Enterprises introduced identity federation as it relates to single sign-on (SSO) and demonstrated how Security Assertion Markup Language (SAML) and the Liberty Identity Federation Framework (ID-FF) offer standard mechanisms for cross-domain SSO. For example, employees can log in to the employer's portal and subsequently access resources at a supplier site without logging in to the latter. That article also briefly described the Liberty Alliance Project's Identity Web Service Framework (ID-WSF) and its capabilities for identity-enabling Web services.

At a technical session at JavaOne 2005 in San Francisco, we delved into ID-WSF and the new developments in the Java Community Process and in Sun's products that enable you to efficiently build identity-enabled Web services. This article recaps the content of that session. Specifically, you'll learn the following:

• How Liberty ID-WSF identity-enables Web services
  
  
• How components that are based on the Java 2 Platform, Enterprise Edition (J2EE platform), such as Java Specification Request (JSR) 196, insulate you from the mechanics of ID-WSF
  
  
• How Sun Java Studio Enterprise (henceforth, Java Studio Enterprise) will automate the creation of identity-enabled Web services

Many enterprises have heterogeneous, complex IT environments that cause numerous logistical and support issues. To complicate matters, those same enterprises are now exposing and deploying Web services outside the firewall to customers and partners.

Transport security protocols, such as Secure Sockets Layer (SSL) and Transport Level Security (TLS), help secure the communication among nodes, but that's not always enough. Even with client-authenticated TLS, the ultimate Web-service provider only knows the identity of its immediate consumer—the intermediary—with no secure records of the ultimate consumer. See Figure 1.

Figure 1: The Imperfect Scenario: Web-Service Provider Unaware of Ultimate Consumer's Identity

What we need is end-to-end security. See Figure 2.

Figure 2: The Improved Scenario: Web-Service Provider Aware of Ultimate Consumer's Identity

End-to-end security is ensured, in part, by the WS-Security standard, which defines how a Web-service consumer signs and, optionally, encrypts messages so that the consumer's identity is transparent to Web-service providers along the processing chain. However, WS-Security stops short of identity-enabling Web services.

Consider this scenario—

An enterprise plans to add a calendar channel to its employee portal with the following capabilities:

• Employees can browse their appointments and subscribe to coworkers' calendars.
  
  
• Employees can create their own private appointments that are invisible to others, that is, employees can view those appointments; their coworkers cannot.

The enterprise lacks a single calendar service. An employee's calendar service depends on that individual's location and work group, and no simple mapping exists from an employee's location and work group to the calendar server. That's because calendar migration may lag an employee's move by days or even weeks.

The enterprise now embarks on a plan to collaborate with several partners to enable a subset of employees to subscribe to partner employees' calendars. These questions immediately surface:

• How does the Web-service consumer (the employee portal) prove to the provider that it is acting on behalf of a particular employee?
  
  
• How should the Web-service provider (the calendar service) manage trust relationships with a large population of employees?
  
  
• How does the enterprise resolve identities across organizational boundaries?
  
  
• How does the Web-service consumer locate the correct Web-service provider for a particular employee?
  
  
• How does the enterprise accord employee access to partner sites without giving the partners a roster of the employees?
  
  
• How does the enterprise extend solutions to its partners without imposing its vendor choices on the partners' own infrastructure?

Enter Liberty's ID-WSF. Built on existing industry standards, such as WS-Security, SAML, XML Signature and XML Encryption, ID-WSF extends those standards to resolve the problems of identity-enabling Web services. See Figure 3.

Figure 3: Relationships Among ID-FF, ID-SIS, ID-WSF, and Other Standards

ID-WSF comprises the following:

• Mechanisms for leveraging browser-based authentication of end users or, alternatively, for enabling Web services to authenticate users through credentials
  
  
• A trusted authority that can issue assertions of user identities, attributes, and roles
  
  
• A capability that locates an identity-based service, with which Web-service consumers can find the correct Web-service providers for specific users
  
  
• A built-in privacy component—so that users can access systems by revealing only that they are authorized to do so
  
  
• A mandatory conformance program to promote interoperability

In addition, Liberty's Identity Service Interface Specifications (ID-SIS) build on ID-WSF to deliver service definitions for numerous situations, such as the following:

• Personal Profile Service, which specifies the principals' basic profile, such as names and contact details
  
  
• Employee Profile Service, which stores the employees' basic profile, such as names and contact details
  
  
• Contact Book Service, with which principals can manage contacts: for friends and family; for business; and even for themselves
  
  
• Geolocation Service, which presents geographical data associated with principals
  
  
• Presence Service, which contains presence information associated with principals, that is, their availability for communications over a network, such as instant messaging

In brief, ID-WSF identity-enables Web services by extending the notion of security for Web services to include end users. See Figure 4.

Figure 4: The Ultimate Scenario: Security of Web Services Extended to End Users

Let's take a look at a simple ID-WSF interaction, in which a Web-service consumer authenticates an end user and invokes a Web service on the user's behalf. See Figure 5.

Figure 5: A Simple ID-WSF Interaction

The authentication process proceeds as follows. These steps correspond to those in Figure 5:

1. You authenticate end users either by bootstrapping from ID-FF SSO or by presenting the user's credentials to the ID-WSF Authentication Service. Either way, the Web-service consumer obtains a resource offering for the Discovery Service. What does that offering do? Two things—
   
   
   • It references a Web service in the context of a particular end user.
     
     
   • It holds an endpoint for that service—essentially a URL—and a credential with which the Web-service consumer can access the service at that endpoint on behalf of the end user. The credential is an SAML assertion, that is, a signed XML token that contains a combination of the user's identity, attributes, and roles.
   
   
2. The Web-service consumer locates the target Web-service provider by querying the Discovery Service. That is, the Web-service consumer creates a Discovery Service query with the resource offering, including the credential in a Simple Object Access Protocol (SOAP) header, and sends that query to the indicated endpoint.
   
   
3. The Discovery Service returns a resource offering—another endpoint and credential—for the target Web-service provider. This credential, shown in Figure 5 as "credential (WSP)," differs from the credential that accesses the Discovery Service, shown in Figure 5 as "credential (DS)."
   
   
4. The Web-service consumer invokes the target Web service with the resource offering, again including the latter in a SOAP header and sending the message to the endpoint specified in the resource offering.
   
   
5. The Web-service provider responds as appropriate.
   
   

For all its capability in enabling Web-service consumers to locate and invoke Web services on behalf of end users, ID-WSF imposes a certain amount of "boilerplate" on those consumers. See the code example WebservicesConsumerWithoutJSR196.java.

Products such as Sun Java System Access Manager (henceforth, Access Manager) contain libraries that simplify interaction with the Authentication and Discovery Services. Still, it's tedious to repeat the same pattern of interaction in each and every Web-service consumer. Here's the savior: JSR 196 (Java Authentication Service Provider Interface for Containers), with an objective of defining a standard service-provider interface by which you can integrate authentication mechanism providers with containers.

As of this writing, JSR 196 is still in progress. This section reflects the current draft but is subject to change as the specification proceeds through its approval cycle.

You deploy a JSR 196 provider into a J2EE container (for example, Sun Java System Application Server) to handle authentication. In the context of Liberty ID-WSF, the process entails two requests:

• Outgoing request, which adds security tokens, signs messages, and interacts with Discovery Service to locate target Web-service providers.
  
  
• Incoming request, which verifies message tokens or signatures and then extracts principal data or assertions before adding them to the client security context.

Consequently, the Web-service consumer and provider can function without much of the boilerplate ID-WSF code. In fact, with the JSR 196 abstraction, the same consumer and provider can operate largely unchanged under different authentication mechanisms. What tremendous time and bandwidth savings!

Here's an example of how JSR 196 simplifies development in a scenario of enterprises partnering through Web services.

ABC Circuits, a manufacturer of circuit boards, would like its employees to be able to order parts directly from CMT Chips. Both companies have their own independent identity-management systems. In its system, ABC has accorded a subset of its employees the purchaser role with a purchasing_limit attribute that limits their per-transaction dollars.

Let's assume that ABC and CMT have already exchanged a base level of metadata, that is, they have each other's Public-Key Infrastructure (PKI) certificates and endpoints and they have defined the role and purchasing_limit attributes. ABC would like to—

• Authorize the employees with the purchaser role to purchase chips up to the limit specified in purchasing_limit.
  
  
• Retain the privacy of the identities of those employees. ABC has learned a tough lesson: When a previous partnership ended in acrimony, the ex-partner used the ABC employee roster to recruit ABC's employees.

See Figure 6 for the architecture of the implementation.

Figure 6: Architecture of Example Scenario (Click to enlarge.)

Here is how the scenario plays out in ID-WSF:

1. John Smith, an ABC Circuits employee, accesses the ABC Portal from his browser.
   
   
2. The portal authenticates John with Access Manager, which in turn returns an authentication token that contains a resource offering for the Discovery Service.
   
   
3. John accesses the Purchasing Application portal to acquire CMT chips.
   
   
4. With the resource offering, Purchasing Application queries Access Manager's Discovery Service implementation for the CMT Chips Web service.
   
   
5. Discovery Service looks up the policy, verifies that John has the purchaser role, returns the CMT Chips resource offering, including a token that contains John's role and purchasing limit.
   
   
6. Purchasing Application accesses CMT Chips with the resource offering.
   
   
7. CMT Chips verifies the token and the role with its instance of Access Manager, executes the relevant business logic, including a check of the order total against the purchasing limit, and returns a response message.
   
   
8. Portal Purchasing Application returns the results.

See WebservicesConsumerWithJSR196.java, the source code for the Web-service consumer.

In this scenario, after successful authentication of the user, the Web-service consumer simply assembles the message and hands it off to the JSR 196 provider—trouble free!

See WebservicesProviderWithJSR196.java, which pertains to the Web-service provider.

The provider needs no Liberty-specific code; it simply executes business logic against the incoming request and then responds. The JSR 196 provider verifies the incoming request and high-level access control (that is, it confirms that John has the purchaser role) before signing the outgoing response.

Now that a programming abstraction is available for identity-enabled Web services in general and ID-WSF in particular, how do all the pieces come together? Just perform two more tasks:

• Register the newly created Web service with the Discovery Service so that Webservice consumers can find it.
  
  
• Deploy the service into a container so that Web-service consumers can invoke it.

And that's where Java Studio Enterprise comes in. From a wizard in that IDE, you can create Web-service providers. New capabilities currently being prototyped will prompt you for the location of the Discovery Service and other relevant information as you deploy the Web service. See Figure 7.

Figure 7: Java Studio Enterprise: Prompts for Location of Discovery Service and Other Information (Click to enlarge.)

As soon as the service is deployed, Java Studio Enterprise registers it with the Discovery Service through a Discovery Update operation. You're then ready to run the client.

In the following example, ABC purchasing clerk Alice, who has a $1,300 purchasing limit, authenticates at the ABC portal, fills her shopping cart with chips, and checks out. At this point, ABC's purchasing application invokes the CMT Web service. Since the total cost falls within Alice's purchasing limit (as expressed in the SAML assertion that's included as a SOAP header with the Web-service invocation), the checkout operation succeeds. See Figure 8.

Figure 8: An Example of a Successful Chip Order

Clicking Credential on the right navigation shows the SAML assertion as received by the CMT Web-service provider, as follows.

<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
AssertionID="sc32583d034d36e7fcbdd7b3ea7c515ad554c53a201" IssueInstant="2005-
09-30T18:45:19Z" Issuer="http://krishna3.sfbay.sun.com:8080/amserver/Liberty/
disco" MajorVersion="1" MinorVersion="1">
  <saml:Conditions NotBefore="2005-09-30T18:42:19Z"
  NotOnOrAfter="2005-09-30T18:52:19Z"></saml:Conditions>
  <saml:AuthenticationStatement AuthenticationInstant="2005-09-30T18:45:11Z"
  AuthenticationMethod="urn:liberty:security:2003-08:null:null">
    <saml:Subject>
      <saml:NameIdentifier Format="urn:liberty:iff:nameid:federated">
        S2T4R5E7A8K1I8S9O2V9E0R
      </saml:NameIdentifier>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:oasis:names:tc:SAML:1.0:cm:bearer
        </saml:ConfirmationMethod>
      </saml:SubjectConfirmation>
    </saml:Subject>
  </saml:AuthenticationStatement>
  <saml:AttributeStatement>
    <saml:Subject>
      <saml:NameIdentifier Format="urn:liberty:iff:nameid:federated">
        S2T4R5E7A8K1I8S9O2V9E0R
      </saml:NameIdentifier>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:oasis:names:tc:SAML:1.0:cm:bearer
        </saml:ConfirmationMethod>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Attribute AttributeName="UserRole"
    AttributeNamespace="urn:oasis:names:tc:SAML:1.0:assertion">
      <saml:AttributeValue>
        purchaser
      </saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="PurchaseLimit"
    AttributeNamespace="urn:oasis:names:tc:SAML:1.0:assertion">
      <saml:AttributeValue>
        1300
      </saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

Note these details:

• Alice's role (purchaser) and purchasing limit (1300) are shown in bold.
  
  
• The NameIdentifier element (also boldfaced) contains a pseudonym for Alice so that her real identity is invisible to CMT. This pseudonym is persistent; Alice can check the status of her order later on.

Now let's see what happens when Bob, another ABC purchaser, tries to buy the same basket of chips. See Figure 9.

Figure 9: An Example of an Unsuccessful Chip Order

Bob's order failed because the total of $1,110 exceeds his purchasing limit of $1,000, as the SAML assertion indicates. See below.

<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
AssertionID="sc32583d034d36e7fcbdd7b3ea7c515ad554c53a201" IssueInstant="2005-
09-30T18:50:52Z" Issuer="http://krishna3.sfbay.sun.com:8080/amserver/Liberty/
disco" MajorVersion="1" MinorVersion="1">
  <saml:Conditions NotBefore="2005-09-30T18:47:52Z"
  NotOnOrAfter="2005-09-30T18:57:52Z"></saml:Conditions>
  <saml:AuthenticationStatement AuthenticationInstant="2005-09-30T18:49:32Z"
  AuthenticationMethod="urn:liberty:security:2003-08:null:null">
    <saml:Subject>
      <saml:NameIdentifier Format="urn:liberty:iff:nameid:federated">
        NAWICAGCAMA4GCCQGSIB3DQ
      </saml:NameIdentifier>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:oasis:names:tc:SAML:1.0:cm:bearer
        </saml:ConfirmationMethod>
      </saml:SubjectConfirmation>
    </saml:Subject>
  </saml:AuthenticationStatement>
  <saml:AttributeStatement>
    <saml:Subject>
      <saml:NameIdentifier Format="urn:liberty:iff:nameid:federated">
        NAWICAGCAMA4GCCQGSIB3DQ
      </saml:NameIdentifier>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:oasis:names:tc:SAML:1.0:cm:bearer
        </saml:ConfirmationMethod>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Attribute AttributeName="UserRole"
    AttributeNamespace="urn:oasis:names:tc:SAML:1.0:assertion">
      <saml:AttributeValue>
        purchaser
      </saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="PurchaseLimit"
    AttributeNamespace="urn:oasis:names:tc:SAML:1.0:assertion">
      <saml:AttributeValue>
        1000
      </saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

Thus, effectively and accurately, CMT can enforce its own purchasing limit policy as ABC manages its employees' limits, sending each limit as an attribute with every purchase request.

In a nutshell—

• ID-WSF specifies protocols to implement end-to-end, identity-enabled Web services.
  
  
• JSR 196 defines a mechanism for extending containers to implement authentication schemes, such as ID-WSF.
  
  
• Java Studio Enterprise and Access Manager seamlessly enable the leverage of IDWSF and JSR 196 in application development.

JSR 196 providers and code samples for Sun Java System Application Server 9 (aka the open-source Project Glassfish) will be available for download from sun.com later this year. Watch Pat Patterson's blog for details. As soon as the providers and samples are available for download, you'll see a posting there. Bear in mind that those providers will require Access Manager 6.3 or later versions.

• Liberty Alliance
  
  
• OASIS Security Assertion Markup Language (SAML) 2.0
  
  
• JSR 196
  • Main page
  • Providers in Sun Java System Application Server 8.1
  
  
• Sun Java Studio Enterprise
  • Main page
  • Software Forum
  
  
• Sun Java System Access Manager
  • Developer home
  • Software Forum
  
  
• Java Web Services Developer Pack
  
  
• Sun Java Enterprise System and Sun Java System Suites
  
  
• Article: What's New in SOA and Web Services?

Rajeev Angal is the architect of Sun's identity products: Sun Java System Access Manager, Federation Manager, and other flagship, access-management products built on open standards. He has over 19 years experience in the software industry, spanning UNIX kernel development, network management, and, for the past six years, identity and Web services security. In addition, Rajeev represents Sun at the Liberty Alliance Project and other security-related standards bodies. He holds a B.S. degree in Electrical Engineering from Indian Institute of Technology, Delhi.

Srividhya (Vidhya) Narayanan, a member of the Java Studio Enterprise development team, is working on service-oriented architecture (SOA) tooling capabilities. Before her current assignment, she was the engineering lead for identity management at Market Development Engineering at Sun. Vidhya has over nine years of IT industry experience on enterprise application architecture and development with Commerce One and Philips. She holds an M.S. degree in Computer Engineering from Syracuse University, New York.

Pat Patterson, a technical architect at Sun, has been working on security and identity management since 1997, when he joined Trustbase Ltd., a software development company in London, England. When Sun acquired Trustbase in 2000, Pat became an engineering manager in secure Web services at Sun. After a four-year stint in product management, he returned to engineering early in 2005, focusing on federation and identity-enabled Web services. Pat's blog centers on identity-related topics.

Malla Simhachalam, a member of the Access Manager engineering team, has over eight years of IT industrial experience. He joined Sun five years ago and is presently focusing on building identity management and identity Web services. Before joining Sun, Malla developed Web single sign-on and real-time systems solutions for CMC India's R&D Center. He holds an M.S. degree from the Indian Institute of Technology, Delhi.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena. Marina blogs on Sun products and technologies.