Find JSRs
Submit this Search


Ad Banner
 
 
 
 

JSRs: Java Specification Requests
JSR 351: JavaTM Identity API

Updates to the Original JSR

The following updates have been made since the original proposal:

2013.01.05:
The JSR has moved to JCP 2.9.


Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member: Oracle America, Inc.

Name of Contact Person: Prateek Mishra

E-Mail Address: prateek.mishra@oracle.com

Telephone Number: +1 617 872 7737

Fax Number: +1 781 442 1610


Specification Lead: Ron Monzillo, Prateek Mishra

E-Mail Address: ron.monzillo@oracle.com, prateek.mishra@oracle.com

Telephone Number: +1 781 442 0968, +1 617 872 7737

Fax Number: +1 781 442 1610


Initial Expert Group Membership:

IBM
Oracle
RedHat
SAP AG

Supporting this JSR:

American Express
Aspect Security
Boeing
Ericsson AB
OWASP



Section 2: Request

2.1 Please describe the proposed Specification:

The objective of this project is to define application programming interfaces and identity interaction models that facilitate and control the use of identity by applications and in access control decisions.

To meet this objective, we will define interfaces that are integrated with the Java security model and that enable a declarative application programming style. We will also define interfaces to attach meta-data to identity attributes (e.g., email address, social security number, bank account number, date of birth, nationality, gender) and a vocabulary of identity characterizing meta-data (e.g., issuer, validity period, usage constraints) to be used in support of the identity interaction models. We will define an attribute service as the point of governance and of interaction with distributed sources of identity. We will also define interfaces that do the following:

- Enable applications to act both as consumers and as providers of attributes
- Facilitate the insertion of access control checks in applications and the use of attributes in access control decisions
- Allow users to authorize disclosure and use of their identity attributes
- Sustain the protection of identity attributes during their propagation between applications and systems
Example: A developer creates a prescription renewal application for use by subscribers of a health care provider. The developer uses the Java Identity API to reference attributes of the subscriber such as subscriber identifier, preferred pharmacy, renewable prescriptions, and service affiliation groups. The developer may also utilize attribute meta-data such as the last time the attributes were updated.
The developer does not describe how the attributes are to be obtained. When the application is deployed by a specific health care provider, the attribute references are resolved against the distributed attribute sources and user authentication tokens in use by the health care provider. This linkage is established without recompiling or changing the application. Further, the governance aspects of the API support tracking and managing the use of attributes both within the application and in its communication with other components.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

The target platform is Java SE and the proposed API is intended to be applicable to Java platforms that retain the SE security framework (including Java EE). It is assumed that the proposed API will depend on a small set of basic services, including resource injection and life-cycle callbacks, that are provided by the encompassing environment.

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

This specification is targeted for compatibility with Java SE and Java EE platforms beginning with Version 6.0. We also expect the output of this project to be relevant to Java applications running in consumer appliances.

2.4 Should this JSR be voted on by both Executive Committees?

No

2.5 What need of the Java community will be addressed by the proposed specification?

The advent of social networking sites, the adoption of single-sign-on and identity federation services, and more generally, the increased use of the internet in conducting business, have combined to amplify the need for Java developers to be able to appropriately consume, produce, and safeguard the disclosure of network identity. The lack of adequate interfaces in the Java platform is forcing application, system, and identity framework developers to rely on non-standard interfaces, which is resulting in indirect, inconsistent, poorly integrated, and inferior support for network identity.

Java developers need interfaces that allow them to:

- encapsulate and attribute application-specific types and mechanism-specific security credentials to sustain their common use and interpretation as identity attributes

- interact (including lookup, read, create, and delete) in a portable fashion with identity information of potentially varying type and from potentially distributed sources

- establish references that identify the one or more attributes of the one or more entities that are to be the target of an interaction

- export attributes from applications such that they can be referenced in context from other systems, including in support of the processing of fine-grained policies during access control decisions performed in the context of the application.

- establish the use and authorization policies relating to any attributes they create, export, or otherwise manage.

- exchange attributes between applications and systems including in a manner that sustains authorization protection of the attributes


In addition to the needs of Java developers, an effective interaction model for network identity requires a governance model in which it must be possible to predict, monitor, and control (such as via access control checks) interactions by applications with identity attributes.

2.6 Why isn't this need met by existing specifications?

The Java security model protects the resources of the Java runtime environment from both the calling code and the entity (for example, user) on whose behalf the calling code is executing. Unlike the CodeSource object which provides a standard interface for identifying code and for certifying its integrity, the Principal interface, which is used to represent on whose behalf the code is running, standardizes only a very superficial representation of that entity. While Java defines some objects (e.g., KerberosTicket and X509Certificate) that encapsulate identity and identity qualifying information(for example, issuer and validity period) such objects are poorly suited to the task of representing identity values that are not intrinsic to the corresponding security mechanism and its associated transfer syntax (e.g., ASN.1). For example, neither a KerberosTicket or an X509Certificate can offer an effective Java binding for a generic identity attribute such as social security number. Moreover, as noted above, it is the Principal objects (e.g., KerberosPrincipal and X500Principal) that represent on whose behalf some java code is running. Information in any encapsulating credentials is not generally available when (for example) an access control decision is being performed, and the existing Principal interface represents only a name without any common capacity to represent identity qualifying information. As such, Java developers and the Java security model require additional interfaces to standardize a more complete representation and interaction model for identity attributes. Further, Java does not assign or otherwise establish a model or architecture for use in defining the terms that govern the disclosure of its representations of network identity.

2.7 Please give a short description of the underlying technology or technologies:

As an initial proposal, this JSR proposes to deliver standard interfaces and functionality at 3 layers.

Layer 1: Representation and JRE integration

We propose to define new attribute interfaces to represent identity attributes and associated meta-data. These interfaces would be used to facilitate common representation of existing Java Object types as identity attributes, to convey identity attributes within the Java access control context, to facilitate integration with the standard java.security.Policy decision interface, and to reference and represent content acquired from the attribute service.

We expect consideration of the representation of relationships among attributes and collections of attributes to factor in the definition of the representation layer.

Layer 2: Services

We propose to define Attribute Service interfaces to support interaction with attributes in one or more attribute repositories, and to support the integration of applications as attribute providers accessible within this service framework.

For the reference implementation, we will provide a Policy subsystem that is able to consume policies that are contingent on identity attributes acquired from the Attribute Service.

The reference implementation will also include one or more attribute providers that facilitate integration with existing identity repositories and protocols. The specific integrations included in the reference implementation will be decided by the Expert Group; while recognizing that the specification will define contracts to facilitate additional repository integrations by third parties. FaceBook, Twitter, and LinkedIn will be among the identity repositories considered for integration within the reference integration, as will their associated programming interfaces and protocols, including FaceBook Connect, OpenID Connect, and OAUTH 2.0.

We expect consideration of support for multi-tenancy to factor in the definition of the services layer.

Layer 3: Application development

We propose to define annotations that will cause the injection of Identity attributes and or references to identity attributes into applications. We also propose to define annotations that will cause application fields to be exported as attributes to the attribute service.

We also intend to describe the use of annotations to cause the insertion of attribute-based policy enforcement points within applications. Where feasible, we will reuse or extend extend existing standard annotations. We will also propose and advocate for improvements in the existing Java access control interfaces to facilitate more efficient enforcement of user-centric access control decisions.

2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

javax.security.identity

2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

no

2.10 Are there any security issues that cannot be addressed by the current security model?

The current security model does not describe or otherwise address the need for an identity governance model; i.e., a model or framework that is used to determine and control how identity information is used, stored and propagated between systems.

2.11 Are there any internationalization or localization issues?

This specification will rely on I18N support in Java SE

2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

no

2.13 Please describe the anticipated schedule for the development of this specification.

Expert Group formed: October 2011
Early Draft: March 2012
Public Review: July 2012
Final Release: January 2013

2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.

The primary means of communication will be email and conference calls. Face-to-face meetings will be scheduled if needed.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

  • The public can read the names of the people on the Expert Group.

    The members of the expert group will be listed on the JSR project page and in every draft of the specification.

  • The Expert Group business is regularly reported on a publicly readable alias.

    The Expert Group will conduct business on a publicly readable email alias. A private alias will be used only for EG-confidential information, as needed.

  • The schedule for the JSR is publicly available, it's current, and I update it regularly.

    The schedule will be available on the project page of the JSR and will be kept current.

  • The public can read/write to a wiki for my JSR.

    A public email list will be used for comments.

  • There is an issue-tracker for my JSR that the public can read.

    The issue-tracker will be accessible from the JSR project page.

  • I have spoken at conferences and events about my JSR recently.

    Not yet, but will do so

  • I am using open-source processes for the development of the RI and/or TCK.

    The RI will be hosted at java.net as an open source project.

  • The Community tab for my JSR has links to and information about all public communication mechanisms and sites for the development of my JSR.

    This will be the case.

2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

Oracle Corporation will deliver a standalone Reference Implementation (RI) and Technology Compatibility Kit (TCK).

2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).

Not applicable

2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

License for Final Final Release Specification

License for Technology Compatibility Kit

Apache License, version 2.0, at http://www.apache.org/licenses/LICENSE-2.0 will apply to the Reference Implementation.

2.19 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

The public should provide feedback via the public user email list, users@identity-api-spec.java.net, or via the public discussion board at: http://java.net/projects/identity-api-spec/forums/message-forum

We document nominations in our Expert Group teleconference minutes, which are made available to the public via the public user email list and archive. The archive is available at: http://java.net/projects/identity-api-spec/lists/users/archive

Expert Group communications are made available to the public via the EG communication archive.
Minutes of our Expert Group meetings are also made available via the project wiki: http://java.net/projects/identity-api-spec/pages/MeetingMinutes

2.20 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

http://java.net/jira/browse/IDENTITY_API_SPEC

2.21 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

http://java.net/projects/identity-api-spec/downloads





Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Project Aristotle, the ArisID API, and the Liberty Identity Governance Framework(IGF). Please see: http://www.openliberty.org/wiki/index.php/ProjectAris

The Open Az project. Please see: http://www.openliberty.org/wiki/index.php/OpenAz_Main_Page

ABAC Reference - A Report on the Privilege (Access) Management Workshop, NISTIR 7657, March 2010: http://csrc.nist.gov/publications/nistir/ir7657/nistir-7657.pdf

Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0. Please see: http://docs.oasis-open.org/security/saml/v2.0/saml-glossary-2.0-os.pdf

The Java Naming and Directory Interface (JNDI) Tutorial. Please see: http://download.oracle.com/javase/jndi/tutorial/

JSR 299: Contexts and Dependency Injection for the JavaTM EE platform. Please see: http://jcp.org/en/jsr/summary?id=299

3.2 Explanation of how these items might be used as a starting point for the work.

The ArisID and Open Az APIs will be reviewed for their approaches to representing identity attributes in Java. The interaction, attribute reference and Subject integration mechanisms of ArisID will be reviewed, as will its use of CARML as the means by which applications declare their use of identity attributes.

It is expected that the output of the JSR will be an API that accommodates a wide range of Java Object types within an identity attribute programming model that features the use of Java annotations and dependency injection.



Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.

The following use case descriptions were used to develop this proposal.

1. Application is Client of Attribute Service
At runtime, an application, e.g., a business application, interacts with an Attribute Service to perform operations on individual attributes or collections of attributes pertaining to one or more identified entities. In one scenario, the operations are performed on the attributes of the entity identified by the access control context of the thread on which the interaction with the Attribute Service is performed. In another scenario the operations are performed on the attributes of one or more entities independent of the entity associated with the thread. At compile time, target attributes are identified using logical constructs that are bound, at runtime, by the Attribute Service to physical attribute repositories and values. In some scenarios, only lookup or read type attribute operations will be performed. In other scenarios, update, create, and or delete operations will also be performed.

In user registration scenarios, an application will create entities that are integrated with an authentication system such that the authentication system can establish an access control context that identifies the entity. Some such applications will establish the governance policy for the attributes of the entities they create.

Example:
Part 1: Sally uses her browser to interact with a web application to renew her prescription at her health care provider. Before being afforded access to the application, Sally must provide proof of her identity to the authentication system used by her health care provider. Once Sally has been authenticated, the application will serve her request on a thread that identifies Sally as the application user. Within the application there are variables that are linked by attribute reference to the prescription that Sally may renew, Sally's preferred pharmacy, and her current primary care physician. During initialization of the application request, the corresponding attribute values are acquired (via the attribute service) from the corresponding subscriber and patient record repositories and assigned to the application variables. The application processes the request by creating a prescription renewal request for handling by Sally's physician. The request identifies Sally, her prescription, and her preferred pharmacy.
Part 2: Sally's physician is notified of the request pending approval, and interacts with an application to authorize the prescription. Sally's physician must provide proof of her identity to the authentication system used by the physician application. Once the physician has been authenticated, the physician application will process the request on a thread that identifies the physician as the user of the application. The physician application contains a variable that is linked by an attribute reference to the email address of the patient identified by the renewal request (i.e., Sally). The physician interacts with the application to renew Sally's prescription at the preferred pharmacy, which causes the completed prescription to be sent to the pharmacy, and a confirmation email to be sent to Sally.
2. Application is Attribute Provider

An application embodies attributes that are to be made available to other applications via the attribute service. These attributes are associated with specific scopes or contexts, such that client applications may be provided with attributes appropriate to the context in which the client is operating. In some scenarios, the attributes are provided from a common context independent of that of the client application. In other scenarios, the attributes are provided from a context associated with the client application, or from a request, session, or user authentication context shared between the attribute provider and the client application or system.

In one specific use case, an application is a client of an authorization system and the policy being enforced by the authorization system is based on contextual attribute values held within the application, The application cannot reliably predict the additional contextual application attributes that will be required by the authorization system. As such, the application (as attribute provider) must respond to requests, from the decision agent, for additional contextual attributes as needed by the authorization system.

Example (contextual attribute details):
The prescription renewal application propagates Sally's patient identifier, the prescription, and Sally's preferred pharmacy to the physician application. During initialization of a request to the physician application, a request-scoped attribute containing the patient identifier is exported from the physician application such that is available via the attribute service to applications or systems invoked by the physician application.
3. Identity Propagation


Application or system wishes to propagate Identity attributes to other system or application. In one common case, the attributes to be propagated will be those of the current authenticated entity. In other cases, the attributes to be propagated may pertain to an arbitrary entity. In some cases, specific attributes are to be propagated; while in others, it will be necessary to propagate an ability for the recipient to acquire additional attributes (of some entity) that the propagator may either be unfamiliar with or unauthorized to acquire. It will also be necessary to be able to pass attributes by reference, in order to force the recipient to interact with the attribute service to acquire the attribute values (which will ensure that it have rights to do so). In cases where the receiving system is outside the java identity framework (including the cases where it is a non-Java system), it will be necessary for the propagator to represent the attributes in a form that will be understood by the recipient.

Example (propagation details):
The prescription renewal application propagates Sally's patient identifier, the prescription, and Sally's preferred pharmacy to the physician application. In a variation, attribute references are propagated to the physician application which uses the references to acquire the values of the corresponding attributes based on the physician application and the physician being authorized by the attribute service to do so. In either case, the physician application uses the patient identifier to acquire the email address at which the patient is to receive confirmation of the physician's approval of the prescription.
4. Authentication System binds Attributes to Java Authentication State


A Java authentication system collects and validates security mechanism-specific tokens or credentials and establishes a corresponding representation of authentication state within the Java access control context of the thread for which the authentication was performed.

The credentials may be collected directly from the user of the runtime environment, or from messages conveyed to the runtime. The authentication system converts the validated credentials into authenticated identity attributes which are then established within the Java access control context. The access control context is established within the runtime environment for which the system is performing the authentication. The authentication system may use the authenticated identity attributes to acquire additional identity attributes pertaining to the authenticated entity. When additional attributes are acquired, they are acquired from an Attribute Service, and are represented in the established access control context. The Attribute Service must be able to locate any additional attributes requested by the authentication system based on the authenticated identity attributes. The Attribute Service must return any additional attributes in a form that can be established within the access control context and suitably conveyed within the runtime.

Example (authentication details):
Sally must provide proof of her identity to the authentication system used by her health care provider, and Sally's physician must provide proof of her identity to the authentication system used by the physician application. When such proof is provided, the respective authentication systems create a security credential which embodies the identity of the authenticated entity, the identity of the service performing the authentication, and other characteristics detailing the quality or properties of the authentication that was performed. The credential produced by the authentication system used by the patient will also include the service affiliation groups of the patient. The credential produced by the physician authentication system will also include the caregiver privilege groups to which the physician is a member. The credentials are represented in an interoperable network transfer syntax (e.g., ASN.1, XML, or JSON). The authentication agents within the application hosting platforms interpret the content of the respective security credentials and create corresponding Java identity attributes that are added to the authentication state that represents the application user to the respective application. The identity of the authentication service and other qualitative properties contained within the credential from which the attributes were derived are captured as meta-data within the user and group attributes derived from the credential.
5. Authorization Subsystem Consumes Attributes


The Authorization Subsystem is presumed to be composed of one or more decision agents each exporting a decision interface for use by policy enforcement points embedded in the application or middleware. The decision agents make calls to an underlying Policy engine. Each decision agent is responsible for converting the artifacts passed to it, via its associated decision interface, to the artifacts required by the Policy engine. The decision agents are presumed to be co-located with an Attribute Service and with the enforcement points that rely on them.

An application or runtime/IDE uses decision interface to embed enforcement point(s). Target resource, action, and actor to be tested for authorization are established at the enforcement point and passed to the decision agent via the decision interface. In one scenario, the target resource and action are derived from the Java language coordinates of the enforcement point (i.e., the method or class on which the enforcement point is embedded). In another scenario, including instance specific access control, the target resource and action are established using decision interface specific objects (e.g., AzAPI Resource attributes, or Java Permission objects) that are orthogonal to the language coordinates. In active entity scenarios, the enforcement point may test the actor who is currently executing the code at the enforcement point (as represented by the access control context). In target entity scenarios, the enforcement point may test some other proposed or predicted actor (e.g., as represented in an unbound access control context). In either case, the actor is commonly expected to correspond to some potential user of the system, but may also include information identifying the code from which an invocation or potential invocation originated.

The Policy engine may use the identity attributes of the actor to request additional attributes from the attribute service. The Policy engine may interact with the application to obtain any additional contextual attributes determined to be required to complete the processing of the access control decision. For the case where the Policy engine is remote with respect to the decision agent (and thus the enforcement point and the corresponding Attribute Service) the Policy engine may direct its requests for additional attributes to the decision agent; which would then interact with the Attribute service or application, as appropriate. In all cases, it is the Policy engine that is responsible for determining, based on the rules that it is processing, when an additional attribute should be acquired, and whether to interact with the Attribute Service, the application, or the decision agent to acquire it.

Example (authorization decision details):

The physician application exports a request-scoped attribute containing the patient identifier such that it is available via the attribute service to applications or systems invoked by the physician application. The physician application makes an embedded call to the authorization system to determine if the physician (using the application) is authorized to prescribe the medication. The request to the authorization system identifies the prescription to be authorized and the physician. During its processing of the authorization request, the authorization system determines that the medication being prescribed can only be authorized by a physician who is listed as a primary care provider to the patient. To determine if this is the case, the authorization system uses the attribute service to obtain the patient identifier from the application, and to acquire the attribute identifying the patient's primary care provider which it then compares to the physician's identifier. If the physician is authorized to prescribe the medication, the physician application submits the prescription to Sally's pharmacy for processing.