Nx Private Cloud User Authentication

There are 2 methods of authenticating users in Nx Private Cloud: single-admin user and GitHub OAuth2.

Why do users need access

While just adding an NxCloud access token to your monorepo give you distributed caching, the NxCloud web app gives you analytics about tasks running in your workspace, allows devs to easily inspect terminal output, and works seamlessly with our GitHub integration for your Pull Requests. Here is a video walkthrough of this.

By default, when you connect your token to a workspace on your NxCloud web app, all links and runs are private to only members of your organisation. This means that you'll either need to explicitly add members, or make your organisation public (which means anyone with access to your Private NxCloud instance will be able to see your runs). More details here.

Setting up a single admin user

If you just want to try out private cloud and set-up full membership management later, then the simplest option is to just set-up a single admin user. This option might also work for you if you are okay with making your organisation public to anyone that has access to your private cloud NxCloud instance.

While setting up your container you can pass it the ADMIN_PASSWORD environment variable. This will set-up a default admin user for you, which you can use to manage your workspace on the NxCloud web app.

Note: Even if you can make your organisation public, we still recommend setting up GitHub authentication and inviting more than 1 admin to your workspace, to reduce the chance of losing access to it.

Full Github OAuth set-up

Before creating your container, you'll need to create a GitHub OAuth app for your organisation.

Creating a GitHub OAuth app

From GitHub, click on your profile picture and chose "Settings":

Then "Developer settings" from the left-hand menu:

Then "OAuth Apps":

And create a new OAuth app:

Give it a name, and a homepage URL. The authorization callback is the important bit. It needs to be in this form:

[your-nx-cloud-url]/auth/github/callback

Once you create, keep a note of the Client ID:

And then generate a new client secret, and save it somewhere secure (we'll use it in a bit):

Connect your private cloud instance to your OAuth App

When setting up your private cloud, you can pass these two environment variables to it:

GITHUB_AUTH_CLIENT_ID=... GITHUB_AUTH_CLIENT_SECRET=...

Use the Client ID and Client Secret from when you created the app above.

Once that's done, you can either login with your admin user (see instructions below on how to log-in with admin), or directly via GitHub by hitting the "Log In" button:

You can then go to your organisation's members page and start inviting people based on their GitHub username:

When you invite someone, NxCloud will generate a unique invite URL, which you can send to that person directly.

GitHub Enterprise

If you are running an on-premise version of GitHub (Enterprise Server), you will need to configure one additional environment variable:

GITHUB_API_URL=https://custom-github-instance.com

This will point all auth endpoints to your GitHub server (rather the public one).

Note: the above environment variable, also helps with setting up the GitHub app integration, so you can have NxCloud build stats directly on your pull request. See full set-up instructions here.

Migrating from an admin-only set-up to GitHub auth

If you already have an admin user that manages an existing NxCloud workspace, you can still login, even after you set-up GitHub auth. You'll find the admin log-in button here:

Select an article to learn more about Nx Cloud