authn

README

Local Authentication

The controller may use this system to optionally accept local authentication - i.e. a username and password. This method of authentication is less secure but useful when the area controller is running without any supporting infrastructure, like a dedicated OAuth server.

Local authentication uses OAuth2 password grant to exchange a username and password for a trusted token.

To setup local authentication you need to do two things:

1. Let the area controller know about the local accounts you wish to allow
2. Turn on the local password-based OAuth server

For step 1 we need to create a users.json file in the area controllers data directory (defaults to .data/area-controller-01/users.json). The structure of this file, like tenants.json, is a JSON list of accounts and their hashed passwords:

[
  {
    "id": "email@example.com",
    "title": "My Name",
    "secrets": [
      {"hash": "$2a$10$/uBhiEncrKMgJ8q5AjyRFuqe1dzTNTsOjX1noIzu/lI5JQ78EUvLO"}
    ],
    "zones": ["Floor1", "Floor2"]
  }
]

The secret hash can be generated using the locally provided pash tool:

go run github.com/vanti-dev/sc-bos/cmd/pash           
Password: <enter your password>
$2a$10$/uBhiEncrKMgJ8q5AjyRFuqe1dzTNTsOjX1noIzu/lI5JQ78EUvLO

Finally we can turn on the OAuth password flow for the area controller via this authn system config

// .data/area-controller-01/system.json
{
  "systems": {
    "authn": {
      "user": {
        "fileAccounts": true
      }
    }
  }
}

Documentation

Overview

Package authn provides token based authentication for gRPC requests.

There are two main categories of authn provided by this service:

1. User auth. Used by applications a user interacts with to grant that application permission to act on the users behalf. For example a web app that needs to execute RPCs against this server to access or modify resources owned by the user.
2. Machine authn. Used by applications that require no user intervention. For example a cron job or the AV system of a tenant fit out.

Both auth categories ultimately result in the server checking a client provided token before allowing a request to proceed. Authorization - deciding whether an RPC is allowed - is performed by Open Policy Agent, see docs/permissions-scheme.md This system contributes token validation and claims to the attributes available to OPA policies.

Issuing a token for _user auth_ is either performed via a third-party authentication server or via self hosted OAuth2 Password Flow server. In our case the Auth Server is Keycloak which can be configured to connect to AD to authenticate the user and issue access tokens. The Password Flow server is written by us and checks user credentials against a json file containing ids and hashed passwords, typically used as a local account login for commissioning.

_Machine to controller auth_ is similar but uses the OAuth2 Client Credentials flow. The client is given by an admin a Client ID and a Client Secret when their account is setup. Those details are then exchanged for an access token which can be used by the client to issue RPCs against the server. When validating the Client ID and Secret the server can use a TenantApi.VerifySecret RPC or a local JSON file containing client ids and hashed secrets. Tenant secrets are typically setup using the tenants system in a production environment.

Index

• Constants
• func Factory() system.Factory
• type System
  • func (s *System) Clear()

Constants

const TokenEndpointPath = "/oauth2/token"

Functions

func Factory

func Factory() system.Factory

Types

type System

type System struct {
	*service.Service[config.Root]
	// contains filtered or unexported fields
}

func (*System) Clear

func (s *System) Clear()