...

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

...

• Complete replacement or equivalent for other claims and signature formats, such as SAML, IMI, or XML Signature
• Protocol for carrying or securing claims and requests for claims for any particular purpose

Terminology

claim: A statement in the sense of [IDCclaim].

claims document: A top-level JSON object containing one or more claims.

claims-requested document: A top-level JSON object containing a request for one or more claims, conforming to this specification. (Claims can be requested in ways that do not involve a claims-requested document.)

signed claim: A claim object that contains a signature member and associated 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 are shown must appear in the required order shown.
• Type: Italic text stands for a value with 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: "(xtype|ytype)" represents a literal string with a series of two or more exclusive alternatives options of the shown types: as shown here, x or ytype. 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?

...

Definition of Claims-Using Protocols and Specific Claim Formats

It is anticipated that any number of specific claim formats will be defined separately from this specification. A definer of a specific claim format MUST document the syntax (including a URL identifying the claim format) and semantics of both the form in which claims must be supplied and any corresponding form in which claims must be requested.

A higher-level protocol using this specification for claims exchange MUST define document where claims -requested and claims documents appear in the protocol. Without further specification in a higher-level protocol, which of its entities request and provide claims, and to what purposea requester of a claim is the sole judge of whether a claim supplied in response is acceptable for the purpose to which the requester intends to put it.

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

...

The top-level object for requesting claims is exchange protocols appear below.

...

Claims-Related Documents

This specification defines a partial protocol made up of a JSON object that represents a request for claims, known as a claims-requested document, and a JSON object that represents claims, known as a claims document. It is OPTIONAL for a higher-level protocol to use an explicit claims-requested document, rather than an implicit, statically defined, or explicit but alternate-format request for claims.

This specification does not dictate how to interpret the subject of a claim; it is dependent on the particulars of the higher-level protocol in which claims are being exchanged. In some cases, the subject may be context-dependent, for example, it may be the claim supplier or an entity in a defined relationship with the claim supplier. @@Is this sufficient to support our needs at the UMA level?

claims-requested Document

{

}

claims Document

The top-level object for supplying claims is known as a claims document.For example:

{
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.

@@Need to express claims that are alternatives for each other? optional vs. required claims?

claims Document

{

}

For example:

{
claims: [
    {...},
    {...}
  ]
}

Each array element is a Claim object that represents a claim being delivered on request.

...

Requested Claim Object

{

}

Claim Object

}

For example:

{
claims-requested: [
    {"type": "{http://www.example.com/ABC"},
    {"http://www.example.com/claimsformats/ABC":
      {"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 param that has a number value of 18.

...

Claim Object

A supplier of a claim MUST construct it to conform to the following format, the constraints of the named claim type, and any constraints dictated by the claims-requested document that it is responding to.

{

}

Conformance

@@Say something about claims definition and syntactic validity.

}

For example:

{
claims: [
    {"type": "{http://www.example.com/ABC"},
    {"http://www.example.com/claimsformats/ABC":
      {"param": 18},
      {"param2": "foo"}
    }
  ]
}

This example represents a claim supplied in response to the previous example, with a param member that conforms to the template and an additional member param2.

...

Signed Claims

Any Claim object can contain a signature member. The signer of the claim represents the issuer of the claim about the subject of the claim. A claim with a signature member MUST also have an issuer member, 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]). For example, if the signer value is "https://signer.example.com", the claim recipient can construst the well-known metadata location "https://signer.example.com/.well-known/host-meta", 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

Non-Normative References

...