$Id: oauth-attributequery.txt 135 2009-09-18 10:41:48Z andreas $
1 Introduction and Terminology
This protocols allows one entity to query attributes related to the current user from another entity using a simple back-channel HTTP GET request. The attribute query makes use of the OAuth protocol to establish a session between the two entities.
The entity requesting attributes plays the role as an OAuth Consumer, while the responding entity is the OAuth Provider.
1.1 Requirements notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
2 Establishing the Session with OAuth
The initial establishment of the session follows the usual OAuth flow.
- Requester requests a Request token from the Responder
- Requester sends the user to the Responder to authorize the Request Token
- User authenticates to the Responder, and possibly is asked for consent about releasing attributes to the specific Requester.
- User returns to the Requester, and the Requester request to exchange the Request Token for an Access Token.
- Requester uses Access Token to extract data from the Responder, using the data access endpoint.
After the initial OAuth establishment, retrieving data, is done by signing a HTTP GET request to the data access endpoint using the Access Token, and the Responder will return the resulting data encoded with JSON, or another encoding depending on the format requested.
3 The Attribute Query Request
The request for attributes is sent to the data access endpoint, with an OAuth signature.
These query parameters are all optional:
target: If the target is not the current user, the requester may query attributes related to another target. The value MUST be a URI, and it is out of scope of this specification to define the semanitcs of different targets.format: What output format is wanted for the response? This parameter may have one of these values:json: The attributes will be returned as a JSON array. This is the default value.saml: The attributes will be returned contained in a SAML version 2.0<saml:AuthenticationStatement>.
attributes: A comma separated list of attribute names that the requester would like in response.openid: If the user is authenticated using OpenID at the requester, and it is reasonable that the responder also would like to authenticate the user using OpenID, the OpenID of the user may be sent as a hint - such that the responder do not need to ask the user for his OpenID.samlentityid: If the user is authenticated using SAML at the requester, and it is reasonable that the responder also would like to authenticate the user using SAML, the requester may send the SAML entityID used to authenticate the user as a hint. This may allow the responder to skip the Discovery Service when authenticating the user, which in turn may improve the user experience.
Here is an example of an request (without any of the optional parameters):
GET /attributeauthority?
oauth_version=1.0& \
oauth_nonce=8eae4197dca8ef9dc6ab21fdbeebda5d& \
oauth_timestamp=1247566660& \
oauth_consumer_key=key& \
oauth_token=accesskey& \
oauth_signature_method=HMAC-SHA1& \
oauth_signature=2087LYaGOaos89CYPbzifsUm8rs%3D HTTP/1.0
4 The Information Model of Attributes
Attributes are a set of key -> value pair, where the value is an ordered list of one or more values. The key MUST be a string.
5 The Response
If the request was successfully processed, an HTTP return code 200 is returned, and the body contains the attributes encoded in one of the following encodings
5.1 JSON
Here is an example of a response encoded using the JSON format:
HTTP/1.x 200 OK
Date: Tue, 14 Jul 2009 10:19:51 GMT
Content-Type: application/json
[
"mail": "andreas@uninett.no",
"entitlement": ["urn:shouldHaveAccess", "urn:moreAccess"],
]
Single-valued attributes, may be represented either as a string or an array with one element which is a string. Both methods are equivalent, and represent the same information.
5.2 SAML 2.0 Attribute Statement
Here is an example of a response encoded using the saml format:
HTTP/1.x 200 OK
Date: Tue, 14 Jul 2009 10:19:51 GMT
Content-Type: application/xml
<saml:AttributeStatement
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="mail">
<saml:AttributeValue xsi:type="xs:string">andreas@uninett.no</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="entitlement">
<saml:AttributeValue xsi:type="xs:string">urn:shouldHaveAccess</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">urn:moreAccess</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
6 Error Response
Return an HTTP return code with 5xx, and print out the error message in plain text in the response.