wazo-platform / wazo-auth-client

A python client for wazo-auth

wazo-auth-client

A python library to connect to wazo-auth. HTTPS is used by default. Certificates are verified by default: if you want to omit the check or use a different CA bundle, use the verify_certificate argument when instantiating the client.

Usage:

from wazo_auth_client import Client

c = Client('localhost', username='alice', password='alice')

# Tokens
token_data = c.token.new('wazo_user', expiration=3600, session_type='mobile')  # Creates a new token expiring in 3600 seconds

token_data
{'expires_at': '2015-06-04T09:49:30.449625',
 'issued_at': '2015-06-04T08:49:30.449607',
 'token': '3d95d849-94e5-fc72-4ff8-93b597e6acf6',
 'auth_id': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'xivo_user_uuid': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'acl': ['dird']}

c.token.is_valid(token_data['token'])
True

c.token.get(token_data['token'])
{'expires_at': '2015-06-04T09:49:30.449625',
 'issued_at': '2015-06-04T08:49:30.449607',
 'token': '3d95d849-94e5-fc72-4ff8-93b597e6acf6',
 'auth_id': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'xivo_user_uuid': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'acl': ['dird']}

# ACL validation
c.token.get(token_data['token'], required_acl='foobar')  # 403

c.token.is_valid(token_data['token'], required_acl='foobar')
False

c.token.check_scopes(token_data['token'], ['dird', 'foobar'])
{'scopes': {
    'dird': True,
    'foobar': False
}}
# Tenant validation
c.token.get(token_data['token'], tenant='alice-tenant-uuid')
{'expires_at': '2015-06-04T09:49:30.449625',
 'issued_at': '2015-06-04T08:49:30.449607',
 'token': '3d95d849-94e5-fc72-4ff8-93b597e6acf6',
 'auth_id': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'xivo_user_uuid': '5cdff4a3-24a3-494f-8d32-9c8695e868f9',
 'acl': ['dird']}

c.token.is_valid(token_data['token'], tenant='alice-tenant-uuid')
True

c.token.check_scopes(token_data['token'], scopes=['dird', 'foobar'], tenant='alice-tenant-uuid')
{'scopes': {
    'dird': True,
    'foobar': False
}}

# Token revocation
c.token.revoke(token_data['token'])

c.token.is_valid(token_data['token'])
False

# Refresh tokens

# When creating a token use the `client_id` and `access_type` `offline` to get a
# refresh token with your "access token"
client_id = 'my-app'
token_data = c.token.new('wazo_user', expiration=3600, access_type='offline', client_id='my-app')
refresh_token = token_data['refresh_token']

# Creating an access token from a refresh token
# Can be created without knowing the username/password
# The client_id must match the one supplied at the refresh token creation
token_data = c.token.new('wazo_user', expiration=3600, refresh_token=refresh_token, client_id='my-app')

# Listing your refresh tokens
c.token.list(user_uuid='me')
c.token.list(user_uuid='<user_uuid>', order='created_at', direction='desc', limit=10, offset=5)

# Deleting a refresh tokens
c.token.delete(user_uuid='me', client_id=client_id)
c.token.delete(user_uuid='<user_uuid>', client_id=client_id)

# List all refresh tokens
c.refresh_tokens.list(order='created_at', direction='desc', limit=10, offset=5)

c.backends.list()
['wazo_user']

# Policies
c.set_token(token_data['token'])

# Create a new policy
c.policies.new(
    'user',
    description='The default policy for users',
    acl=[
        'confd.users.me.#'
        'dird.status.read'
    ],
    tenant_uuid='my-tenant-uuid',
)
{'uuid': '<the policy uuid>'
 'name': 'user',
 'description': 'The default policy for users',
 'acl': ['confd.users.me.#', 'dird.status.read'],
 'tenant_uuid': 'my-tenant-uuid'}

# Get a policy by UUID
c.policies.get('<the policy uuid>')
{'uuid': '<the policy uuid>'
 'name': 'user',
 'description': 'The default policy for users',
 'acl': ['confd.users.me.#', 'dird.status.read'],
 'tenant_uuid': 'my-tenant-uuid'}

# List or search policies
c.policies.list(search='user', order='name', direction='asc', limit=10, offset=0, tenant_uuid='my-tenant-uuid', recurse=True)
{'items': [
    {'uuid': '<the policy uuid>'
     'name': 'user',
     'description': 'The default policy for users',
     'acl': ['confd.users.me.#', 'dird.status.read'],
     'tenant_uuid': 'my-tenant-uuid'}
 ],
 'total': 1}

# Modify a policy
c.policies.edit('<the policy uuid>', 'user', 'A new description', ['#'])
{'uuid': '<the policy uuid>'
 'name': 'user',
 'description': 'A new description',
 'acl': ['#'],
 'tenant_uuid': 'my-tenant-uuid'}

# Add or remove access
c.policies.remove_access('<the policy uuid>', '#')
c.policies.add_access('dird.status.read')
c.policies.add_access('confd.user.me.read')

c.policies.get('<the policy uuid>')
{'uuid': '<the policy uuid>'
 'name': 'user',
 'description': 'A new description',
 'acl': ['dird.status.read', 'confd.users.me.read'],
 'tenant_uuid': 'my-tenant-uuid'}

# delete a policy
c.policies.delete('<the policy uuid>')

# Users

# Creating a user

user = c.users.new(username='alice', email_address='[e-mail]', password='s3cr37')
user = c.users.new(username='alice', email_address='[e-mail]', password='s3cr37', tenant='my-tenant')

user = c.users.register(username='alice', email_address='[e-mail]', password='s3cr37')
user
{'uuid': '<user uuid>', 'username': 'alice', 'email_addresses'=[{'address': '[e-mail]', main=True, confirmed=False}]}

# Requesting a new email confirmation email
c.users.request_confirmation_email('<user_uuid>', '<email_uuid>')

# Changing the user's password
c.users.change_password(<user_uuid>, old_password='<old_password>', new_password='<new_password>')

# Reset a user's password
c.users.reset_password(username='<username>')
c.users.reset_password(email='<email>')

c.users.set_password(<user_uuid>, '<new password>', token=<token received by mail>)

# Updating the user's email addresses
emails = [{'address': '[e-mail]', 'main': True}]
c.users.update_emails(<user_uuid>, emails)

# or as an administrator
emails = [{'address': '[e-mail]', 'main': True, 'confirmed': True}]
c.admin.update_user_emails(<user_uuid>, emails)

# Adding policies to users

c.users.add_policy(<user_uuid>, <policy_uuid>)

# Removing policies from users

c.users.remove_policy(<user_uuid>, <policy_uuid>)

# Listing users

c.users.list(search='foo', limit=5, offset=10, order='username', direction='asc')
{'total': 42,
 'filtered': 5,  # Number of user matching "foo"
 'items': ...,  # The list of users
}

# Deleting a user

c.users.delete('<user-uuid>')

# Getting a user

c.users.get('<user-uuid>')
{'uuid': '<user uuid>', 'username': 'alice', 'email_addresses'=[{'address': '[e-mail]', main=True, confirmed=False}]}

# Editing a user

c.users.edit('<user-uuid>', firstname='foo', username='bar')
{'uuid': '<user uuid>', 'username': 'foo', 'lastname': None, email_addresses=<email addresses>}


# Groups

# Creating a group
group = c.groups.new(name='<group_name>')

# Getting a group
c.groups.get(group['uuid'])

# Modifying a group
c.groups.edit(group['uuid'], {'name': '<new name>'})

# Listing groups
c.groups.list(search='<searched term>', name='<exact match search on name>', order='name', direction='desc', limit=10, offset=20)

# Deleting a group
c.groups.delete(group['uuid'])

# Adding a user to a group
c.groups.add_user(group['uuid'], <user_uuid>)

# Removing a user from a group
c.groups.remove_user(group['uuid'], <user_uuid>)

# List users in a group
c.groups.get_users(group['uuid'])

# List all groups a user belongs to
c.users.get_groups(<user_uuid>)


# Sessions

# Listing sessions
c.sessions.list(limit=10, offset=20)

# Deleting session
c.sessions.delete(<session_uuid>)

# List all sessions a user belongs to
c.users.get_sessions(<user_uuid>)

# Removing a session from a user
c.users.remove_session(<user_uuid>, <session_uuid>)


# Tenants

# Creating a tenant
c.tenants.new(name='<new tenant name>')

# Updating a tenant
c.tenants.edit('<tenant_uuid>', name='<new tenant name>')

# External authentification storage
c.external.create('<auth_service>', '<user_uuid>', {'key': 'value'})
c.external.update('<auth_service>', '<user_uuid>', {'key': 'value'})
c.external.get('<auth_service>', '<user_uuid>')
c.external.delete('<auth_service>', '<user_uuid>')
c.external.list('<user_uuid>', search='<search term>', limit=5, offset=10, order='type', direction='asc')
c.external.list_connected_users('<auth_service>', limit=5, offset=10, recurse=True)

# check the current status of wazo-auth
c.status.check()

# Config

config = c.config.get()

config_patch = {
    'op': 'replace',
    'path': '/debug',
    'value': True,
}
c.config.patch(config_patch)

# To use a given certificate file

from wazo_auth_client import Client

c = Client('localhost', username='alice', password='alice', verify_certificate='</path/to/trusted/certificate>')

token_data = c.token.new('wazo_user')

# LDAP backend configuration

# Get the LDAP configuration

ldap_config = c.ldap_config.get()  # Uses the token's tenant
ldap_config = c.ldap_config.get(tenant_uuid=<tenant_uuid>)

# Update the LDAP configuration

c.ldap_config.update(ldap_config)  # Uses the token's tenant
c.ldap_config.update(ldap_config, tenant_uuid=<tenant_uuid>)

c.ldap_config.delete()  # Uses the token's tenant
c.ldap_config.delete(tenant_uuid=<tenant_uuid>)