HTTP Security¶

3.0

For simple use cases, Normal supports setting a single username and password for the administration console and API access, enforced using HTTP Basic. To enable this feature, set the CONSOLE_USERNAME and CONSOLE_PASSWORD environment variables on the Normal Framework container.

Hosting over SSL¶

To enable SSL within Normal, you will need to create a server certificate and key for each Normal container. Make sure settings like the Subject Name and Use are appropriate for web hosting, and reflect the hostname where users will access the container.

Once you have the certificate and key files, bind-mount them into the container by inserting them into the volumes section of your docker-compose file.

   volumes:
     - /path/to/server.key:/tailscale-certs/server.key:ro
     - /path/to/server.crt:/tailscale-certs/server.key:ro

Login with OIDC¶

When Normal is used with the Normal Portal, user authentication is handled via the portal. When users sign up there, their session is automatically also used with their Normal instances, so no additional configuration is required.

If the Normal Portal is not used, it is possible to configure the Normal container to authorize users using Microsoft Entra ID.

Set up Entra ID¶

Before starting, note that using Entra ID requires hosting the Normal container at a secure origin. Therefore, either configure SSL within the container; or place it behind a reverse proxy to perform SSL.

Next, create an application within your Entra Portal under "Entra ID" > "App Registrations", and create a new application. Set the redirect URI to the hostname users will visit the app at; or localhost (for testing).

After completing this configuration, enable authencation in your NF installation, set the following environment variables. Replace IDs in the Client ID with the client ID generated when configuring the App Registration; set the IDs in the Issuer and Authority settings to your Entra Tenant ID.

!! info You will need to retrieve the JWKS value from Azure B2C. In the App Registrations page of the Azure B2C console, select Endpoints and retrieve the "OpenID Connect Metadata Document". Within that document, locate the jwks_url field and use the result of retrieving that URL as the value of AUTH_JWKS_VALUE.

Use of OAuth Scopes¶

When set, the NF console will pass the requested scopes set using AUTH_SCOPES to the identity provider when the user requests login. These may be used within the provider flow to, for instance, conditionally grant access to particular sites. However, NF does not currently check for particular scopes in the JWT when granting access to resources.

Security Considerations¶

Some users of NF may wish to use wildcard URLs within the Redirect URL. This can lead to a number of vulnerabilities. See the Azure AD discussion of this topic for more detail on the attacks and mitigations in order to decide if they apply to your scenario.

The JWT must be validated in order to provide meaningful security. In this release, NF uses Envoy to perform the following checks:

• That the token is not expired (e.g., if an nbf key is present)
• That the signature validates against the statically configured JWKS key.
• That the audience (aud) matches AUTH_CLIENT_ID
• That the issuer (iss) matches AUTH_ISSUER)