Abstract
This document defines a lightweight, generic, and powerful JSON-based format for expressing claims and requests for claims. The primary driver for Claims 2.0 is the process of negotiation for access authorization defined by the User-Managed Access (UMA) core protocol, but this document is defined as a modular building block that can be used by other protocols as well.
Status
This document is a product of the User-Managed Access Work Group. It is currently under active development. Its latest version can always be found here. See the Change History at the end of this document for its revision number.
Editors
- Eve Maler
- Paul C. Bryan
Intellectual Property Notice
...
Table of Contents
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
...
Introduction
This document defines a lightweight, generic, and powerful JSON-based format ([JSON]) for expressing claims and requests for claims, that is, statements in the sense of [IDCclaim]. The primary driver for Claims 2.0 is the process of negotiation for access authorization defined by Step 2 of the User-Managed Access (UMA) core protocol, in which an authorization manager can demand that require a requester to convey claims on behalf of a requesting party, in order to satisfy the polices of an authorizing user. However, this This document is defined as a modular building block that can is intended to be used by other protocols as well.
Following The following are design goals of this specification:
- Allows for efficient, convenient, and consistent processing, marshalling, and unmarshalling
- Lightweight way to express both self-asserted claims and third-party-signed claims
- Allows for variability in the characteristics of claims being requested
Following are non-not goals of this specification:
...
signed claim: A claim object that contains a signature member attribute and associated related data.
Conventions
Following are conventions used in this specification for documenting constraints on claims-related JSON objects:
- @@Do we need a proper BNF, or will this do?
- Order: Members of objects must appear in the order shown.
- Type: Italic text stands for a scalar value, array, or object of the indicated type. @@This one can't currently be used in actual Requested Claims object, unless we import JSON-schema or something. Do we want to go that far?
- Options:
"(type|type)"represents a literal string with a series of two or more exclusive options of the shown type. When a literal parenthesis mark or vertical bar must appear in such a string, use @@what? instead. - Wildcards:
"*"or"string*string"represents a literal string that can have any non-null value at the point indicated by the asterisk. When a literal asterisk must appear in such a string, use @@what? instead. @@Slippery slope question: the claims-requested example below shows why it would be valuable to allow zero-or-more in addition to one-or-more. What to do?
...
When these documents are exchanged by means of HTTP, their content type MUST be application/json. (@@Should this allow for application/json+something?)
Additional requirements on the definition of specific claim formats and higher-level claims exchange protocols appear below.
...
Name | Value | Value Description |
|---|---|---|
| Array of one or more Requested Claim objects | A set of requested claims. |
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims-requested": [
{...},
{...}
]
}
|
Each array element is a Requested Claim object that represents a template for a corresponding claim being sought, where the template MAY use any or all of the order, type, option, and wildcard conventions defined by this specification to indicate constraints on the corresponding claim, along with any other conventions.
...
claims Document
{
Name | Value | Description |
|---|---|---|
| Array of one or more Claim objects | A set of claims. |
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims": [
{...},
{...}
]
}
|
Each array element is a Claim object that represents a claim being delivered on request.
...
Name | Value | Description |
|---|---|---|
| | The identifying URL of the claim format being requested. |
| | Constraint on the value of the issuer of a supplied claim. If absent, it is acceptable for the corresponding claim to supply no issuer. (The presence of an issuer value in a supplied claim has additional implications, as noted below.) |
| Object containing attributes that are specific to the claim type | The literal values of the attributes MAY use the option and/or wildcard conventions The value MUST conform to the claims-requested format identified by this URL. If absent, the requested claim MUST have a non-null string valueto indicate desired constraints on the claim. |
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims-requested": [
{
"type": "{http://www.example.com/ABC"},
{"http://www.example.com/claimsformats/ABC "value": {
{ "param": 18
}
}
]
}
|
This example requests a claim conforming to the http://www.example.com/claimsformats/ABC format, whose value is an object that must contain at least a member called an attribute named param that has a number value of 18.
...
Name | Value | Description | |||
|---|---|---|---|---|---|
| | The identifying URL of the format of the claim being supplied. @@Is this object member even necessary? If another member with a name of claimURL is supplied, isn't that sufficient? Or is there benefit in having this be the very first member, even before other stuff that might get more complicated? | |||
| | The issuer of the claim. The issuer URL can be used by the recipient of the claim to retrieve the public key of the signer of a signed claim. The issuer MUST be present if a signature is present. | |||
| Scalar value, array, or object | The value MUST conform to the claims format identified by this URL. |
| Signature object | A signature over the entire Claim object (see the Signed Claims section, below). The signature MUST be present if an issuer is present. |
| Object containing attributes that are specific to the claim type |
|
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims": [
{
"type": "{http://www.example.com/ABC"},
{"http://www.example.com/claimsformats/ABC"value": {
{ "param": 18},
{"param2": "foo"
}
}
]
}
|
This example represents a claim supplied in response to the previous example, with a param member attribute that conforms to the template and an additional member attribute param2.
...
Signed Claims
Any Claim object can contain a signature memberattribute. The signer of the claim represents the issuer of the claim about the subject of the claim. A claim with a signature member attribute MUST also have an issuer memberattribute, and vice versa.
The Signature object is as defined in [CouchSign]. @@Need to fully define, and extend, in this spec.
A claim recipient that wishes to verify the signature of a signed claim MAY use the issuer value to construct and dereference a well-known location for the signer's "host-meta" metadata (as defined in [hostmeta]) and then obtain the signer's public key from this location by retrieving the href value an XRD <Link> element with a rel attribute whose value is http://c2.io/public-key.
For example, if the signer value is "https://signer.example.com", the claim recipient can construst construct the well-known metadata location "https://signer.example.com/.well-known/host-meta" , and perform an HTTP GET on that location to retrieve the XRD resource and obtain the signer's public key from this location.@@TBS: Define the XRD format for the key material here? Borrow some ideas from Magic Signature?
...
References
Normative References
...