Contact UsUE AuthUE StreamsCompany
Guides

Getting Started with Local Dev

Suggest Edits

Database

UE Auth is built with MongoDB as a dependency. For development purposes, we suggest you use docker for a quick test instance as follows:

docker run -p 27017:27017 mongo

First Run of Local Instance

Setup

You'll need to setup the config directory. Do not update .env_ci directly. Copy .env_ci to .env and then update the json files pertaining to your desired deployment or NODE_ENV configuration.

Add new deployment/env configurations as desired using the naming "env.NODE_ENV_NAME.json" (e.g., env.production.json, env.qa.json, etc.)

cp -R ./env_ci ./env

Within .env/env.dev.json, set the following

  • ALLOW_ROOT_CREATION = true
  • ROOT_EMAIL = [email protected]
  • ONE_TIME_PERSONAL_ROOT_CREATION_KEY = YOUR_ONE_TIME_SECRET
  • set other values as you like

Install, Test, and Run the Service

yarn test
yarn dev
  • yarn test will also install dependencies

Configure Root

You can do the following curl command in a tool such as Postman as well. NOTE, this is a one time setup action and is not represented in swagger.

curl -X POST "<http://localhost:3000/api/init>" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"password\":\"YOURPASSWORD\",\"setupCode\":\"YOUR_ONE_TIME_SECRET\"}"
  • Copy the resulting AuthGroup, Account, and Client data for future use
  • Within .env/env.dev.json set the following and restart
    • ALLOW_ROOT_CREATION = false
    • ONE_TIME_PERSONAL_ROOT_CREATION_KEY = ""
  • You will need to configure Root in any new environment setup

Validate OIDC and Access Swagger

Get Started with an AuthGroup

  1. Navigate to http://localhost:3000/swagger
  2. Access the group creation API (not shown in the UE Auth Commercial API Guide): http://localhost:3000/swagger#/Auth%20Groups/post_api_group
  3. Click "Try it out" and define the POST request object ensuring the required fields are defined:
{
  "name": "Your Group Name",
  "prettyName": "url_safe_name",
  "owner": "[email protected]",
  "locked": false,
  "primaryDomain": "https://example.com",
  "primaryEmail": "[email protected]"
}
  1. Make the request and take note of the response properties. One of them will be an initialAccessToken. Another property will be the securityExpiration, which is how long you have to create your account and activate the AuthGroup before it auto deletes.
  2. Access the Account creation API: http://localhost:3000/swagger#/Users/writeAccount
  3. Click the Authorization button and paste the initialAccessToken from step 4 into the bearer field
  4. Click "Try it out" and define the POST request object for the account. Make sure you use the same email address you used to define the Owner when you created your AuthGroup - [email protected]
{
  "username": "[email protected]",
  "email": "[email protected]",
  "generatePassword": true
}
  1. Make the request. This will create your account, activate your AuthGroup, provide a oAuth Client with client_id and client_secret, initialize the primary products, organizations and domains and finally associate you to those products so you have full Admin privileges.
  2. Access your well-known URL here: http://localhost:3000/url_safe_name/.well-known/openid-configuration

Lambda Deployment Options

UE Auth is designed to operate either as a Lambda Function or as a standalone Docker service. It should be noted that as a lambda function, there are no async operations that persist beyond a response from the function. The primary impact of this is with the console event emitter functionality, which defines and writes to standard out or to a configured event streaming plugin. When operating as a lambda function, it is possible that events may not be written to standard out or streamed as they occur if the service responds quickly and ends the session. In the future, an approach using Lambda Layers will be provided to allow for all events to be emitted without an impact to performance; however, for now, it is recommended that UE Auth only be used as a Lambda function in the following scenarios:

  • Non-production development and hosting
  • Internal usage without data audit requirements
  • Production usage without data audit requirements

If you wish to manually deploy UE Auth as a Lambda function, you can do so using the following approach.

  • Ensure you have your .env correctly configured. Let's assume we want to deploy a QA instance which pertains to json file env.qa.json
  • Ensure that Serverless is installed and configured to deploy to aws for your account
    • Note: serverless is installed as a dev dependency for the project, so you can also simply set your appropriate environment variables and use this install
yarn deploy --stage=qa
  • Or set stage to any other .env supported environment such as 'dev' or 'production'

Docker

UE Auth has a Docker registry as part of its GitHub project which you are free to pull from. If you wish to generate your own images, you can do so using the docker file in the project.

Plugins and UI Not Included

Keep in mind that the commercial solution for UE Auth has several plugins and systems configured. The open source version has the potential for these configurations but none are included beyond the code necessary to integrate. Additionally, UE Auth Open Source does not come with a User Interface. It is provided as the backend service ONLY.

Updated over 1 year ago