Metadata-Version: 2.0
Name: kinto-fxa
Version: 2.5.2
Summary: Firefox Accounts support in Kinto
Home-page: https://github.com/Kinto/kinto-fxa
Author: Mozilla Services
Author-email: services-dev@mozilla.com
License: Apache License (2.0)
Description-Content-Type: UNKNOWN
Keywords: web services
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: License :: OSI Approved :: Apache Software License
Requires-Dist: kinto (>=5.0)
Requires-Dist: pyfxa (>=0.0.9)
Provides-Extra: scripts
Requires-Dist: SQLAlchemy; extra == 'scripts'
Requires-Dist: boto3; extra == 'scripts'
Requires-Dist: ec2-metadata; extra == 'scripts'
Requires-Dist: psycopg2 (>2.5); extra == 'scripts'
Requires-Dist: zope.sqlalchemy; extra == 'scripts'

Firefox Accounts support in Kinto
=================================

|travis| |master-coverage|

.. |travis| image:: https://travis-ci.org/Kinto/kinto-fxa.svg?branch=master
    :target: https://travis-ci.org/Kinto/kinto-fxa

.. |master-coverage| image::
    https://coveralls.io/repos/Kinto/kinto-fxa/badge.png?branch=master
    :alt: Coverage
    :target: https://coveralls.io/r/Kinto/kinto-fxa

*Kinto-fxa* enables authentication in *Kinto* applications using
*Firefox Accounts* OAuth2 bearer tokens.

N.B. This project used to be called *cliquet-fxa*, but was renamed to
  *kinto-fxa* following the rename of the *cliquet* project to
  *kinto*.

It provides:

* An authentication policy class;
* Integration with *Kinto* cache backend for token verifications;
* Integration with *Kinto* for heartbeat view checks;
* Some optional endpoints to perform the *OAuth* dance (*optional*).


* `Kinto documentation <http://kinto.readthedocs.io/en/latest/>`_
* `Issue tracker <https://github.com/Kinto/kinto-fxa/issues>`_


Installation
------------

As `stated in the official documentation <https://developer.mozilla.org/en-US/Firefox_Accounts>`_,
Firefox Accounts OAuth integration is currently limited to Mozilla relying services.

Install the Python package:

::

    pip install kinto-fxa


Include the package in the project configuration:

::

    kinto.includes = kinto_fxa

And configure authentication policy using `pyramid_multiauth
<https://github.com/mozilla-services/pyramid_multiauth#deployment-settings>`_ formalism:

::

    multiauth.policies = fxa
    multiauth.policy.fxa.use = kinto_fxa.authentication.FxAOAuthAuthenticationPolicy

By default, it will rely on the cache configured in *Kinto*.


Configuration
-------------

Fill those settings with the values obtained during the application registration:

::

    fxa-oauth.client_id = 89513028159972bc
    fxa-oauth.client_secret = 9aced230585cc0aaea0a3467dd800
    fxa-oauth.oauth_uri = https://oauth-stable.dev.lcip.org/v1
    fxa-oauth.requested_scope = profile kinto
    fxa-oauth.required_scope = kinto
    fxa-oauth.webapp.authorized_domains = *
    # fxa-oauth.cache_ttl_seconds = 300
    # fxa-oauth.state.ttl_seconds = 3600


In case the application shall not behave as a relier (a.k.a. OAuth dance
endpoints disabled):

::

    fxa-oauth.relier.enabled = false


If necessary, override default values for authentication policy:

::

    # multiauth.policy.fxa.realm = Realm

Handling multiple FxA clients
:::::::::::::::::::::::::::::

If you want to isolate data between two FxA apps using the same Kinto
service to sync their data you can define client specific
configuration:

::

    fxa-oauth.clients.notes.client_id = 89513028159972bc
    fxa-oauth.clients.notes.required_scope = profile app-notes

    fxa-oauth.clients.todo.client_id = 1805184631529d5a
    fxa-oauth.clients.todo.required_scope = profile app-todo


Depending on the requested scopes, Kinto Fxa will assign a user id or
another (using a suffix):

  - `fxa:{user_id}-notes` for the former
  - `fxa:{user_id}-todo` for the later

Note that you can still use `fxa:{user_id}` to explicitely share data between
apps for a given FxA user.

If you don't give any specific permission, it will be impossible for
someone logged in in with the `app-notes` scope in their Bearer token to
access the todo app data.

The default buckets will also be isolated, one for `notes` and one for
`todo`.

Login flow
----------

OAuth Bearer token
::::::::::::::::::

Use the OAuth token with this header:

::

    Authorization: Bearer <oauth_token>


:notes:

    If the token is not valid, this will result in a ``401`` error response.


Obtain token using Web UI
:::::::::::::::::::::::::

* Navigate the client to ``GET /fxa-oauth/login?redirect=http://app-endpoint/#``.
  There, a session cookie will be set, and the client will be redirected to a login
  form on the FxA content server;
* After submitting the credentials on the login page, the client will
  be redirected to ``http://app-endpoint/#{token}`` (the web-app).


Obtain token custom flow
::::::::::::::::::::::::

The ``GET /v1/fxa-oauth/params`` endpoint can be use to get the
configuration in order to trade the *Firefox Accounts* BrowserID with a
*Bearer Token*. `See Firefox Account documentation about this behavior
<https://developer.mozilla.org/en-US/Firefox_Accounts#Firefox_Accounts_BrowserID_API>`_

.. code-block:: http

    $ http GET http://localhost:8000/v0/fxa-oauth/params -v

    GET /v0/fxa-oauth/params HTTP/1.1
    Accept: */*
    Accept-Encoding: gzip, deflate
    Host: localhost:8000
    User-Agent: HTTPie/0.8.0


    HTTP/1.1 200 OK
    Content-Length: 103
    Content-Type: application/json; charset=UTF-8
    Date: Thu, 19 Feb 2015 09:28:37 GMT
    Server: waitress

    {
        "client_id": "89513028159972bc",
        "oauth_uri": "https://oauth-stable.dev.lcip.org",
        "scope": "profile"
    }


Scripts
-------

The ``kinto-fxa`` library installs a ``kinto-fxa`` command which is
used to run utility scripts that come with the ``kinto-fxa``
plugin. Right now the only one is ``process-account-events``, which
listens to an Amazon SQS queue for account deletion events and tries
to delete a user's data to comply with GDPR.

These scripts have some additional dependencies; you may need to ``pip
install kinto-fxa[scripts]`` to install them.

To use them, run ``kinto-fxa [script-name] [arguments]``.


Changelog
=========

This document describes changes between each past release.

2.5.2 (2018-07-05)
------------------

**Bug fixes**

- Fix the ``process-account-events`` script to take client user ID suffixes into account (fixes #61)


2.5.1 (2018-06-28)
------------------

- Set up metrics on the ``process-account-events`` script (#57).
- Set up logging on the ``kinto_fxa.scripts`` programs (#58).


2.5.0 (2018-05-17)
------------------

- Introduce new ``kinto_fxa.scripts``. Right now the only script
  available is ``process-account-events``, which listens to an SQS
  queue for user delete events and deletes data from that user's
  default bucket, in order to comply with GDPR.


2.4.1 (2018-03-15)
------------------

- Move kinto-fxa to the Kinto github org. (#54)


2.4.0 (2017-11-27)
------------------

- Add support for multiple FxA Clients (#52)


2.3.1 (2017-01-30)
------------------

**Bug fixes**

- Make sure that caching of token verification nevers prevents from authenticating
  requests (see Mozilla/PyFxA#48)


2.3.0 (2016-12-22)
------------------

**Internal changes**

- Migrate schemas to Cornice 2 #38


2.2.0 (2016-10-27)
------------------

**New features**

- Improve FxA error messages (fixes #1)

**Bug fixes**

- Optimize authentication policy to avoid validating the token several times
  per request (fixes #33)

**Internal changes**

- Use Service from kinto.core (fixes #28)
- Make sure it does not catch Cornice 2 dependency (#36)


2.1.0 (2016-09-08)
------------------

- Add the plugin version in the capability.


2.0.0 (2016-05-19)
------------------

**Breaking changes**

- Project renamed to *Kinto-fxa* to match the rename of ``cliquet`` to
  ``kinto.core``.

- Update to ``kinto.core`` for compatibility with Kinto 3.0. This
  release is no longer compatible with Kinto < 3.0, please upgrade!

- With *Kinto* > 2.12*, the setting ``multiauth.policy.fxa.use`` must now
  be explicitly set to ``kinto_fxa.authentication.FxAOAuthAuthenticationPolicy``

**Bug fixes**

- Fix checking of ``Authorization`` header when python is ran ``-O``
  (ref mozilla-services/cliquet#592)


1.4.0 (2015-10-28)
------------------

-  Updated to *Cliquet* 2.9.0

**Breaking changes**

- *cliquet-fxa* cannot be included using ``pyramid.includes`` setting.
  Use ``cliquet.includes`` instead.


1.3.2 (2015-10-22)
------------------

**Bug fixes**

- In case the Oauth dance is interrupted, return a ``408 Request Timeout``
  error instead of the ``401 Unauthenticated`` one. (#11)
- Do not call ``cliquet.load_default_settings`` from cliquet-fxa (#12)


1.3.1 (2015-09-29)
------------------

- Separate multiple scopes by a + in login URL.


1.3.0 (2015-09-29)
------------------

**Bug fixes**

- Multiple scopes can be requested on the login flow.
- Multiple scopes can be required for the app.

**Configuration changes**

- ``fxa-oauth.scope`` is now deprecated. ``fxa-oauth.requested_scope`` and
  ``fxa-oauth.required_scope`` should be used instead.


1.2.0 (2015-06-24)
------------------

- Add default settings to define a policy "fxa".
  It is now possible to just include ``cliquet_fxa`` and
  add ``fxa`` to ``multiauth.policies`` setting list.
- Do not check presence of cliquet cache in initialization
  phase.
- Do not use Cliquet logger to prevent initialization errors.


1.1.0 (2015-06-18)
------------------

- Do not prefix authenticated user with ``fxa_`` anymore (#5)


1.0.0 (2015-06-09)
------------------

- Imported code from *Cliquet*


Contributors
============

* Alexis Metaireau <alexis@mozilla.com>
* Mathieu Leplatre <mathieu@mozilla.com>
* Nicolas Perriault <nperriault@mozilla.com>
* Rémy Hubscher <rhubscher@mozilla.com>
* Tarek Ziade <tarek@mozilla.com>
* Lavish Aggarwal <lucky.lavish@gmail.com>


