{"id":29572657,"url":"https://github.com/accelbyte/extend-vivox-authorization-service-python","last_synced_at":"2026-01-20T16:30:22.378Z","repository":{"id":268031177,"uuid":"900806669","full_name":"AccelByte/extend-vivox-authorization-service-python","owner":"AccelByte","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-23T22:11:44.000Z","size":2261,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-12-25T11:57:39.746Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccelByte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-09T14:03:13.000Z","updated_at":"2025-12-23T22:11:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"af0f4895-83d5-48f1-baaf-fe443480ac79","html_url":"https://github.com/AccelByte/extend-vivox-authorization-service-python","commit_stats":null,"previous_names":["accelbyte/extend-vivox-authorization-service-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AccelByte/extend-vivox-authorization-service-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fextend-vivox-authorization-service-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fextend-vivox-authorization-service-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fextend-vivox-authorization-service-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fextend-vivox-authorization-service-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccelByte","download_url":"https://codeload.github.com/AccelByte/extend-vivox-authorization-service-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fextend-vivox-authorization-service-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T05:10:45.374Z","updated_at":"2026-01-20T16:30:22.369Z","avatar_url":"https://github.com/AccelByte.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# extend-vivox-authorization-service-python\n\nA Vivox authentication service is essential for integrating AccelByte Gaming Services (AGS), Vivox, and game clients. It generates the signed Vivox token that game clients need to interact with Vivox. This token is valid for 90 seconds, so game clients must regularly call the service to obtain a new token.\n\n```mermaid\nsequenceDiagram\n    autonumber\n\n    participant GC as Game Client\u003cbr\u003e(or Game Server)\n    box YOU ARE HERE\n        participant ESE as Vivox Authentication Service\u003cbr\u003e(Extend Service Extension app)\n    end\n    participant V as Vivox\n\n    note over GC, V: A. Vivox login\n\n    GC -\u003e\u003e ESE: Get Vivox login token\n    activate ESE\n    ESE --\u003e\u003e GC: Return Vivox login token\n    deactivate ESE\n    GC -\u003e\u003e V : Vivox login (login token, user id)\n    activate V\n    V --\u003e\u003e GC: Vivox login success\n    deactivate V\n\n    note over GC, V: B. Vivox join\n\n    GC -\u003e\u003e ESE: Get Vivox join token\n    activate ESE\n    ESE --\u003e\u003e GC: Return Vivox join token\n    deactivate ESE\n    GC -\u003e\u003e V : Vivox join (join token, channel id)\n    activate V\n    V --\u003e\u003e GC: Vivox join success\n    deactivate V\n\n    note over GC, V: C. Vivox join muted\n\n    GC -\u003e\u003e ESE: Get Vivox join muted token\n    activate ESE\n    ESE --\u003e\u003e GC: Return Vivox join muted token\n    deactivate ESE\n    GC -\u003e\u003e V : Vivox join muted (join muted token, channel id)\n    activate V\n    V --\u003e\u003e GC: Vivox join muted success\n    deactivate V\n\n    note over GC, V: D. Vivox kick\n\n    GC -\u003e\u003e ESE: Get Vivox kick token\n    activate ESE\n    ESE --\u003e\u003e GC: Return Vivox kick token\n    deactivate ESE\n    GC -\u003e\u003e V : Vivox kick (kick token, channel id)\n    activate V\n    V --\u003e\u003e GC: Vivox kick success\n    deactivate V\n```\n\n## Overview\n\nThis repository provides a project template for an `Vivox Authorization Service` Extend Service Extension app written in `Python`. It includes a ready to use service to generate Vivox access token. This web service created using a stack that includes a `gRPC Server` and the [gRPC Gateway](https://github.com/grpc-ecosystem/grpc-gateway?tab=readme-ov-file#about). Additionally, it comes with built-in instrumentation for observability, ensuring that metrics, traces, and logs are available upon deployment.\n\nYou can clone this repository to modify and develop your own \n`Vivox Authorization Service` Extend app. Simply modify this project by defining your \nendpoints in `service.proto` file and implementing the handlers for those \nendpoints.\n\nIf you need to customize this app, please refer to our [Extend Service Extension](https://docs.accelbyte.io/gaming-services/services/extend/service-extension/) documentation.\n\n## Prerequisites\n\n1. Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:\n\n   a. Bash\n\n      - On Windows WSL2 or Linux Ubuntu:\n\n         ```\n         bash --version\n\n         GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)\n         ...\n         ```\n\n      - On macOS:\n\n         ```\n         bash --version\n\n         GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)\n         ...\n         ```\n\n   b. Make\n\n      - On Windows WSL2 or Linux Ubuntu:\n\n         To install from the Ubuntu repository, run `sudo apt update \u0026\u0026 sudo apt install make`.\n\n         ```\n         make --version\n\n         GNU Make 4.3\n         ...\n         ```\n\n      - On macOS:\n\n         ```\n         make --version\n\n         GNU Make 3.81\n         ...\n         ```\n\n   c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)\n   \n      - On Linux Ubuntu:\n\n         1. To install from the Ubuntu repository, run `sudo apt update \u0026\u0026 sudo apt install docker.io docker-buildx docker-compose-v2`.\n         2. Add your user to the `docker` group: `sudo usermod -aG docker $USER`.\n         3. Log out and log back in to allow the changes to take effect.\n\n      - On Windows or macOS:\n\n         Follow Docker's documentation on installing the Docker Desktop on [Windows](https://docs.docker.com/desktop/install/windows-install/) or [macOS](https://docs.docker.com/desktop/install/mac-install/).\n\n         ```\n         docker version\n\n         ...\n         Server: Docker Desktop\n            Engine:\n            Version:          24.0.5\n         ...\n         ```\n\n   d. Python 3.10\n\n      - On Linux Ubuntu:\n\n         To install from the Ubuntu repository, run `sudo apt update \u0026\u0026 sudo apt install python3 python3-venv`.\n\n      - On Windows or macOS:\n\n         Use the available installer [here](https://www.python.org/downloads/).\n\n         ```\n         python3 --version\n\n         Python 3.10.12\n         ```\n\n   e. [Postman](https://www.postman.com/)\n\n      - Use binary available [here](https://www.postman.com/downloads/)\n\n   f. [extend-helper-cli](https://github.com/AccelByte/extend-helper-cli)\n\n      - Use the available binary from [extend-helper-cli](https://github.com/AccelByte/extend-helper-cli/releases).\n\n   \u003e :exclamation: In macOS, you may use [Homebrew](https://brew.sh/) to easily install some of the tools above.\n\n2. Access to AGS environment.\n\n   a. Base URL:\n\n      - Sample URL for AGS Shared Cloud customers: `https://spaceshooter.prod.gamingservices.accelbyte.io`\n      - Sample URL for AGS Private Cloud customers:  `https://dev.accelbyte.io`\n\n   b. [Create a Game Namespace](https://docs.accelbyte.io/gaming-services/services/access/reference/namespaces/manage-your-namespaces/) if you don't have one yet. Keep the `Namespace ID`. Make sure this namespace is in active status.\n\n   c. [Create an OAuth Client](https://docs.accelbyte.io/gaming-services/services/access/authorization/manage-access-control-for-applications/#create-an-iam-client) \n      with confidential client type with the following permissions. Keep the \n      `Client ID` and `Client Secret`.\n\n      - For AGS Private Cloud customers:\n         - `ADMIN:ROLE [READ]` to validate access token and permissions\n         - `ADMIN:NAMESPACE:{namespace}:NAMESPACE [READ]` to validate access namespace        \n      - For AGS Shared Cloud customers:\n         - IAM -\u003e Roles (Read)\n         - Basic -\u003e Namespace (Read)\n\n3. Your Vivox configuration.\n   - Vivox application-specific issuer name\n   - Vivox domain name\n   - Vivox signing key\n\n## Setup\n\nTo be able to run this app, you will need to follow these setup steps.\n\n1. Create a docker compose `.env` file by copying the content of \n   [.env.template](.env.template) file.\n\n   \u003e :warning: **The host OS environment variables have higher precedence \n   compared to `.env` file variables**: If the variables in `.env` file do not \n   seem to take effect properly, check if there are host OS environment \n   variables with the same name. See documentation about \n   [docker compose environment variables precedence](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/) \n   for more details.\n\n2. Fill in the required environment variables in `.env` file as shown below.\n\n   ```\n   AB_BASE_URL='http://test.accelbyte.io'       # Your environment's domain Base URL\n   AB_CLIENT_ID='xxxxxxxxxx'                    # Client ID from the Prerequisites section\n   AB_CLIENT_SECRET='xxxxxxxxxx'                # Client Secret from the Prerequisites section\n   AB_NAMESPACE='xxxxxxxxxx'                    # Namespace ID from the Prerequisites section\n   PLUGIN_GRPC_SERVER_AUTH_ENABLED=true         # Enable or disable access token and permission validation\n   BASE_PATH='/vivoxauth'                       # The base path used for the app\n   VIVOX_ISSUER='xxxx'                          # Replace with your Vivox application-specific issuer name\n   VIVOX_DOMAIN='tla.vivox.com'                 # Replace with Vivox domain default to `tla.vivox.com`\n   VIVOX_SIGNING_KEY='xxxxxxx'                  # Replace with your Vivox signing key\n   ```\n \n   \u003e :exclamation: **In this app, PLUGIN_GRPC_SERVER_AUTH_ENABLED is `true` by default**: If it is set to `false`, the endpoint `permission.action` and `permission.resource`  validation will be disabled and the endpoint can be accessed without a valid access token. This option is provided for development purpose only.\n\n## Building\n\nTo build this app, use the following command.\n\n```shell\nmake build\n```\n\nThe build output will be available in `.output` directory.\n\n## Running\n\nTo (build and) run this app in a container, use the following command.\n\n```shell\ndocker compose up --build\n```\n\n## Testing\n\n### Unit Test\n\nThe unit test for the example included in this project is available in `src/AccelByte.Extend.Vivox.Authentication.Tests`.\nRun this command to execute unit test.\n\n```shell\nmake test\n```\n\n### Test in Local Development Environment\n\nThis app can be tested locally through the Swagger UI.\n\n1. Run this app by using the command below.\n\n   ```shell\n   docker compose up --build\n   ```\n\n2. If **PLUGIN_GRPC_SERVER_AUTH_ENABLED** is `true`: Get an access token to \n   be able to access the REST API service. \n   \n   To get a user access access token, you can use\n   [get-access-token.postman_collection.json](demo/get-access-token.postman_collection.json).\n   Import the Postman collection to your Postman workspace and create a \n   Postman environment containing the following variables.\n\n   - `AB_BASE_URL` For example, https://test.accelbyte.io\n   - `AB_CLIENT_ID` A confidential IAM OAuth client ID\n   - `AB_CLIENT_SECRET` The corresponding confidential IAM OAuth client secret\n   - `AB_USERNAME` The username or e-mail of the user\n   - `AB_PASSWORD` The corresponding user password\n\n   To get the user access token, open the `POST get-user-access-token` request in this \n   collection and click `Send`. If successful, you will get a `200 OK` response and \n   the user access token will be available in access_token property in the response \n   body. In the example below, the user token is `eyJhbGciOi...`.\n\n   ```json\n   {\n      \"access_token\": \"eyJhbGciOi...\",\n      ...\n   }\n   ```\n\n3. The REST API service can then be tested by opening Swagger UI at \n   `http://localhost:8000/vivoxauth/apidocs/`. Use this to create an API request \n   to try the endpoints.\n   \n   \u003e :info: Depending on the envar you set for `BASE_PATH`, the service will \n   have different service URL. This how it's the formatted \n   `http://localhost:8000/\u003cbase_path\u003e`\n\n   ![swagger-interface](./docs/images/swagger-interface.png)\n\n   To authorize Swagger UI, click on \"Authorize\" button on right side.\n\n   ![swagger-interface](./docs/images/swagger-authorize.png)\n\n   Popup will show, input \"Bearer \u003cuser access token\u003e\" in `Value` field for \n   `Bearer (apiKey)`. Then click \"Authorize\" to save the user's access token.\n\n### Test Observability\n\nTo be able to see the how the observability works in this template project in\nlocal development environment, there are few things that need be setup before \nperforming test.\n\n1. Uncomment loki logging driver in [docker-compose.yaml](docker-compose.yaml)\n\n   ```\n    # logging:\n    #   driver: loki\n    #   options:\n    #     loki-url: http://host.docker.internal:3100/loki/api/v1/push\n    #     mode: non-blocking\n    #     max-buffer-size: 4m\n    #     loki-retries: \"3\"\n   ```\n\n   \u003e :warning: **Make sure to install docker loki plugin beforehand**: Otherwise,\n   this app will not be able to run. This is required so that container \n   logs can flow to the `loki` service within `grpc-plugin-dependencies` stack. \n   Use this command to install docker loki plugin: \n   `docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions`.\n\n2. Clone and run [grpc-plugin-dependencies](https://github.com/AccelByte/grpc-plugin-dependencies) stack alongside this app. After this, Grafana \nwill be accessible at http://localhost:3000.\n\n   ```\n   git clone https://github.com/AccelByte/grpc-plugin-dependencies.git\n   cd grpc-plugin-dependencies\n   docker compose up\n   ```\n\n   \u003e :exclamation: More information about [grpc-plugin-dependencies](https://github.com/AccelByte/grpc-plugin-dependencies) \n   is available [here](https://github.com/AccelByte/grpc-plugin-dependencies/blob/main/README.md).\n\n3. Perform testing. For example, by following [Test in Local Development Environment](#test-in-local-development-environment).\n\n## Deploying\n\nAfter completing testing, the next step is to deploy your app to `AccelByte Gaming Services`.\n\n1. **Create an Extend Service Extension app**\n\n   If you do not already have one, create a new [Extend Service Extension App](https://docs.accelbyte.io/gaming-services/services/extend/service-extension/sample-use-cases/vivox-authentication-service/#create-the-extend-app).\n\n   On the **App Detail** page, take note of the following values.\n   - `Namespace`\n   - `App Name`\n\n   Under the **Environment Configuration** section, set the required secrets and/or variables.\n   - Secrets\n      - `AB_CLIENT_ID`\n      - `AB_CLIENT_SECRET`\n      - `VIVOX_SIGNING_KEY`\n   - Variables\n      - `VIVOX_ISSUER`\n      - `VIVOX_DOMAIN`\n\n2. **Build and Push the Container Image**\n\n   Use [extend-helper-cli](https://github.com/AccelByte/extend-helper-cli) to build and upload the container image.\n\n   ```\n   extend-helper-cli image-upload --login --namespace \u003cnamespace\u003e --app \u003capp-name\u003e --image-tag v0.0.1\n   ```\n\n   \u003e :warning: Run this command from your project directory. If you are in a different directory, add the `--work-dir \u003cproject-dir\u003e` option to specify the correct path.\n\n3. **Deploy the Image**\n   \n   On the **App Detail** page:\n   - Click **Image Version History**\n   - Select the image you just pushed\n   - Click **Deploy Image**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Fextend-vivox-authorization-service-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccelbyte%2Fextend-vivox-authorization-service-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Fextend-vivox-authorization-service-python/lists"}