Nexaas ID Python client
Project description
# Nexaas ID Client
This is a client for Nexaas ID. It brings support for generic OAuth
authentication and for Django and Flask frameworks.
## OAuth client
The general use is:
```python
from nexaas_id_client import NexaasIDOAuthClient
client = NexaasIDOAuthClient(
application_token,
application_secret,
server='id.nexaas.com',
redirect_uri=application_callback,
)
```
The authorization URL can get from `client.authorize_url` and the access token
can be retrieve in the callback procedure from `client.get_access_token(code)`,
where `code` is the access grant code.
### Settings for Django and Flask
- `NEXAAS_ID_CLIENT_ID`: the application token
- `NEXAAS_ID_CLIENT_SECRET`: the application secret
- `NEXAAS_ID_HOST`: the Nexaas ID host
- `NEXAAS_ID_CLIENT_SCOPE`: the scope (can be `None`)
### Django
In Django you must include the following path to the main `urlpatterns`:
```python
path('oauth/', include('nexaas_id_client.support.django.urls'))
```
The views that requires authorized access must be decorated:
```python
from nexaas_id_client.support.django.decorators import authorization_required
@authorization_required
def index(request, api_client: 'nexaas_id_client.NexaasIDClient') -> 'django.http.request.HttpResponse':
...
```
Your view must expect an `api_client` as argument – see bellow. Anyway you can
retrieve de access token from the session, under the key `oauth_access_token`.
In order to logout, use the app route `signout`. The query string key
`next_url` inform where to redirect after sign out.
**Caution:** If the view returns falsy (`None`, `False`, `0`, `""`, et cetera),
the `authorization_required` decorator redirects to sign out URL.
### Flask
The Flask support supplies a blueprint capable of deal with Nexaas ID OAuth.
The use:
```python
from flask import Flask
from nexaas_id_client.support.flask import oauth
app = Flask(__name__)
app.register_blueprint(oauth, url_prefix='/oauth')
```
The decorator is similar to Django support:
```python
from nexaas_id_client.support.flask import authorization_required, oauth
...
@app.route('/')
@authorization_required
def index(api_client: 'nexaas_id_client.NexaasIDClient') -> 'flask.Response':
...
```
Your view must expect an `api_client` as argument – see bellow. Anyway you can
retrieve de access token from the session, under the key `oauth_access_token`.
In order to logout, use the blueprint route `signout`. The query string key
`next_url` inform where to redirect after sign out.
## API client
The API client is responsible for dealing with Nexaas ID API.
You can get it this way:
```python
api_client = NexaasIDClient.from_oauth(
client.get_access_token(code),
client=client,
)
```
Where `client` is the OAuth client and `code` is the access grant code.
But, if you are using a framework support, you don’t need to do it: views
decorated by `authorization_required` will receive an API client ready to use.
### Resource API
The API client attributes:
- `access_token: str` – the access token
- `refresh_token: str` – the refresh token
- `scope: str` – the allowed scope
- `token: OAuthToken` – a token wrapper
- `id: str` – the client id
- `secret: str` – the client secret
- `server: urllib.parse.ParseResult` – the Nexaas ID server
- `personal_info: PersonalInfo` – the user’s personal data
- `professional_info: ProfessionalInfo` – the user’s professional data
- `emails: Emails` – a dictionary containing user id and the its e-mails list
- `contacts: Contacts` – a dictionary containing user id and its phone numbers
and eventually other contacts
- `invite(email: str) -> Invitation` – invite another user to the current
application
The classes `PersonalInfo`, `ProfessionalInfo`, `Emails`, `Contacts` and
`Invitation` are built on demand metaprogrammatically, and have an `id`
attribute (`uuid.UUID`) at least.
Other attributes you may expect:
- `PersonalInfo`
- `full_name: str`
- `first_name: str`
- `last_name: str`
- `nickname: str`
- `email: str`
- `birth: datetime.date`
- `gender: str`
- `language: str`
- `picture: str`
- `timezone: str`
- `country: str`
- `city: str`
- `bio: str`
- `ProfessionalInfo`
- `profession: str`
- `company: str`
- `position: str`
- `Emails`
- `emails: List[str]`
- `Contacts`:
- `phone_numbers: List[str]`
- `Invitation`:
- `email` (invited user)
- `requester` (inviter id)
- `OAuthToken`:
- `access_token: str`
- `refresh_token: str`
- `expired_at: datetime.datetime`
- `scope: str`
- `expired: bool` (maybe not present)
This is a client for Nexaas ID. It brings support for generic OAuth
authentication and for Django and Flask frameworks.
## OAuth client
The general use is:
```python
from nexaas_id_client import NexaasIDOAuthClient
client = NexaasIDOAuthClient(
application_token,
application_secret,
server='id.nexaas.com',
redirect_uri=application_callback,
)
```
The authorization URL can get from `client.authorize_url` and the access token
can be retrieve in the callback procedure from `client.get_access_token(code)`,
where `code` is the access grant code.
### Settings for Django and Flask
- `NEXAAS_ID_CLIENT_ID`: the application token
- `NEXAAS_ID_CLIENT_SECRET`: the application secret
- `NEXAAS_ID_HOST`: the Nexaas ID host
- `NEXAAS_ID_CLIENT_SCOPE`: the scope (can be `None`)
### Django
In Django you must include the following path to the main `urlpatterns`:
```python
path('oauth/', include('nexaas_id_client.support.django.urls'))
```
The views that requires authorized access must be decorated:
```python
from nexaas_id_client.support.django.decorators import authorization_required
@authorization_required
def index(request, api_client: 'nexaas_id_client.NexaasIDClient') -> 'django.http.request.HttpResponse':
...
```
Your view must expect an `api_client` as argument – see bellow. Anyway you can
retrieve de access token from the session, under the key `oauth_access_token`.
In order to logout, use the app route `signout`. The query string key
`next_url` inform where to redirect after sign out.
**Caution:** If the view returns falsy (`None`, `False`, `0`, `""`, et cetera),
the `authorization_required` decorator redirects to sign out URL.
### Flask
The Flask support supplies a blueprint capable of deal with Nexaas ID OAuth.
The use:
```python
from flask import Flask
from nexaas_id_client.support.flask import oauth
app = Flask(__name__)
app.register_blueprint(oauth, url_prefix='/oauth')
```
The decorator is similar to Django support:
```python
from nexaas_id_client.support.flask import authorization_required, oauth
...
@app.route('/')
@authorization_required
def index(api_client: 'nexaas_id_client.NexaasIDClient') -> 'flask.Response':
...
```
Your view must expect an `api_client` as argument – see bellow. Anyway you can
retrieve de access token from the session, under the key `oauth_access_token`.
In order to logout, use the blueprint route `signout`. The query string key
`next_url` inform where to redirect after sign out.
## API client
The API client is responsible for dealing with Nexaas ID API.
You can get it this way:
```python
api_client = NexaasIDClient.from_oauth(
client.get_access_token(code),
client=client,
)
```
Where `client` is the OAuth client and `code` is the access grant code.
But, if you are using a framework support, you don’t need to do it: views
decorated by `authorization_required` will receive an API client ready to use.
### Resource API
The API client attributes:
- `access_token: str` – the access token
- `refresh_token: str` – the refresh token
- `scope: str` – the allowed scope
- `token: OAuthToken` – a token wrapper
- `id: str` – the client id
- `secret: str` – the client secret
- `server: urllib.parse.ParseResult` – the Nexaas ID server
- `personal_info: PersonalInfo` – the user’s personal data
- `professional_info: ProfessionalInfo` – the user’s professional data
- `emails: Emails` – a dictionary containing user id and the its e-mails list
- `contacts: Contacts` – a dictionary containing user id and its phone numbers
and eventually other contacts
- `invite(email: str) -> Invitation` – invite another user to the current
application
The classes `PersonalInfo`, `ProfessionalInfo`, `Emails`, `Contacts` and
`Invitation` are built on demand metaprogrammatically, and have an `id`
attribute (`uuid.UUID`) at least.
Other attributes you may expect:
- `PersonalInfo`
- `full_name: str`
- `first_name: str`
- `last_name: str`
- `nickname: str`
- `email: str`
- `birth: datetime.date`
- `gender: str`
- `language: str`
- `picture: str`
- `timezone: str`
- `country: str`
- `city: str`
- `bio: str`
- `ProfessionalInfo`
- `profession: str`
- `company: str`
- `position: str`
- `Emails`
- `emails: List[str]`
- `Contacts`:
- `phone_numbers: List[str]`
- `Invitation`:
- `email` (invited user)
- `requester` (inviter id)
- `OAuthToken`:
- `access_token: str`
- `refresh_token: str`
- `expired_at: datetime.datetime`
- `scope: str`
- `expired: bool` (maybe not present)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
No source distribution files available for this release.See tutorial on generating distribution archives.
Built Distribution
File details
Details for the file nexaas_id_client-1.0.1-py3-none-any.whl
.
File metadata
- Download URL: nexaas_id_client-1.0.1-py3-none-any.whl
- Upload date:
- Size: 11.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/28.8.0 requests-toolbelt/0.8.0 tqdm/4.25.0 PyPy/6.0.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 232380f36a43139f788d8c0d48c0596ef4d60d60c44ef3fa54cb345567cd7812 |
|
MD5 | 403eb7ee8deaed8f43cb0b4221918ff5 |
|
BLAKE2b-256 | 7241325af8921412eb2d8696208e64818c77af5ffe6ee8f75431848f763cd603 |