wazo-auth

An authentication micro-service able to create tokens, check ACLs, delete expired tokens and much more.

• Create and manage users
• Create and manage groups
• Create and manage policies
• Create and store tokens
• External authentication with LDAP, Google and Microsoft

Usage

Launching wazo-auth

wazo-auth [--user <user>] --config-file <path/to/config/file>

Getting a token

curl -k -i -X POST -H 'Content-Type: application/json' -u "alice:alice" "http://localhost:9497/0.1/token" -d '{}'

Retrieving token data

curl -k -i -X GET -H 'Content-Type: application/json' "http://localhost:9497/0.1/token/${TOKEN}"

Bootstrapping wazo-auth

In order to be able to create users, groups and policies you have to be authenticated. The bootstrap process allows the administrator to create a first user with the necessary rights to be able to add other users.

We create the initial credentials. The username and password can then be used to create a token with the # acl. This can be done using the wazo-auth-bootstrap command.

wazo-auth-bootstrap complete

This script will create a configuration file named /root/.config/wazo-auth-cli/050-credentials.yml containing all necessary information to be used from the wazo-auth-cli.

Docker

The wazoplatform/wazo-auth image can be built using the following command:

docker build -t wazoplatform/wazo-auth .

The wazoplatform/wazo-auth-db image can be built using the following command:

docker build -f contribs/docker/Dockerfile-db -t wazoplatform/wazo-auth-db .

Configuration

The default configuration file is located in /etc/wazo-auth/config.yml. As with all other Wazo services, it can be overridden (and should only be overridden this way) with YAML files located in /etc/wazo-auth/conf.d/.

Enabling the users registration API

To enable the users registration (/users/register) API endpoint, add a file containing the following lines to the /etc/wazo-auth/conf.d directory and restart wazo-auth

enabled_http_plugins:
  user_registration: true

Profiling

If you need to profile an API to understand why it is slow, you can use the setting profiling_enabled: true, or enable it live with PATCH /0.1/config.

When profiling is enabled, the profiles will be logged in /tmp/wazo-profiling, one file per request. Profiles are Python profiles from the module cProfile. Profiles can then be analyzed with CLI or GUI tools like snakeviz.

Testing

Running unit tests

apt-get install libldap2-dev libpq-dev python3-dev libffi-dev libyaml-dev libsasl2-dev
pip install tox
tox --recreate -e py311

Running integration tests

You need a SAML test account and configuration, you need to create a configuration file .integration_tests/asses/saml/config/saml.json with following json:

{
  "login": "entraLogin",
  "password": "entraPwd"
}

then run

playwright install
tox -e integration

Note: If you update the test-requirements-for-tox.ini file don't forget to run tox --recreate -e integration. Note: The playwright install command installs the required browsers to run tests.

Playwright can be executed with headed browser and in a slowmotion mode, you need to uncomment some lines in tox.ini integration section and run: tox -e integration -- suite/test_saml.py --headed --slowmo 1000

You can also use the GUI debugger - another modification available in tox.ini is required.

Load testing

It is possible to test wazo-auth with ab.

Dependencies

• ab

apt-get update && apt-get install apache2-utils

Running the tests

With the following content in /tmp/body.json

{}

ab -n1000 -c25 -A 'alice:alice' -p /tmp/body.json -T 'application/json' "http://localhost:9497/0.1/token"

This line will start 25 process creating 1000 tokens with the username and password alice alice

Performance tests

Adding a test

Performance tests are similar to integration tests and may be added to integration_tests/performance_suite.

Profiling

Integration/performance tests may be used to profile specific API endpoints. To do so:

    with self.profiling_enabled():
        result = self.client.tenants.list(...)

This will enable the configuration option profiling_enabled in the service and produce profiling files in /tmp/wazo-profiling on the container and in /tmp/wazo-profiling-* on the host filesystem.

The output directory for profile files in tests can be configured with the env variable WAZO_TEST_PROFILING_DIR.

The profile files can then be analyzed with visual tools like snakeviz.

Functional tests

Can be run using tox -e functional.

Requires following environment variables to be set: WAZO_SAML_LOGIN WAZO_SAML_PASSWORD

You can use WAZO_SAML_CONFIG_FILE variable to specify a SAML credentials config file.

How to get help

If you ever need help from the Wazo Platform community, the following resources are available:

• Discourse
• Mattermost

Contributing

You can learn more on how to contribute in the Wazo Platform documentation.

License