App Authentication

Alpha Documentation

These docs are very rough, incorrect, and incomplete. They will be modified heavily over the next few weeks.

Please contribute by making Pull Requests and Issues on the GitHub repository.

Tent uses OAuth 2 for app authentication. Because of the distributed nature of Tent, it is necessary for apps to register with the Tent entity before doing the authentication flow.

After the authentication flow, requests are authenticated using the credentials with MAC Access Authentication.

App Registration

Before authenticating a user, the application must be registered with the specified Tent entity. The first step is to perform discovery on the provided entity url.

HEAD / HTTP/1.1
Accept: application/vnd.tent.v0+json

HTTP/1.1 200 OK
Content-Type: text/html
Link: </profile>; rel="https://tent.io/rels/profile"

The next step is to register the application with the server. Registration specifies some details about the app, as well as the exact redirect_uris that will be used during the OAuth flow. The response id, secret, and mac_algorithm are used to authenticate future requests to the Tent server. The id is used as the client_id in all OAuth requests.

POST /apps HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json

{
  "name": "FooApp",
  "description": "Does amazing foos with your data",
  "url": "http://example.com",
  "icon": "http://example.com/icon.png",
  "redirect_uris": [
    "https://app.example.com/tent/callback"
  ],
  "scopes": {
    "write_profile": "Uses an app profile section to describe foos",
    "read_followings": "Calculates foos based on your followings"
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Content-Length: 459

{
  "name": "FooApp",
  "description": "Does amazing foos with your data",
  "url": "http://example.com",
  "icon": "http://example.com/icon.png",
  "redirect_uris": [
    "https://app.example.com/tent/callback"
  ],
  "scopes": {
    "write_profile": "Uses an app profile section to describe foos",
    "read_followings": "Calculates foos based on your followings"
  },
  "id": "p0cq4m",
  "mac_key_id": "a:f665629b",
  "mac_key": "6cda8195d50bb55fb17d22de3f7575de",
  "mac_algorithm": "hmac-sha-256",
  "authorizations": [

  ]
}

App JSON Schema

Property	Required	Type	Description
`id`	Optional	String	The unique identifier of the app.
`name`	Required	String	The short display name for the app.
`description`	Required	String	The short display description of the app.
`url`	Required	String	The URL for the home page of the app.
`icon`	Optional	String	The URL to the icon for the app.
`redirect_uris`	Required	Array	The exact (including parameters) uris that will be used as OAuth `redirect_uri`.
`scopes`	Required	Object	All of the scopes that the application will use, and the reason why each is required.
`mac_algorithm`	Optional	String	The MAC algorithm to use when authenticating the app.
`mac_key_id`	Optional	String	The MAC key identifier to use when authenticating the app.
`mac_key`	Optional	String	The MAC key to use when authenticating the app.

Authentication Flow

Auth Request

The app requests the user's Tent identifier, and performs discovery on it to find the Tent API root. The app then builds an auth request and redirects the user-agent to it:

/oauth/authorize?client_id=p0cq4m
  &redirect_uri=http://app.example.com/tent/callback
  &scope=read_posts,read_profile
  &state=87351cc2f6737bfc8ba
  &tent_profile_info_types=https://tent.io/types/info/music/v0.1.0
  &tent_post_types=https://tent.io/types/posts/status/v0.1.0,https://tent.io/types/posts/photo/v0.1.0

Parameters

Name	Required	Description
`client_id`	Required	The `id` obtained by registering with the Tent server
`redirect_uri`	Required	The URI to redirect to after authentication is complete. It must exactly match a URI (including parameters) provided during app registration in `redirect_uris`.
`state`	Optional	This parameter will be added to the `redirect_uri` and should always be set to a random string that is stored in the session, and then verified to prevent cross-site request forgery attacks.
`scope`	Optional	A comma-separated list of scopes that the app is requesting access to.
`tent_profile_info_types`	Optional	A comma-separated list of profile info type urls that the app is requesting access to. Set to `all` to request full access to the profile.
`tent_post_types`	Optional	A comma-separated list of type urls that the app is requesting access to. Set to `all` to request access to all posts.
`tent_notification_url`	Optional	The URI to send post notifications to.

Scopes

Scope	Description
`read_profile`	Read profile sections listed in the `profile_info` parameter
`write_profile`	Read and write profile sections listed in the `profile_info` parameter
`read_followers`	Read follower list
`write_followers`	Read follower list and block followers
`read_followings`	Read followings list
`write_followings`	Read followings list and follow new entities
`read_posts`	Read posts with types listed in the `post_types` parameter
`write_posts`	Read and publish posts with types listed in the `post_types` parameter

Redirect

After the user has authorized the application, the Tent server will redirect the User-Agent back to the specified redirect_uri with a code that can be used to retrieve authentication details from the server.

The state parameter should be matched against the state parameter sent in the initial request to prevent request forgery.

HTTP/1.1 302 Found
Location: http://app.example.com/tent/callback?code=9a27c37c0adb08351b1e7aac4ec12dc6&state=87351cc2f6737bfc8ba

Access Token

The code must be traded for permanent authentication details that can be used to access the Tent server on behalf of the user.

POST /apps/:id/authorizations

The request must be signed with a MAC using the secret obtained during app registration. Currently only the mac token_type is supported.

POST /apps/p0cq4m/authorizations HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json
Authorization: MAC id="a:f665629b", ts="1346984266", nonce="1f400b", mac="9kvPu8d7eM0kT/19XjHC39FiOWJZyYHAqbD5cTjAAkc="

{
  "code": "9a27c37c0adb08351b1e7aac4ec12dc6",
  "token_type": "mac"
}

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Content-Length: 124

{
  "access_token": "u:083dc7a9",
  "mac_key": "b67e42ad66e10538785d6d1bca024a17",
  "mac_algorithm": "hmac-sha-256",
  "token_type": "mac"
}

Response Parameters

Name	Description
`access_token`	Used as the MAC key identifier.
`mac_key`	Used as the MAC key for requests.
`mac_algorithm`	The MAC algorithm to be used.
`token_type`	Specifies the token type. Currently always `mac`

Request Authentication

Tent uses HTTP MAC Access Authentication to authenticate app requests. Requests to modify the app's registration details must be authorized using the provided id and secret as the MAC key identifier and MAC key respectively.

Requests to the Tent server on behalf of an authenticated user must be authorized using the credentials retrieved at the end of the auth flow. The access_token and mac_key are the MAC key identifier and MAC key respectively.

App Registration Modification

The request must be authenticated with a MAC generated using the secret from the initial registration.

GET /apps/:id

GET /apps/p0cq4m HTTP/1.1
Accept: application/vnd.tent.v0+json
Authorization: MAC id="a:f665629b", ts="1346984266", nonce="173d55", mac="lXyfBqkxNmZZ83f5brd1dlgm6V0ZQjkSCSwjnR5U6Fo="

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Last-Modified: Fri, 07 Sep 2012 02:17:46 GMT
Content-Length: 853

{
  "name": "FooApp",
  "description": "Does amazing foos with your data",
  "url": "http://example.com",
  "icon": "http://example.com/icon.png",
  "redirect_uris": [
    "https://app.example.com/tent/callback"
  ],
  "scopes": {
    "write_profile": "Uses an app profile section to describe foos",
    "read_followings": "Calculates foos based on your followings"
  },
  "id": "p0cq4m",
  "authorizations": [
    {
      "post_types": [
        "https://tent.io/types/post/status/v0.1.0",
        "https://tent.io/types/post/photo/v0.1.0"
      ],
      "profile_info_types": [
        "https://tent.io/types/info/basic/v0.1.0"
      ],
      "scopes": [
        "read_posts",
        "write_posts",
        "import_posts",
        "read_profile",
        "write_profile",
        "read_followers",
        "write_followers",
        "read_followings",
        "write_followings",
        "read_groups",
        "write_groups",
        "read_permissions",
        "write_permissions",
        "read_apps",
        "write_apps",
        "follow_ui",
        "read_secrets",
        "write_secrets"
      ],
      "notification_url": null,
      "id": "ha4g6i"
    }
  ]
}

PUT /apps/:id

PUT /apps/p0cq4m HTTP/1.1
Content-Type: application/vnd.tent.v0+json
Accept: application/vnd.tent.v0+json
Authorization: MAC id="a:f665629b", ts="1346984266", nonce="722389", mac="X0okwuXuknoB+FjbVS02LzIvL4dmYDHlnkSjwmmpBMg="

{
  "name": "FooApp",
  "description": "Does amazing foos with your data",
  "url": "http://example.com",
  "icon": "http://example.com/icon.png",
  "redirect_uris": [
    "https://app.example.com/tent/callback"
  ],
  "scopes": {
    "write_profile": "Uses an app profile section to describe foos",
    "read_followings": "Calculates foos based on your followings",
    "write_following": "Follow new users when you click"
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.tent.v0+json
Content-Length: 905

{
  "name": "FooApp",
  "description": "Does amazing foos with your data",
  "url": "http://example.com",
  "icon": "http://example.com/icon.png",
  "redirect_uris": [
    "https://app.example.com/tent/callback"
  ],
  "scopes": {
    "write_profile": "Uses an app profile section to describe foos",
    "read_followings": "Calculates foos based on your followings",
    "write_following": "Follow new users when you click"
  },
  "id": "p0cq4m",
  "authorizations": [
    {
      "post_types": [
        "https://tent.io/types/post/status/v0.1.0",
        "https://tent.io/types/post/photo/v0.1.0"
      ],
      "profile_info_types": [
        "https://tent.io/types/info/basic/v0.1.0"
      ],
      "scopes": [
        "read_posts",
        "write_posts",
        "import_posts",
        "read_profile",
        "write_profile",
        "read_followers",
        "write_followers",
        "read_followings",
        "write_followings",
        "read_groups",
        "write_groups",
        "read_permissions",
        "write_permissions",
        "read_apps",
        "write_apps",
        "follow_ui",
        "read_secrets",
        "write_secrets"
      ],
      "notification_url": null,
      "id": "ha4g6i"
    }
  ]
}