Nuon BYOC Requirements - Nuon documentation

Before installing Nuon BYOC, you will need to prepare the following dependencies.

Cloud Account

You will need an AWS or GCP account to run Nuon BYOC in. The installation process is the same on both platforms. Platform-specific architecture is covered in Architecture.

If you are hosting Nuon BYOC on GCP, a public S3 bucket is still required to support CloudFormation Quick create links for customer AWS install stacks. By default, we will provision a bucket for you, but if you would like to own the bucket yourself, you will need an AWS account.

DNS

Root DNS

In order to serve Nuon BYOC at your own domain — for example, nuon.my-domain.com — you will need a DNS zone to place the records in.

Before creating the install, create the DNS zone my-domain.com in your preferred hosting provider, if it does not already exist.

While provisioning the install stack, provide nuon.my-domain.com as the value for the Root Domain input.

Once Nuon BYOC has fully provisioned, the nameservers for the install will be available in the outputs.

Create an NS record named nuon.my-domain.com using the nameserver values from the install outputs.

Once propagation is complete, your Nuon BYOC install will be available at nuon.my-domain.com.

Nuon will provision the following subdomains under nuon.my-domain.com. Only the runner API needs to be public. The rest can be private to your internal network.

Subdomain	Service	Public
app	The vendor dashboard
api	The control plane API, used by the Vendor Dashboard and the CLI
admin	The admin API. Exposes functionality for administration of the control plane
runner	The API used by runners to communicate with the control plane
slack	The Slack integration API (optional)

The Nuon Dashboard uses cookies for authentication, and they will be shared on all subdomains of the provided root domain. We strongly recommend creating a Nuon-specific subdomain to avoid leaking auth cookies.

Install Delegation DNS (Optional)

If you don’t want your customers to have to set up DNS when installing your app, you can configure DNS delegation. A subdomain is provisioned for each install under a subdomain you control. Nuon Cloud, for example, creates a subdomain for each install at <install_id>.nuon.run by default. For details, see Custom Domains.

GitHub App

Create a GitHub App so Nuon can access your GitHub org. This allows it to access private repos and receive webhook events.

Go to GitHub App Settings and click New GitHub App.

Configure the app with the following settings.

Setting	Value
GitHub App name	Choose any name (e.g., “Nuon BYOC”)
Homepage URL	`https://app.<your-root-domain>`
Setup URL	`https://app.<your-root-domain>/connect`
Redirect on Update	Checked
Webhook	Unchecked

Configure the following permissions.Repository permissions

Permission	Access
Contents	Read-only
Metadata	Read-only
Pull requests	Read and write

Organization permissions

Permission	Access
Webhooks	Read and write

The Webhooks permission lets Nuon register a webhook to trigger app branch runs. If you do not want to grant this access, you can instead trigger runs from your own CI using the Nuon GitHub Action.

Under “Where can this GitHub App be installed?”, select Only on this account (unless you need to access repos in other GitHub organizations).

Click Create GitHub App.

After creation, scroll to the bottom of the page and click Generate a private key. Save the PEM file to provide as a secret.

The GitHub App PEM key must be base64 encoded to preserve newlines.

base64 -i your-github-app-key.pem

Save the App ID and Client ID from the app settings page to provide as inputs.

Identity Provider

Configure your preferred identity provider to control user access to Nuon.

Google

To use Google as your IdP, set up an OAuth client in the Google Cloud Console.

Go to the Google Cloud Console and create or select a project.

Navigate to APIs & Services > Credentials.

Click Create Credentials > OAuth client ID and select Web application as the application type.

Configure the OAuth client.

Setting	Value
Name	`Nuon BYOC` (or any name)
Authorized JavaScript origins	`https://auth.<your-root-domain>`
Authorized redirect URIs	`https://auth.<your-root-domain>/auth`

Click Create.

After creation, save the Client ID to provide as an input, and the Client Secret to provide as a secret. You will also need the Issuer URL for Google. It is always https://accounts.google.com.

Okta

To use Okta as your IdP, set up an OIDC Application in Okta.

In the Okta Admin Console, navigate to Applications and create a new OIDC application.

For Sign-in method, select OIDC - OpenID Connect
For Application type, select Web Application

Set the Sign In Redirect to https://auth.<your-root-domain>/auth

Set Trusted Origins to <your-root-domain>

Click Save.

After creation, save the Issuer URL and Client ID to provide as an input, and the Secret to provide as a secret.

Auth0 (Legacy)

This section does not document using Auth0 as a regular auth provider. Nuon BYOC previously required Auth0 for authentication. This is no longer the case. This documentation is retained for anyone still using the legacy Auth0 integration.New Nuon BYOC installs should use one of the IdP integrations documented above.

To use Auth0 for authentication, you will need to configure an API, applications, and a custom action in your Auth0 tenant. Nuon provides a Terraform module to automate Auth0 configuration. We recommend this over manual configuration. Apply the following Terraform to use it.

module "byoc_auth0" {
  source = "github.com/nuonco/byoc-auth0"
  # Your Auth0 tenant domain
  auth0_domain = "your-tenant.auth0.com"
  # The root domain for your BYOC install
  public_domain = "<your-root-domain>"
  # Your Nuon install ID
  install_id   = "<your-install-id>"
  install_name = "<your-install-name>"
}

After applying, the module outputs the values you will need for the install inputs. If you would prefer to configure Auth0 manually, follow the steps below.

Add an action to enrich the access token with the user’s email.

Go to Actions > Library in your Auth0 dashboard
Click Create Action > Build from scratch
Name it AddScope and select the latest runtime
Replace the code with:

exports.onExecutePostLogin = async (event, api) => {
  const email = event.user.email;
  api.accessToken.setCustomClaim(`email`, email);
};

Deploy the action
Go to Actions > Triggers > Post Login
Drag the AddScope action into the flow and save

Create an API with the following settings.

Setting	Value
Name	`API Gateway <your-install-id>`
Identifier	`api.<your-root-domain>`
Maximum Access Token Lifetime	`2592000`
Implicit/Hybrid Flow Access Token Lifetime	`86400`
Allow Skipping User Consent	`true`

The Identifier must match your API URL exactly. It cannot be changed after creation.

Create a Single Page Application for the Dashboard UI.

Setting	Value
Name	`Nuon App - <your-install-name>`
Allowed Callback URLs	`https://app.<your-root-domain>/api/auth/callback`
Allowed Logout URLs	`https://app.<your-root-domain>`
Allowed Web Origins	`https://app.<your-root-domain>`
Allow Cross-Origin Authentication	`true`
Maximum Refresh Token Lifetime	`31557600`
Allow Refresh Token Rotation	`true`
Rotation Overlap Period	`0`

Create a Native Application for CLI authentication.

Setting	Value
Name	`Nuon CTL API - <your-install-name>`
Description	`For Nuon BYOC Install <your-install-id>`
Allow Cross-Origin Authentication	`true`
Device Code (Advanced > Grant Types)	Checked

​Cloud Account

​DNS

​Root DNS

​Install Delegation DNS (Optional)

​GitHub App

​Identity Provider

​Google

​Okta

​Auth0 (Legacy)

Cloud Account

DNS

Root DNS

Install Delegation DNS (Optional)

GitHub App

Identity Provider

Google

Okta

Auth0 (Legacy)