FamilyWall API

h1. Authentification

h1. 1 Principles

h2. 1.1 Account

In the platform a user having family data is called an account. An account may be authenticated on the platform and has:

* One or several identifiers

* A Password: Password of a user is stored in the databased with a BCrypt Hash

h2. 1.2 Account identifiers

Each user's account on the platform is identified by one or several identifiers. Identifier properties are:

* The 'type', which is an enum that may be: 

> * Email: an email

> * Msisdn: a phone number (not used at the moment)

> * ExternalId: the id of an external system (for SSO integration)

> * Login: a login (free-form string)

> * AccessToken: a random string being an identifier for a cryptographic authentication token

> * SOMETHING_ELSE: reserved for extension mechanism.

* The 'value', which correspond to the type and must be totally unique across all users

h2. 1.3 Type of Authentication 

The server APIs falls into two different categories: 

- _*Account-based api*_ :

> API where the api call is relative to an account, such as wall/get (retrieve wall messages). Such apis do always work on the user's account data or on the behalf of the Account, and the account in question is not passed as an explicit argument to the api. It is an implicit argument. 

> Such apis mandate the caller to be authenticated and that the authentication corresponds to an account on the platform.

- _*Non-account-based api*_ , such as createAccount:

> API which does not consider the logged account as an implicit argument. Such apis may mandate the client (or the calling application) to be authenticated, but does not mandate that the authentication correspond to an account on the platform. For instance, the client, or an administrator, may be authenticated to perform such api calls, but they do not automatically correspond to an account.

As a result, an api call can be authenticated in two fashion:

- _*Client Authentication*_

> Authentication recognize the calling application and associated right to can one or another api

- _*Account Authentication*_

> Authentication recognize the account and therefore enable calling account-based api.

> Both authentication can be available at the same time.

For the moment, only Account Authentication is implemented, and all apis except for the "log2" api requires Account Authentication. "log2" api does not requires authentication now but will at least requires Client authentication in the future.

h2. 1.3 Client authentication

> Application are not authenticated at the moment.

> As a consequences, non-account-based apis are not authenticated, too...

*To be completed.*

h2. 1.4 HTTP Sessions

The api support (and even requires for performance reason) a session concept over HTTP.

At any time during an HTTP api call the server _MAY_ respond with an additional Set-Cookie HTTP header, setting a JSESSIONID http cookies.

At any subsequent call the the server, the client _MUST_ return the JSESSION id cookie, and ONLY this cookie. The cookie time-to-live on the client may be short and shall, if possible, correspond to a user session, if applicable.

At any time the server may invalidate an HTTP session and resend a JSESSIONID. However the server shall implement an HTTP session time-to-live based on a 30 minutes timeout after the lastest access.

h1. 2 Simple login/password authentication based on the http session

> This Authentication scheme will be deprecated in the future, because it does not support Client Authentication, and is poorly secure.

This authentication scheme consist in calling the log2in api priori to any other account-based API. Non account-based apis are left unauthenticated.

By calling the log2in api, the identifier/password are passed to the system and verified. The identifier must correspond to an account's identifier and the password must pass the hash test of the corresponding account.

If the authentication is successful, the current HTTP session will become Account Authenticated up to the end of the HTTP Session. 

The api log2out may be called to remove the account authentication from the current HTTP Session. This will also invalidate the current HTTP session.

Because an http session can be invalidated by the server at any time (or almost at any time, the server _SHALL_ implement a 30 minutes timeouts after the last call on a session), the client _SHALL_ be ready to manage any 501:FizAccountNotFoundInSessionException errors and redo a log2in call.

h2. 2.1 Authorization errors:

Whenever an account-based api is called without an account authentication, the following error will be returned to the caller:

501 :  FizAccountNotFoundInSessionException

h1. 3 OAuth2 Authentication

h2. 3.1 OAuth2 Presentation

The system is able to use various (but not all) OAuth2 authentication scenarios to provide access to account-based apis.

> Based on The OAuth 2.0 Authorization Protocol (draft-ietf-oauth-v2-23) (see http://datatracker.ietf.org/doc/draft-ietf-oauth-v2/ )

The principle is that the client must obtain an Access-Token and a Refresh-Token from the server, and then use the Access-Token to authenticate itself and use account-based apis. In order to obtain the Access-Token and the Refresh-Token, the client must use HTTPS/TLS.

The type of access-token managed by the server is "MAC Access Authentication" .

> Based on HTTP Authentication: MAC Access Authentication, draft-ietf-oauth-v2-http-mac-01 (see http://datatracker.ietf.org/doc/draft-ietf-oauth-v2-http-mac/ )

The MAC Access Token is secure enough in order to be used on plain http connection instead of HTTPS/TLS. However his time-to-live is medium-lived (ie several days). When an Access Token is obsolete, the client must use the Refresh Token to obtain a new Access Token, using HTTPS/TLS. The Refresh Token is much more long lived (several years).

The Access-Token is used by signing an http request with the token secret with a hmac algorithm and put the signature in the Authorization Header of the http request.

> Note that this authentication mechanism does not aleviate the client from handling the HTTP Sessions cookies. However the HTTP sessions will be transparently recreated and re-authenticated and the usage of the log2in api is not necessary anymore.

In order to retrieve the Access-Token or the Refresh-Token, several scenario are possible, depending on the type of application, the type of client, etc...

The following scenario are implemented:

# Oauth2 Password based authentication

*TBD: access of non-account based apis.*

*TBD: Client Authentication.*

h2. 3.2 OAuth2 error codes

When an access token is required and missing the following error is returned to the client:

<pre>

HTTP/1.1 401 Unauthorized

  WWW-Authenticate: MAC

</pre>

When an access token is obsolete the following error is returned to the client:

<pre>

HTTP/1.1 401 Unauthorized

  WWW-Authenticate: MAC Expired

</pre>

For other errors the WWW-Authenticate will provide various error messages.

h2. 3.3 Compatibility with authentication based on the http session

Normally, resource protected by OAuth will deny access of any request that do not have a valid Authorization Header.

However, when using the "Simple login/password authentication based on the http session" (see #2.0) concurrently, we have the following policy:

For accessing account-based apis:

# Any http request passed with an http session identified authentified with the "Simple login/password authentication based on the http session" will not require the OAuth 2.0 authentification

# Any other http request will requires the OAuth Authorization http header

For non-account-based apis, for the moment they are left unauthentified while we implement security on non-account based apis.

h2. 3.4 Fiz specific URL references

The following URL endpoint are defined:

* Token endpoint : https://<SERVER_URL/token

* 

h2. 3.5 Refresh Token usage

In order to use the refresh token, the client must present the refresh token to the /token endpoint in HTTPS/TLS.

See #6 of IETF OAuth specification.

Example:

<pre>

POST /token HTTP/1.1

  Host: server.example.com

  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  Content-Type: application/x-www-form-urlencoded;charset=UTF-8

  grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

</pre>

h2. 3.6 Access-Token response format

As defined in both ietf specification, the access token will be returned in JSON.

The only type of access-token managed is "mac". 

The only type of max algorithm managed is "hmac-sha-1".

<pre>

HTTP/1.1 200 OK

  Content-Type: application/json;charset=UTF-8

  Cache-Control: no-store

  Pragma: no-cache

  {

    "access_token":"2YotnFZFEjr1zCsicMWpAA",

    "token_type":"mac",

    "expires_in":3600,

    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",

	"mac_key":"AEZRDF41424aezraezr",

	"mac_algorithm","hmac-sha-1"

  }

</pre>

h2. 3.7 Using the MAC SHA1 access-token to generate Authorization request.

It is actually all explained here : draft-ietf-oauth-v2-http-mac-01 , but I will summarize the procedure here:

# Generate the request Timetsamp in seconds

# Generate a random number to be used as a nonce

# From the request being done, extract the HOST, PORT, HTT_METHOD, and FULL_PATH_OF_QUERY

# Concatenate all Timestamp, nonce, and information extracted from request into a string

# Compute the hmac of the concatenated string with the mac_key

# Generate and add an Authorization header in the http request

The format of the Authorization header is:

<pre>

 Authorization: MAC id="h480djs93hd8",

                     ts="1336363200",

                     nonce="dj83hs9s",

                     mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

</pre>

The id is the "access_token" value, the ts is the timestamp, the nonce is (well) the nonce, and the mac is the result of the hmac computation.

h1. 4 Oauth2 Password based authentication

This type of authentication is suitable for privilegied application that take care of asking and managing the user's password.

It is  "Resource Owner Password Credentials Grant"

In order to retrieve an access token and a refresh token the user must call the /token endpoint in HTTPS/TLS. The username must be a valid account identifier value.

Example with a account identifier being an email:

<pre>

POST /token HTTP/1.1

  Host: stagingapi.familywall.com

  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

  Content-Type: application/x-www-form-urlencoded;charset=UTF-8

  grant_type=password&username=johndoe@x.com&password=A3ddj3w

</pre>

Note: as of now, because client authentication is not supported, the Authorization header shall not be included

The typical response will be an Access-token and a Refresh-Token in JSON as defined in #3.6