Vivox authentication service

Last updated on June 12, 2025

Overview​

The AccelByte Gaming Services (AGS) Extend Service Extension can be used to implement a Vivox authentication service, enabling seamless integration between AGS, Vivox, and game clients. This Vivox authentication service will generate signed Vivox tokens that game clients need to interact with Vivox. Each token is valid for 90 seconds, requiring game clients to regularly request a new token from the service.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:

    a. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)

    • On Linux Ubuntu:

      1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.
      2. Add your user to the docker group: sudo usermod -aG docker $USER.
      3. Log out and log back in to allow the changes to take effect.

    • On Windows or macOS:

      Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

      docker version

      ...
      Server: Docker Desktop
         Engine:
         Version:          24.0.5
      ...

    b. extend-helper-cli

  2. Access to the AGS Admin Portal environment.

    • Base URL: <your environment's domain URL>

      • Example for AGS Shared Cloud customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Private Cloud customer: https://dev.customer.accelbyte.io

    • Create a game namespace if you don't have one yet. Take note of the namespace ID.

    • Create an OAuth Client with confidential client type containing the following permissions:

      • For AGS Private Cloud customers:

        • ADMIN:ROLE [READ]
        • ADMIN:NAMESPACE:{namespace}:NAMESPACE [READ]

      • For AGS Shared Cloud customers:

        • IAM > Roles (Read)
        • Basic > Namespace (Read)

        Keep the Client ID and Client Secret.

  3. Your Vivox configuration.

    • Vivox application-specific issuer name
    • Vivox domain name
    • Vivox signing key

Clone the app repository​

git clone https://github.com/AccelByte/extend-vivox-authorization-service-csharp

Deploy in AGS​

Deploying an Extend app in AGS involves the following steps in the Admin Portal:

  1. Create the Extend app.
  2. Upload the Extend app.
  3. Configure the Extend app.
  4. Deploy the Extend app.

Create the Extend app​

  1. In the AGS Admin Portal, go to the namespace where you wish to create your Extend Override app.
  2. On the sidebar menu, under ADD-ONS, go to Extend > Service Extension.
  3. On the Service Extension page, click on the + Create New button.
  4. On the Create App form, provide a name and description (optional) for your Extend app.
  5. Click Create. Your new Extend app is added to the Service Extension app list.

Upload the Extend app​

  1. Set up an IAM client for extend-helper-cli. Create an IAM client with client type confidential and assign the required permissions listed below. Keep a copy of the Client ID and Client Secret.

    • For AGS Private Cloud customers:
      • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
      • ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ]
    • For AGS Shared Cloud customers:
      • Extend > Extend app image repository access (Read)
      • Extend > App (Read)

  2. Export the required environment variables, then build and upload the Extend app container image to AGS using extend-helper-cli.

    • Ensure <project-dir> points to your Extend app project directory
    • The values for <namespace> and <app-name> can be found on the App Detail page of your Extend app
    • Use an appropriate image tag e.g. v0.0.1
    # Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
    export AB_BASE_URL='https://xxxxxxxxxx'
    # Client ID of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_ID='xxxxxxxxxx'     
    # Client Secret of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_SECRET='xxxxxxxxxx'

    ./extend-helper-cli-linux_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1
    info
    • We recommend running the above commands in a separate terminal and from a different working directory than the Extend app project. This helps prevent the extend-helper-cli from inadvertently using environment variables intended for the Extend app.
    • If you encounter the following error, see Troubleshooting: Docker login fails for resolution steps.
      Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

    If your images are successfully uploaded, you will see an image with version v0.0.1 on the Image Version History page.

    image history in AGS Admin Portal

Configure the Extend app​

Before deploying the uploaded Extend app, you must configure the environment variables required by the app. In the app's details page, set the following environment variables with the values prepared in the Prerequisites section.

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
  • VIVOX_ISSUER
  • VIVOX_DOMAIN
  • VIVOX_SIGNING_KEY

Deploy the Extend app​

To deploy the Extend app, click Deploy Latest Image. Wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.

Run sample game client​

AccelByte provides you a sample game client to try Vivox authentication service. Follow these steps:

  1. Clone the project.

    git clone https://github.com/AccelByte/extend-vivox-authorization-sample-game-unreal

  2. Configure the AGS SDK for Unreal. Follow the steps in the Configure the AGS Game SDK for the IAM client section in the Install the AGS Game SDK guide.

  3. Configure the Vivox Unreal SDK.

    1. Set the values for VIVOX_VOICE_SERVER, VIVOX_VOICE_DOMAIN, VIVOX_ISSUER in the VivoxGameInstance.cpp file with values that are found in the Vivox Credentials in your Unreal Dashboard project.
    2. Set the value for VIVOX_TOKEN_PROVIDER_URL in the VivoxTokenProvider.cpp
    3. Locate and modify Token Provider Url field and Inspector field.

  4. Open the project (Client/ShooterGame.uproject) in your IDE.

  5. Build and package the for Windows (64-bit).

  6. Launch one or more instances of the build. The executable name should be ShooterGame.exe.

  7. Have one client host and others join.

Next step​

If you need to customize this Vivox authentication service to better fit your requirements, you may refer to this guide.

Last updated on

On this page