Skip to content

Docker⚓︎

Prerequisites⚓︎

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 nextauth.mydomain.com and *.nextauth.mydomain.com 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.

Installation⚓︎

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 registry.git.nextauth.com

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 https://git.nextauth.com/core/docker.git nextauth

Next, replace all instances of nextauth.mydomain.com 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:

  • NEXTAUTH_NS_ROOT_API_KEY;
  • NEXTAUTH_MC_ROOT_API_KEY;
  • MYSQL_ROOT_PASSWORD;
  • MYSQL_PASSWORD.

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 nextauth.mydomain.com with the domain you configured for nextAuth usage.

./init.sh nextauth.mydomain.com

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 maps 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.

config
================================================================================
message_centers:
- id: E5b4Np7yk2swTmkhfCN-Qw
  public_key: RQx5GSWdWF1vGcT2Ndr29rh39StvBBq3fwsGfq38H_E
  public_key_box: czuzqADptmIw3EPfEIKk0M19h-nz8RLGEsGDGhoa0kA
  uri:
  - wss://nextauth.mydomain.com/mc/sigmai
================================================================================

docker-compose
================================================================================
NEXTAUTH_MC_SIGMAI_PUBLIC_KEY: RQx5GSWdWF1vGcT2Ndr29rh39StvBBq3fwsGfq38H_E
NEXTAUTH_MC_SIGMAI_SECRET_KEY: pF-GmQgEx6wMUzlxLJd0r1yi_dKPwLFvylSGfOUruC8
NEXTAUTH_MC_BOX_PUBLIC_KEY: czuzqADptmIw3EPfEIKk0M19h-nz8RLGEsGDGhoa0kA
NEXTAUTH_MC_BOX_SECRET_KEY: 25FsiCNGUo-WEBh5PQWC6cpv4zP9qJGvwo7SY7JMKmk
================================================================================

config
================================================================================
second_factor_servers:
- id: YpzBcSpffYJ9vJ-p6KFmQQ
  public_key: jQOM4emjOXo-n6cdVzMjgDl0pwH5YgyDVfZjd5Sy1x4
  uri:
  - wss://nextauth.mydomain.com/sfs/sigmai
================================================================================

docker-compose
================================================================================
NEXTAUTH_NS_DEFAULT_SFS_SERVER_ID: VuYHdiUpuLULk4KBXvM-Lw
NEXTAUTH_NS_DEFAULT_SFS_PUBLIC_KEY: IXOYORMe7RCv0p3ElTfZX7j8jhhiuZoSXdoCSX-aX4U
================================================================================

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

Info

While the NS and SFS have virtual servers, the MC has not. That is why for the MC, the keys are specified in the environment and the id is not kept by the MC (as it does not need it for its own operations). The message center's id is part of the Mobile SDK config, such that the Mobile SDK can tell the NS to use that MC for sending push messages to its accounts. The NS keeps a list of MC's it can connect with.

By specifying the default SFS in the NS's environment, every newly created virtual server in the NS will have that SFS associated to it.

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.

Tip

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.

Warning

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.

Tip

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 nextauth.mydomain.com 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 https://mc-api.nextauth.mydomain.com/api/v1/config/applications/

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.

Warning

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 nextauth.mydomain.com, 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 https://mc-api.nextauth.mydomain.com/api/v1/config/applications/

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
./upgrade.sh

Running the upgrade.sh script migrates the database(s), if applicable. Alternatively, you can configure, through environment variables, for the each of the NS, SFS, and MC containers to automatically migrate their database on starting the container.

NEXTAUTH_NS_DB_ENABLE_MIGRATIONS: "true"
NEXTAUTH_SFS_DB_ENABLE_MIGRATIONS: "true"
NEXTAUTH_MC_DB_ENABLE_MIGRATIONS: "true"

Troubleshooting⚓︎

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