Identity Delegation

Definitions
Scope
Steps
Notes

The purpose of this specification is to define a method by which one App.net app is able to verifiably prove to another application that it has access to a specific user’s account without sharing any secret credentials.

Definitions

Unless otherwise defined here, terms should have the same approximate usage as the OAuth 2.0 draft specification.

delegate client: The client to which the identity delegation is made (e.g., a photo hosting service)
authorized client: The client wishing to make a request to the delegate client (e.g., an App.net mobile client application)

Scope

Intentionally not addressed in this document are the following:

Authorization of delegate client to make requests to the request server on behalf of the resource owner
Discovery of delegate client client_id
Discovery of user identity endpoints
Format of user identity endpoint

Steps

The authorized client completes an OAuth authorization flow and obtains an access token from the resource server. This is outside the scope of this document.
The authorized client makes an authenticated POST request to the resource server OAuth token endpoint:
```
 POST /oauth/access_token HTTP/1.1
 Host: account.app.net
 Authorization: Bearer [access_token]
 Content-Length: 59
 Content-Type: application/x-www-form-urlencoded

 grant_type=delegate&delegate_client_id=[delegate client_id]
```
which returns in the body of the reply:
```
 {"delegate_token": "[delegate token]"}
```
For App.net, the OAuth token endpoint is: https://account.app.net/oauth/access_token

Example:

to see more complete examples.
```
curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=delegate" -d "delegate_client_id=[your client_id]" \
 "https://account.app.net/oauth/access_token"
```
The authorized client makes a request to the delegate client with two additional headers, Identity-Delegate-Token and Identity-Delegate-Endpoint:
```
 POST /protected/resource HTTP/1.1
 Host: delegate-client.example.com
 Identity-Delegate-Token: [delegate_token]
 Identity-Delegate-Endpoint: https://alpha-api.app.net/stream/0/token
 Content-Length: 100
 Content-Type: application/x-www-form-urlencoded

 do_some_stuff=1&fo_reals=1
```
The Authorization header is purposefully not used, as another mechanism may be in place for authentication.

The delegate token and delegate endpoint may also be sent as delegate_token and delegate_endpoint in the query string or POST body.

Example:

to see more complete examples.
```
curl -X POST -H "Identity-Delegate-Token: [delegate_token from previous step]" \
 -H "Identity-Delegate-Endpoint: https://alpha-api.app.net/stream/0/token" \
 -H "Content-Type: application/x-www-form-urlencoded" -d "do_some_stuff=1" \
 -d "fo_reals=1" "https://delegate-client.example.com/protected/resource"
```
The delegate client identifies the resource server (App.net) by using the Identity-Delegate-Endpoint header and makes a request to that endpoint with the Authorization header set.

The query string parameters delegate_token, client_id and client_secret may be used in place of HTTP headers if desired.
```
 GET /stream/0/token HTTP/1.1
 Host: alpha-api.app.net
 Authorization: Basic [base64(client_id + ":" + client_secret)]
 Identity-Delegate-Token: [delegate_token]
```
which returns in the body of the reply:
```
 {
     "data": {
         "app": {
             "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
             "link": "http://foo.example.com",
             "name": "Bryan's app for testing"
         },
         "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
         "scopes": [
             "follow",
             "write_post",
             "stream"
         ],
         "user": {
             "created_at": "2012-07-30T18:57:05Z",
             "id": "16",
             "locale": "en_US",
             "name": "Bryan Berg",
             "timezone": "America/Los_Angeles",
             "type": "human",
             "username": "bryan"
             [... truncated for the sake of brevity ...],
         },
     },
     "meta": {
         "code": 200
     }
 }
```
App.net replies with information about the authorized delegate token. This is the Token object of the authorizing client’s access_token as returned by the Retrieve current Token endpoint.

The delegate client may verify that the authorized client matches some external authentication scheme and/or list of authorized applications. If the delegate token is not valid for the delegate client’s client_id, this call will return a 401 Unauthorized.

For App.net, the identity delegation endpoint is: https://alpha-api.app.net/stream/0/token

Example:

to see more complete examples.
```
curl -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "Identity-Delegate-Token: [delegate_token]" \
 "https://alpha-api.app.net/stream/0/token"
```

Notes

delegate_tokens are valid as long as their associated access_tokens are valid.
The delegate client may cache the return value of the identity delegate endpoint for a short period of time.
Feedback on this draft is welcomed. Please open an issue on the api-spec GitHub repo. Private or security-sensitive commentary can be sent to bryan@app.net.