Skip to content



You will need a Linux server with Docker and Docker Compose installed. Please consult the Docker and Docker Compose installation guides for further details.

Preferably, the server should be reachable over the internet. We strongly recommend setting up wildcard DNS records (e.g., configure and * to point to the IP address of your Authentication Server). Note that when running local tests, the mobile device you use for authentication needs to be able to reach this local server.


Login to the nextAuth Docker Registry⚓︎

Run the following command as root on the shell of your server to login to the nextAuth Docker Registry. This registry contains the images of the NS, SFS, and MC for local installation.

docker login

You will need to enter the credentials you received from nextAuth. Please contact support to request new credentials.

Set up Docker Compose⚓︎

First, clone our reference Docker Compose configuration by running the following command in a well-known location (e.g., your home directory or /opt/docker).

git clone nextauth

Next, replace all instances of in docker-compose.yml and traefik/traefik.yml with the domain that you configured for nextAuth usage. Furthermore, it is important that you update the NEXTAUTH_NS_LICENSE environment variable with the license issued to you by nextAuth.

Finally, we recommend revising the following environment variables with your own randomly generated values before initialising the Authentication Server:


Do not forget to also update the MySQL password in the NEXTAUTH_MC_DB_URI, NEXTAUTH_NS_DB_URI, and NEXTAUTH_SFS_DB_URI. Similarly, the NEXTAUTH_ROOT_APIKEY variable should be equal to the newly-generated value for NEXTAUTH_NS_ROOT_API_KEY.

Initialising the Authentication Server⚓︎

Before launching the Authentication Service, you need to initialise it. Run the following command in the same folder as your docker-compose.yml, again replacing with the domain you configured for nextAuth usage.


During this initialisation process, you will notice that the following two message blocks will be printed. Please replace the environment variables in the /services/mc/environment and /services/ns/environment hashes in your docker-compose.yml with the values listed in the docker-compose blocks. Finally, join the two config sections in a single file named config.yml, and send this file to your nextAuth contact.

- id: E5b4Np7yk2swTmkhfCN-Qw
  public_key: RQx5GSWdWF1vGcT2Ndr29rh39StvBBq3fwsGfq38H_E
  public_key_box: czuzqADptmIw3EPfEIKk0M19h-nz8RLGEsGDGhoa0kA
  - wss://

- id: YpzBcSpffYJ9vJ-p6KFmQQ
  public_key: jQOM4emjOXo-n6cdVzMjgDl0pwH5YgyDVfZjd5Sy1x4
  - wss://


Once you have completed these steps, run docker-compose up -d to restart all containers with their updated configuration values. When all containers are online again, we can register the newly created Message Center with the nextAuth Server. This can be accomplished by running the following command, replacing the sample Server ID (E5b4Np7yk2swTmkhfCN) with the one generated above and the sample API key (LXbtnPK7dotjyhyOjqlw) with the value you configured for NEXTAUTH_MC_ROOT_API_KEY.

docker-compose run --rm ns mc create --server-id=E5b4Np7yk2swTmkhfCN --api-key=LXbtnPK7dotjyhyOjqlw --uri=mc:9090

Configuring the Message Center (Optional)⚓︎

While the MC will be running after completing the Authentication Server initialisation, it will not have any applications or push service accounts associated with it. In order to do so, take a look at application_android.json and application_ios.json in the init/json folder of the repository you cloned at the start of the installation process.


The bundle_id field in the application_android.json and application_ios.json files is referred to as Application ID on Android and is typically of the form com.nexauth.authenticator. Apple also refers to this value as the App ID in the Developer portal and will generally be formatted as com.nextauth.Authenticator.

While the bundle_ids must match the values configured for your apps, the name value in application_android.json and application_ios.json is just for your own reference.


If you have multiple apps that use this Message Center, you need to do this for every bundle_id. Note that this also applies if you have multiple build flavours of your app. On Android, this is usually done by adding a suffix to your application id, e.g. com.nexauth.authenticator.beta. On iOS, this is usually done by adding a prefix to your bundle id, e.g. com.nextauth.beta.Authenticator (you will need the suffix for the Notification Service app extension). Take care to specify the Bundle ID of the app and not that of the Notification Service app extension.

Firebase Cloud Messaging⚓︎

In order to send push notifications to an Android app, you will need to obtain a Firebase service account from the Firebase Console. You can do so by following the process described here by Google. At the end of this process, you will have downloaded a JSON file containing the generated private key.


You can use the same Firebase service account for all your apps. The coupling between your app and firebase instance happens inside your app through the inclusion of the google-services.json file. Your app does not need to be distributed through the Google Play Store for this to work.

Coming back to the application_android.json file, fill out the bundle_id and name fields with the relevant values for the app you want to register with the MC. Next. copy the contents from the service account private key file you downloaded in the previous step to the /push_service/credentials field.

Finally, you will need to call the MC API to register this application and the corresponding push service. To this end, run the following cURL command, replacing the sample API key (LXbtnPK7dotjyhyOjqlw) with the value you configured for NEXTAUTH_MC_ROOT_API_KEY, and with the domain you set up for nextAuth usage.

curl -X POST -H "Content-Type: application/json" -H "X-Api-Key: LXbtnPK7dotjyhyOjqlw" -d @init/json/application_android.json

Apple Push Notification service (APNs)⚓︎

Similarly, delivering push notification to iOS devices requires access to the Apple Push Notification service (APNs). To this end, obtain an authentication token signing key from the Apple Developer portal by following the steps described here, obtaining a file named AuthKey_{KEY ID}.p8. Finally, retrieve your Team ID from the Membership tab of the Developer Portal, as you will need it in the following.

We can now complete the application_ios.json file, again starting with the bundle_id and name fields. Next, fill out the /push_service/credentials hash with the information we obtained from Apple. As you will notice, the AuthKey_{KEY ID}.p8 file contains a PEM-encoded private key, which you can add to the JSON file.


In order to ensure that key will parse correctly, join the lines of the PEM file to a single string using \ns.

The last step is to call the MC API with the following cURL command to register the configured app and push service. Take care to replace the sample API key and, respectively with the value you configured for NEXTAUTH_MC_ROOT_API_KEY and the domain you set up for nextAuth usage.

curl -X POST -H "Content-Type: application/json" -H "X-Api-Key: LXbtnPK7dotjyhyOjqlw" -d @init/json/application_ios.json

Upgrading Your Authentication Server⚓︎

You can upgrade your Authentication Server to the latest version by running the following commands in the same folder as your docker-compose.yml.

docker-compose pull


Accessing the Logs⚓︎

In order to access the logs of the NS, SFS, and MC containers, execute one of the following command in the folder containing your docker-compose.yml.

docker-compose logs -f nextauth ns
docker-compose logs -f nextauth sfs
docker-compose logs -f nextauth mc