Running it · Chapter 15

Signing in with authentik, Entra ID and a second factor.

nexcrate has one account, the operator's, and signs people in with a user name and a password out of the box. That is enough at home. If you already run a sign-in service, you can hang nexcrate on it: authentik, Microsoft Entra ID, Keycloak, Authelia or Pocket ID, several at once. This chapter shows how to set up a provider, link your account, switch off the password and get back in when the provider fails.

Where things are

• “Settings › System › Sign-in” has the switch “Sign-in with a password”, the “Public address”, the list of “Sign-in providers” and the card “authentik in one step”.
• “Settings › System › Account” has “Sign-in providers” for linking, the “Second factor”, “Change password” and “Logged-in devices”.

First, the public address

After signing in, a provider sends the browser back to an address of nexcrate. That is the “Public address”, the one you reach nexcrate at in the browser, with the sub path if there is one. nexcrate never registers a redirect address that it only guessed. If you have not set an address yet, the card suggests the one you are using right now. “Use it and set up” takes it and sets up authentik with it at once, “Use it only” just keeps it. Instead of the interface you can also set it with the environment variable NEXCRATE_PUBLIC_URL, which applies as long as the interface names none. If nexcrate runs behind a proxy, see below.

authentik in one step

1. Create a token in authentik

   In authentik create an API token that may create applications.

2. Enter the address and the token

   On the card “authentik in one step” enter the address under “Address of authentik” and the token under “API token”. Click “Set up”. This can take up to 20 seconds.

3. Watch

   nexcrate creates in authentik, one after the other, what it needs: the signing key, the mappings for name and address, the provider and the application. Then it fills in its own settings and binds the application to the account that owns the token. That way authentik lets in only you. Each step shows on the card, and a failure says why.

nexcrate uses the token for this setup only and does not store it. If you would rather not hand out a token, choose “Download blueprint instead”, apply the blueprint in authentik and enter client ID and secret in the form. The provider then appears in the list as “set up through authentik” and gets a button on the sign-in page.

Settings › System › Sign-in

Other providers by hand

For Keycloak, Authelia, Pocket ID, Microsoft Entra ID and any other provider that speaks OpenID Connect, click “Add a provider”. You enter:

• “Name on the button” and “Short name”. The short name is part of the redirect address and cannot be changed later.
• “Issuer”, “Client ID” and “Client secret” from your provider.
• “Redirect address for the provider” is shown by the form itself. It has the form /api/oidc/<short name>/callback behind the public address, and you enter it at the provider.
• “The provider checks the second factor itself” decides whether nexcrate still asks for its own code after signing in through this provider.

The issuer looks like this for authentik and for Microsoft Entra ID. For several Entra tenants common and organizations work, too. Entra accepts only https redirect addresses, localhost aside, and sends the email address only as the optional claim email.

https://auth.example.com/application/o/<slug>/
https://login.microsoftonline.com/TENANT-ID/v2.0

Linking your account

1. Click “Link”

   Open “Settings › System › Account”. Under “Sign-in providers” each active provider is listed as “Not linked”. Click “Link”.

2. Confirm the password

   nexcrate asks once for the nexcrate password. That proves it is you.

3. Sign in at the provider

   nexcrate sends you to the provider. You sign in there and land back in the settings with “Your account is now linked to …”.

For each provider only this one identity opens nexcrate, and nexcrate turns every other away, however the provider is set up. There stays one account, linked to as many providers as you like. nexcrate never matches by email address, only by the identity you linked. “Unlink” removes a link. The last one stays as long as the account signs in only through that provider.

Switching off the password, and the emergency switch

Once your account is linked to an active provider, “Sign-in with a password” can be switched off. Before that it cannot. From then on you only get in through a provider. If the last provider goes, the sign-in with a password opens again by itself. If a provider has only failed, for example because its server is down, the emergency switch helps: put NEXCRATE_PASSWORD_LOGIN=1 in the compose file and restart nexcrate. That opens the password again whatever the switch says, and the page points it out as long as it is set. Afterwards you take the line out again. Whether the password then stays open is up to the switch “Sign-in with a password” again, so switch it on if you want to keep it.

    environment:
      NEXCRATE_PASSWORD_LOGIN: "1"

The second factor

Under “Settings › System › Account” the “Second factor” asks, after the password, for a code from an authenticator app such as Aegis, 2FAS or your password manager.

1. Switch on

   Click “Switch on”, scan the QR code or type in the key, enter the password and a code from the app and confirm.

2. Keep the recovery codes

   nexcrate shows eight codes that appear only now. Each one opens nexcrate exactly once if the phone is missing. “Save as a file” stores them, keep them apart from the phone.

If you sign in through a provider, its second factor applies as long as “The provider checks the second factor itself” is on. That is the default. If you have lost the phone and the codes, only the server helps: docker exec -it nexcrate python -m app.cli reset-second-factor switches the second factor off. A forgotten password is reset by docker exec -it nexcrate python -m app.cli reset-password. Both commands run on the server, not in the browser.

Behind a proxy

If a reverse proxy ends the TLS, nexcrate itself sees only http. It believes the header X-Forwarded-Proto only from the addresses in FORWARDED_ALLOW_IPS, and that list is empty out of the box, so it believes nobody. The redirect address is then built with http, and the provider usually does not accept it. Enter the address your proxy connects from, for example the gateway of the Docker network. A proxy on the same machine with host networking needs 127.0.0.1. nexcrate takes the rightmost value, the one your proxy wrote. The card warns you if the server sees a different scheme from your browser.

If the public address changes later, nexcrate asks first when authentik or a provider entered by hand still knows the old redirect address. For authentik you then run “Set up” once more with a token, for the others you enter the new address yourself.