Configuring Authentication¶

Fine Grained Access Tokens¶

3.4

When the environment variables CONSOLE_USERNAME, CONSOLE_PASSWORD, and TOKEN_SIGNING_SECRET are defined, NF will require authentication for all external API requests.

Creating a Token¶

In order to create access tokens, you must first create an API Key from the Admin Console (settings => authorization => api keys). Select the specific permissions you want this API key to have. After creating, copy and secure the client secret, as you will not be able to see it again.

You can then obtain an Access Token using the /api/v1/auth/token endpoint like so:

curl 'http://localhost/api/v1/auth/token' \
--data '{
    "client_id": "<client-id>",
    "client_secret": "<client-secret>",
    "grant_type": "client_credentials"
}

A successful request will return a response containing the access token, as well as an expiration time (in seconds).

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZXMiOlsibm9ybWFsZ3cucGxhdGZvcm0udjEucmVhZG9ubHkiXSwiYXVkIjoibmYtIiwiZXhwIjoxNzEyNjAwNjg3LCJqdGkiOiIwMTY0YzcyNC0xMGE2LTRlZGMtOTMxZi01N2QyM2JjODZkZWMiLCJpYXQiOjE3MTI1OTcwODcsInN1YiI6Ik8yRTAxRlZ1aVNXVjA4aTEifQ.u_R6CjTGun0RAB78tGlIH1JrWQSp-Rv5Q1ETLgg-o8U",
    "tokenType": "Bearer",
    "expiresIn": "3600"
}

Then use the Access Token as a Bearer Token to Authenticate requests like so:

curl 'https://localhost/api/v1/point/points' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZXMiOlsibm9ybWFsZ3cucGxhdGZvcm0udjEucmVhZG9ubHkiXSwiYXVkIjoibmYtIiwiZXhwIjoxNzEyNjAwNjg3LCJqdGkiOiIwMTY0YzcyNC0xMGE2LTRlZGMtOTMxZi01N2QyM2JjODZkZWMiLCJpYXQiOjE3MTI1OTcwODcsInN1YiI6Ik8yRTAxRlZ1aVNXVjA4aTEifQ.u_R6CjTGun0RAB78tGlIH1JrWQSp-Rv5Q1ETLgg-o8U'

Securing Applications¶

By default, NF Applications do not require authentication, however it is a good practice to only give the application a minimum level of access that is required. You can access this configuration through the Application Configuration Advanced Settings page. Select the appopriate access levels and save the configuration.

No further steps are required, as the NF applications framework will now handle retreiving and refreshing access tokens, as well as integrating these tokens into any existing API calls in the application.

Examples¶

See more authentication examples in the examples in the nf-sdk project.

HTTP Login¶

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.

Login with OIDC¶

1.1 Normal Framework supports coarse-grained authentication for access control using JWTs. When enabled, each request must carry a valid bearer-token granting access to its APIs. Additionally, NF supports providing an end-user login flow for the console using Auth0 or Azure AD B2C.

Set Up Auth0¶

Before configuring NF, create a new Auth0 Application as type "Single Page Application". You will need to collect the following values from the Auth0 console:

• Domain
• Client ID
• JSON Web Key Set. This is found in "Advanced Settings", "Endpoints" Tab, "OAuth" section.

You must also configure the application Callback URLs and Allowed Web Origins to include the URL where you will access the NF installation. This depends on your installation; if you are using Balena, make sure the Balena VPN URLs are included. For instance, include https://*.balena-devices.com/ for both options (see Security Considerations.)

Set Up Normal Framework using Auth0¶

In order for NF to require login, you must configure Envoy to validate JWTs issued by your Auth0 tenant, and the frontend to redirect the user into the login flow if no session exists. Set the following environment variables:

These must be at minimum set on the envoy and platform-service containers.

Set up Azure AD B2C¶

First, follow the steps to configure a new application and API scope in your Azure AD B2C tenant, saving the client ID and scope obtained during setup.

In order to use this configuration in your NF installation, set the following environment variables. 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)