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
...
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:
...
- @@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.) |
| Scalar value, array, or object, potentially with embedded 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 value. |
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims-requested": [
{"type": "{http://www.example.com/ABC"},
{"http://www.example.com/claimsformats/ABC":
{"param": 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. |
}
For example:
| Code Block |
|---|
{
"http://c2.io/claims": [
{"type": "{http://www.example.com/ABC"},
{"http://www.example.com/claimsformats/ABC":
{"param": 18},
{"param2": "foo"}
}
]
}
|
...