Connecting to Digital Person

There are two options to connect your project to your custom UI, using web API keys or you could use a token server. The easier and more secure option is using the web API keys method.

Using API Keys

API Keys are unique identifiers used to help authenticate connection requests to a particular project. This section describes high-level steps to how to create, and use your API Key for the Soul Machines platform.

1. Create and deploy your project from Digital DNA Studio > New Project.

2. Create a web API key and assign it to your project from settings cog > API Keys > Create API Key.

3. To connect to your UI, pass in your web API key as an option when constructing your scene.

Note: You should revoke an API key immediately if it becomes inactive, lost, or compromised.

Using Token Server

If you have an orchestration server, you should use the advanced connection configuration on the Project Summary page. This method leverages JSON Web Tokens (JWTs) for establishing secure, unique sessions between your users and the Digital Person. Template code is available on request, which runs an Express (Node.js) server that generates and issues the necessary JWTs. Alternatively any valid method of serving JWTs is supported—Soul Machines is agnostic to your backend language and framework.

The token server/issuer must be hosted by your organization or a third party provider.

Running Token Server Sample

The provided sample generates and issues the necessary JWTs then passes it to Soul Machines servers (via Web SDK) for authentication.

Local

• For a more detailed installation guide see the “readme” file included with the sample code.
• To skip local certificate checks in Chrome navigate to chrome://flags/#allow-insecure-localhost and enable “Allow invalid certificates for resources loaded from localhost”

1. Unzip project to selected location.

2. Open new terminal (or cmd) session, navigate to app root directory.

3. Run npm install.

4. Create new subdirectory called “certs” - e.g. on Mac “mkdir certs”.

5. Change to “certs” directory and run following script to generate local certifications: Mac: ..scripts/generate-ssl.sh localhost

6. Navigate back to app root directory.

7. Rename environment variables file “env.template” to “.env”

8. Open the “.env” file and make the following changes:

   1. SESSION_SERVER= dh.soulmachines.cloud, this value will be the same for all Digital DNA deployed Digital People
   2. JWT_PUBLIC_KEY= get “KEY NAME” from project summary page in Digital DNA Studio
   3. JWT_PRIVATE_KEY = get “PRIVATE NAME” from project summary page in Digital DNA Studio
   4. PRODUCTION_PERSONA = false (for Development environments)

Note: Leave all other settings in this file as is.

9. From app root directory run: “npm run dev”. You should see the following message:

   [nodemon] starting `ts-node ./src/server.ts`
   Express server listening on port 5000

10. Test by navigating to the following: https://{your app url}/auth/authorize.

    You should see a response similar to the following:

    {
     "success":true,
     "url":"wss://dh.soulmachines.cloud", 
     "jwt":"eyJhbGciOiJIUzI1NiIs...InR5cCI6IkpXVCJ9"
    }

Google Cloud

• Token server can be deployed to any public cloud provider that supports Express Node.js
• The following steps describe one approach to using continuous deployment to deploy the Token App to Google Cloud

1. Create in project in Google Cloud Platform (GCP).

2. Enable Cloud Build API.

3. Enable App Engine Admin API.

4. Enable Service Account permission for App Engine service: (Go to Cloud Build, under services > Settings > App Engine > Enable)

5. Create a build file for the project (cloudbuild.yaml) in your code repository (e.g. github, bitbucket, etc). Add the following text to this file:

     steps:
     - name: node
     entrypoint: npm
     args: ['install']
     - name: node
     entrypoint: npm
     args: ["run", "create-env"]
     env:
     - 'SESSION_SERVER=${_SESSION_SERVER}'
     - 'JWT_PUBLIC_KEY=${_JWT_PUBLIC_KEY}'
     - 'JWT_PRIVATE_KEY=${_JWT_PRIVATE_KEY}'
     - 'UI_SERVER=${_UI_SERVER}'
     - name: "gcr.io/cloud-builders/gcloud"
     args: ["app", "deploy"]
     timeout: "1600s"

6. Create app.yaml in your code repository. Add the following to this file:

   - runtime: nodejs10
   handlers:
     - url: /.*
       secure: always
       redirect_http_response_code: 301   
       script: auto

7. Create new App Engine for project:

   a. Go to App Engine and click Create Application.

   b. Select region for App deployment, then Create App.

   c. Set Language = “Node.js”.

   d. Set Environment=Standard.

   e. Click Next.

8. Create new Cloud Build > Trigger for GCP project:

   1. Follow steps to connect trigger to Token source code repo:

      a. Install Google Cloud Build if prompted

      b. Create repo token if required

   2. Click Create push Trigger. After trigger is created you should see the Trigger list page.

   3. Edit the trigger and make the following changes:

      a. Build configuration > File Type > select Cloud Build configuration type.

      b. Click ADD VARIABLE and add the following variables and values: JWT_PRIVATE_KEY, JWT_PUBLIC_KEY, SESSION_SERVER, UI_SERVER

   4. Run Trigger – This will build then deploy the code.

   5. Go to Trigger History page to monitor deployment progress. If the build succeeds, a green light appears next to build.

9. Navigate to https://{your app url}/auth/authorize to confirm a successful deployment.

Standard JWT Fields

The following table describes the standard JWT fields.

Field	Example	Description
sm-control	wss://{your app url}:8080	Your Orchestration Server URL. The sm-control field in your JWT is required to point to your Orchestration server. The Soul Machines video host uses this value to make an outbound WebSocket connection to the specified address. It is also possible to make this a localhost address so you can just have a locally running Orchestration server which is useful for debugging, etc.  To do this, you need to have the sm-control-via-browser flag set to True in the JWT, and the production flag set to False on the server. Once the connection is established, messages flow back and forth over the WebSocket. The protocol for these messages is the same as the protocol which underlies the Web SDK, but some extra messages are permitted (mainly startSpeaking).
sm-session-server		The URL of the server where your Digital Person is hosted. For a Digital DNA Studio deployed Digital Person, you can find this URL on the Project Management page, under the Connection Config (Advanced) > Digital Person Server field. For customized environments, this is provided by your Soul Machines Solutions Architect. This is a mandatory field.
sm-control-via-browser		Flag to permit control via browser. Only allowed in Development environments.
sm-control-cookie-header		Field is set as Cookie header on the Orchestration server connection. This can be useful when working with components like load balancers which can act on headers.
iss	sm-abcdef123456789	Issuer – the assigned ID for your JWT.
nbf		Not before timestamp. The time of issue with a small leeway for clock skew.
exp		Expires at timestamp.
iat		Issued at timestamp.

Custom JWT Fields

You may add any other fields you wish to your JWT, for example a custom session ID, which is passed on to your backend Orchestration server. Custom JWT fields enable you to set up a shared state between your backend and your frontend.

Notes:

• You must avoid the sm- prefix in field names.
• To prevent tampering with the token, the JWT must be signed with your private key that was pre-shared with you by Soul Machines.