Authentication

Description of MetaWEB authentication mechanism.

Overview

MetaWeb concept is specifying mechanism to easily authenticate with server.

It also specifies central identity concept.

Central identity concept may be described in separate chapter.

Authentication

Authentication flow:

  1. Client tries to access protected resource.
  2. Server must respond to resource request with HTTP 401 status code with meta-data as response body.
  3. Client choses auth method:
    1. If navigate then client must navigate to specified URI
    2. If identity then client sends auth request to identity server and then calls specified resource server URI with access token and identity server URL - see Central identity concept. This process should be processed in background without renavigating.
  4. If client authenticates then resource server must respond with successfull action response with token property.
  5. Client now tries to access protected resource with token set as X-Meta-Token request HTTP header.

protected.meta

HTTP/1.1 401 Unauthorized
Content-type: application/x.meta+json
...
{
    "@doctype": "meta/protected",
    "providers": [
        {
            "type": "navigate",
            "label": "Log in via Facebook",
            "uri": "https://www.facebook.com/dialog/oauth?client_id=xxx&redirect_uri=https%3A%2F%2Fmymetaserver%2Flogin.meta"
        },
        {
            "type": "identity",
            "scope": [ "contact", "email", "avatar" ],
            "uri": "http://mymetaserver.com/auth"
        }
    ]
}

401 Unauthorized response

Response body is JSON encoded MetaWeb document with follwing properties.

Property Type * Description
@doctype String Yes meta/protected
providers Array of Object Yes List of available auth providers

Provider properties

Property Type * Description
type String Yes Provider type, one of: navigate, identity (central identity concept)
label String Yes if navigate provider Provider label, eg.: Facebook, Google, Twitter, Internal
uri String / URI Yes URI to MetaWeb document where client can authenticate
scope Array of String Yes if identity provider Required data from identity server

Request auth.php

{
    "@doctype": "meta/response/auth",
    "token": "abc123",
    "path": "/myweb/",
    "expires": "2016-12-01T15:15:00.111Z"
}

Authentication response

When client tries to authenticate then server must respond with MetaWeb action response.

If unsucessfull then standard error response is sent.

When successfull then server must provider token property in response and meta/response/auth doctype.

Successfull response properties:

Property Type * Description
@doctype String Yes meta/response/auth
token String Yes Authorization token which will be used to request protected resources
path String No Auth token is applicable only on specified path
expires String No ISO-8601 formated date and time when token expires

Client remembers this token for session and uses it to request protected resources.

protected.meta

GET /protected.meta
X-Meta-Token: abc123
...


HTTP/1.1 200 OK
...
{
    "@doctype": "meta/resource",
    ...
}

Protected resource request

Then when client tries to access protected resource it sends token as X-Meta-Token HTTP header.

Central identity concept

Central identity concept is based on an idea to have identity server where users have their accounts.

3rd party applications can then access identity information and use these services as log in mechanisms.

Difference between OpenID and other services is that central identity server DOES NOT require application to be known and authorized. It's because following workflow.

When resource server requires authentication:

  1. Server says that is supports MetaWeb identity mechanism
  2. Client contacts identity server and request auth token for resource server
  3. Client then passes auth token and identity server URL to resource server
  4. Resource server requests identity information from identity server using that token
  5. Resource server internaly authenticates client and returns session token as described above

Identity server API

User registration and log in mechanisms to identity server are up to that server. But when successfully logged in then server MUST respond with proper action response so client can easily recognize properties required for future requests.

https://identity.server/auth

{
    "@doctype": "meta/response/auth/identity",
    "token": "abc123",
    "request_uri": "https://identity.server/service_request",
    "profile_uri": "https://identity.server/profile"
}

Identity server successfull login response

Response MUST be in MetaWeb meta/response/auth/identity format, extends meta/response/auth.

Property Type * Description
@doctype String Yes meta/response/auth/identity
token String Yes Authorization token which will be used to request identity server
path String No Auth token is applicable only on specified path
expires String No ISO-8601 formated date and time when token expires
request_uri String Yes URI where client can request authorzation for resource server
profile_uri String Yes URI where client can find his profile

https://identity.server/service_request

POST /service_request
X-Meta-Token: abc123
...
{
    "resource": "https://resource.server/protected.meta",
    "scope": [ "contact", "email" ]
}

Response

{
    "@doctype": "meta/response/identity/token",
    "token": "xyz456",
    "expires": "2016-12-01T15:15:00.111Z",
    "auth_uri": "https://identity.server/service_auth"
}

Request resource server authorization

When resource server requires identity authentication then client sends following request to identity server which returns token for that resource server using POST method.

Request is JSON encoded and MUST has following properties.

Property Type * Description
resource String Yes URI of protected resource
scope Array of String Yes Array of required information scope

Client needs to be authenticated to identity server to send this request. So request must be send with X-Meta-Token HTTP header.

Identity server then responds with meta/response/identity/token type with following properties.

Property Type * Description
@doctype String Yes meta/response/identity/token
token String Yes Authorization token which will be passed to resource server
expires String No ISO-8601 formated date and time when token expires
auth_uri String / URL Yes URL where resource server can request identity information

https://resource.server/auth

POST /auth
...
{
    "token": "xyz456",
    "expires": "2016-12-01T15:15:00.111Z",
    "auth_uri": "https://identity.server/service_auth"
}

Passing token to resource server

Then client sends access token with identity server URI to resource server using POST method.

Request is sent to URI specified in resource server unauthorized response.

Property Type * Description
token String Yes Authorization token which will be passed to resource server
expires String No ISO-8601 formated date and time when token expires
auth_uri String / URL Yes URL where resource server can request identity information

https://identity.server/service_auth

POST /auth
...
{
    "resource": "https://resource.server/protected.meta",
    "token": "xyz456"
}

Response

{
    "@doctype": "meta/response/identity/profile",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@doe.tld"
}

Resource server identity request

Resource server then can request identity data from identity server.

Request is send to specified auth_uri using POST method with following properties.

Property Type * Description
resource String Yes Protected resource URI
token String Yes Authorization token optained from client

Identity server should check if resource URI match with client request.

When successfull then identity server responds with meta/response/identity/profile type which has following properties and extends meta/identity/profile type.

Property Type * Description
@doctype String Yes meta/response/identity/profile
<profile> - Yes Profile data as meta/identity/profile type

Then resource server authenticates client internaly and sends him access token as described above.

Identity profile

@doctype: meta/identity/profile

TO-DO

OAuth 2.0 example

MetaWeb naturaly supports OAuth 2.0 auth with following workflow:

1) Server responds with 401 HTTP code and meta-data and specifies OAuth server auth URL.

GET /protected.meta
...
---

HTTP/1.1 401 Unauthorized
Content-type: application/x.meta+json

{
    "@doctype": "meta/protected",
    "providers": [
        {
            "type": "navigate",
            "label": "Login via OAuth server",
            "uri": "http://oauth.server/auth?client_id=xyz&scope=contact&redirect_uri=http%3A%2F%2Fresource.server%2Fauth"
        }
    ]
}

2) Client choses navigate provider and navigates to OAuth URL.

3) OAuth server responds with MetaWeb document which describes UI/mechanisms to log in and authorize request.

GET http://oauth.server/auth
...
---

HTTP/1.1 200 OK
Content-type: application/x.meta+json

{
    "@doctype": "meta/resource",
    "label": "Authorize aplication Resource server",
    "$req": {
        "@type": "meta/data",
        "value": {
            "client_id": "xyz",
            "scope": [ "contact" ],
            "redirect_uri": "http://resource.server/auth"
        }
    },
    "properties": [ ... ],
    "actions": [
        {
            "method": "POST",
            "uri": "./confirm",
            "model": $req,
            "label": "Authorize"
        }
    ]
}

4) Client invokes auth action on login resource and server responds with navigate property which is set to callback URL.

POST http://oauth.server/confirm
Content-type: application/json
...

{
    "client_id": "xyz",
    "scope": [ "contact" ],
    "redirect_uri": "http://resource.server/auth"   
}
---

HTTP/1.1 200 OK
Content-type: application/x.meta+json

{
    "@doctype": "meta/response",
    "navigate": "http://resource.server/auth?token=abc123"
}

5) Client navigates to callback URL.

6) Resource server responds on callback URL with meta/response/auth and token specified.

GET http://resource.server/auth?token=abc123
...
---

HTTP/1.1 200 OK
Content-type: application/x.meta+json

{
    "@doctype": "meta/response/auth",
    "token": "xyz456"
}
  1. Client now can access resource with MetaWeb token.
GET http://resource.server/protected.meta
...
---

HTTP/1.1 200 OK
Content-type: application/x.meta+json

{
    "@doctype": "meta/resource",
    "label": "Protected resource",
    ...
}