Skip to content

Deployment⚓︎

Login to the nextAuth Registry⚓︎

In order to pull the NS, SFS, and MC images, you will need to authenticate to the nextAuth Registry at registry.git.nextauth.com. This requires the credentials you received from nextAuth. Please contact support to request new credentials.

Setting up the Authentication Server⚓︎

Each of the nextAuth services should be deployed to your cluster, specifying the following environment variables in order to get started. If preferred, values holding secrets, such as the database connection strings, can also be read from a file by specifying the _FILE variant instead (e.g., NEXTAUTH_NS_DB_URI_FILE).

  • nextAuth Server
  • NEXTAUTH_NS_LOG_FORMAT
  • NEXTAUTH_NS_LOG_LEVEL
  • NEXTAUTH_NS_DB_URI
  • NEXTAUTH_NS_DB_ENABLE_MIGRATIONS
  • NEXTAUTH_NS_KV_URI
  • NEXTAUTH_NS_ROOT_API_KEY
  • NEXTAUTH_NS_LICENSE
  • NEXTAUTH_NS_DEFAULT_SIGMAI_URI
  • NEXTAUTH_NS_DEFAULT_WEBSOCKET_URI
  • Message Center
  • NEXTAUTH_MC_LOG_FORMAT
  • NEXTAUTH_MC_LOG_LEVEL
  • NEXTAUTH_MC_DB_URI
  • NEXTAUTH_MC_DB_ENABLE_MIGRATIONS
  • NEXTAUTH_MC_ROOT_API_KEY
  • Second Factor Server
  • NEXTAUTH_SFS_LOG_FORMAT
  • NEXTAUTH_SFS_LOG_LEVEL
  • NEXTAUTH_SFS_DB_URI
  • NEXTAUTH_SFS_DB_ENABLE_MIGRATIONS

Initialising the Authentication Server⚓︎

Before launching the Authentication Service, you need to initialise it. Run the following commands for the Message Center and Second Factor service respectively in order to generate additional required parameters.

mc config generate wss://nextauth.mydomain.com/mc/sigmai
sfs server create wss://nextauth.mydomain.com/sfs/sigmai

During this process, you will notice that the following two message blocks will be printed. Please replace the environment variables in the nextAuth Server and Message Center environments 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
================================================================================

When all services have been restarted, we can register the newly created Message Center with the nextAuth Server. This can be accomplished by setting the following environment variables, replacing the sample API key (LXbtnPK7dotjyhyOjqlw) with the value you configured for NEXTAUTH_MC_ROOT_API_KEY. If you've configured TLS for the gRPC transport of the Message Center, the insecure flag should also be cleared.

NEXTAUTH_NS_MC_URI: mc:9090
NEXTAUTH_NS_MC_ROOT_API_KEY: LXbtnPK7dotjyhyOjqlw
NEXTAUTH_NS_MC_INSECURE: "true"

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 it can be communicated to the NS.

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.

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.

Place the following JSON body in a file name application_android.json, 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.

{
  "platform": "android",
  "bundle_id": "",
  "name": "",
  "push_service": {
    "dialect": "fcm",
    "credentials": {
      "type": "",
      "project_id": "",
      "private_key_id": "",
      "private_key": "",
      "client_email": "",
      "client_id": "",
      "auth_uri": "",
      "token_uri": "",
      "auth_provider_x509_cert_url": "",
      "client_x509_cert_url": ""
    }
  }
}

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 @pplication_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 create the application_ios.json file starting from the template below, 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.

{
  "platform": "ios",
  "bundle_id": "",
  "name": "",
  "push_service": {
    "dialect": "apns",
    "credentials": {
      "auth_key": "",
      "key_id": "",
      "team_id": ""
    }
  }
}

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/