pyramid_iap 0.1
Google Cloud Identity-Aware Proxy authentication policy for Pyramid
License: BSD
Keywords: Pyramid JWT IAP authentication security

============================================================
Google Cloud Identity-Aware Proxy Authentication for Pyramid
============================================================

This package implements an authentication policy for Pyramid compatible with Google Cloud's `Identity-Aware Proxy <https://cloud.google.com/iap/>`.


Configuration
=============

After configuring your Identity-Aware Proxy, get the *Signed Header JWT Audience* from its settings (detailed instructions in `Securing your app with signed headers <https://cloud.google.com/iap/docs/signed-headers-howto>`.)

To enable JWT support in a Pyramid application:

.. code-block:: python

    from pyramid.config import Configurator
    from pyramid.authorization import ACLAuthorizationPolicy
    from pyramid_iap import JWTClaimAuthenticationPolicy

    def main():
        config = Configurator()
        # Pyramid requires an authorization policy to be active.
        config.set_authorization_policy(ACLAuthorizationPolicy())
        # Identity-Aware Proxy's Signed Header JWT Audience.
        audience = "/projects/123/global/backendServices/456"
        # Enable JWT authentication.
        config.include('pyramid_iap')
        config.add_iap_jwt_claims(audience)
        config.set_authentication_policy(JWTClaimAuthenticationPolicy())

By default, the userid is the "sub" claim of the JWT token (e.g. "accounts.google.com:123456".) To instead use the "email" claim (e.g. "test@example.com") specify:

.. code-block:: python

    config.set_authentication_policy(JWTClaimAuthenticationPolicy(userid_claim="email"))


Settings
========

There are a number of flags that specify how tokens are verified.
You can either set this in your .ini-file, or pass/override them directly to the ``config.add_iap_jwt_claims()`` function.

+--------------+------------------+---------------+---------------------------------------------+
| Parameter    | ini-file entry   | Default       | Description                                 |
+==============+==================+===============+=============================================+
| audience     | iap.audience     |               | Verified audience for the token (required.) |
+--------------+------------------+---------------+---------------------------------------------+


Uncommon settings
-----------------

These settings are unlikely to be needed if you are running behind Google Cloud IAP.

+--------------+-----------------+---------------+--------------------------------------------+
| Parameter    | ini-file entry  | Default       | Description                                |
+==============+=================+===============+============================================+
| public_key_url | iap.public_key_url | https://www.gstatic.com/iap/verify/public_key | Url of keys used to verify token signatures. |
+--------------+-----------------+---------------+--------------------------------------------+
| algorithm    | iap.algorithm   | ES256         | Hash or encryption algorithm               |
+--------------+-----------------+---------------+--------------------------------------------+
| leeway       | iap.leeway      | 0             | Number of seconds a token is allowed to be expired before it is rejected. |
+--------------+-----------------+---------------+--------------------------------------------+
| http_header  | iap.http_header | x-goog-iap-jwt-assertion | HTTP header used for tokens     |
+--------------+-----------------+---------------+--------------------------------------------+
| auth_type    | iap.auth_type   | JWT           | Authentication type used in Authorization header. Unused for other HTTP headers. |
+--------------+-----------------+---------------+--------------------------------------------+


Differences with pyrmid_jwt
===========================

This package is inspired by `pyramid_jwt <https://pypi.org/project/pyramid_jwt/>` and seeks to remain compatible where possible.

* Public keys are fetched automatically from the ``public_key_url``.

* The ``create_jwt_token`` request method is not available since it is the responsiblity of the Idenitity-Aware Proxy to issue tokens.

* No authentication policy is configured by the ``add_iap_jwt_claims`` config method to provide flexibility for those using ``pyramid_multiauth``.


Changes
=======

0.1 (2019-02-14)
----------------

* Initial release