dhq-auth 0.1.6
{{ DESCRIPTION }}
License: MIT
Keywords: data,auth

# DataHQ auth service

[![Build Status](https://travis-ci.org/datahq/auth.svg?branch=master)](https://travis-ci.org/datahq/auth)

A generic OAuth2 authentication service and user permission manager.

## Quick start

### Clone the repo and install

`make install`

### Run tests

`make test`

### Run server

`python server.py`

## Env Vars
- `PRIVATE_KEY` & `PUBLIC_KEY` an RSA key-pair in PEM format.
  See `tools/generate_key_pair.sh` for more info.
- `GOOGLE_KEY` & `GOOGLE_SECRET`: OAuth credentials for authenticating with Google
- `GITHUB_KEY` & `GITHUB_SECRET`: OAuth credentials for authenticating with Github
- `DATABASE_URL`: A SQLAlchemy compatible database connection string (where user data is stored)
- `EXTERNAL_ADDRESS`: The hostname where this service is located on
- `ALLOWED_SERVICES`:
    Which permissions providers are available. A `;` delimited list of provider identifiers.
    Each provider identifier takes the form of `[alias:]provider`, where `provider` is the name of a Python module
    which exports a `get_permissions(service, userid)` function.
- `INSTALLED_EXTENSIONS`:
    List of installed extensions. A `;` delimited list of `extension` - the name of a Python modules which exports one or all of these functions
    - `on_new_user(user_info)`
    - `on_user_login(user_info)`
    - `on_user_logout(user_info)`


## API

### Check an authentication token's validity
`/auth/check`

**Method:** `GET`

**Query Parameters:**

 - `jwt` - authentication token
 - `next` - URL to redirect to when finished authentication

**Returns:**

If authenticated:

```json
{
    "authenticated": true,
    "profile": {
        "id": "<user-id>",
        "name": "<user-name>",
        "email": "<user-email>",
        "avatar_url": "<url-for-user's-profile-photo>",
        "idhash": "<unique-id-of-the-user>",
        "username": "<user-selected-id>" # If user has a username
    }
}
```

If not:

```json
{
    "authenticated": false,
    "providers": {
        "google": {
            "url": "<url-for-logging-in-with-the-Google-provider>"
        },
        "github": {
            "url": "<url-for-logging-in-with-the-Github-provider>"
        },
    }
}
```

When the authentication flow is finished, the caller will be redirected to the `next` URL with an extra query parameter
`jwt` which contains the authentication token. The caller should cache this token for further interactions with the API.

### Get permission for a service
`/auth/authorize`

**Method:** `GET`

**Query Parameters:**

 - `jwt` - user token (received from `/user/check`)
 - `service` - the relevant service (e.g. `storage-service`)

**Returns:**

```json
{
    "token": "<token-for-the-relevant-service>"
    "userid": "<unique-id-of-the-user>",
    "permissions": {
        "permission-x": true,
        "permission-y": false
    },
    "service": "<relevant-service>"
}
```

### Change the username
`/auth/update`

**Method:** `POST`

**Query Parameters:**

 - `jwt` - authentication token (received from `/user/check`)
 - `username` - A new username for the user profile (this action is only allowed once)

**Returns:**

```json
{
    "success": true,
    "error": "<error-message-if-applicable>"
}
```

__Note__: trying to update other user profile fields like `email` will fail silently and return

```json
{
    "success": true
}
```

### Receive authorization public key
`/auth/public-key`

**Method:** `GET`

**Returns:**

The service's public key in PEM format.

Can be used by services to validate that the permission token is authentic.