authapi

Documentation

Index

• Constants
• Variables
• type AddDeviceArgs
• type AddDeviceResp
• type AddServiceArgs
• type AddServiceResp
• type AddUserArgs
• type AddUserResp
• type AuthnEntry
• type ClientProfile
• type CreateRoleArgs
• type DeleteRoleArgs
• type GetClientProfileArgs
• type GetCountResp
• type GetProfileResp
• type GetProfilesResp
• type IAuthnStore
• type NewTokenArgs
• type NewTokenResp
• type RefreshTokenResp
• type RemoveClientArgs
• type SetServicePermissionsArgs
• type UpdateClientArgs
• type UpdateClientPasswordArgs
• type UpdateClientRoleArgs
• type UpdateNameArgs
• type UpdatePasswordArgs
• type UpdatePubKeyArgs

Constants

const (
	PWHASH_ARGON2id = "argon2id"
	PWHASH_BCRYPT   = "bcrypt" // fallback in case argon2i cannot be used
)

supported password hashes

const (
	ClientTypeDevice  = "device"
	ClientTypeService = "service"
	ClientTypeUser    = "user"
)

Types of clients that are issued authentication tokens

const (
	DefaultDeviceTokenValidityDays  = 90  // 90 days
	DefaultServiceTokenValidityDays = 365 // 1 year
	DefaultUserTokenValidityDays    = 30  // 30 days
)

Authentication token validity for client types

const (

	// ClientRoleNone indicates that the user has no particular role. It can not do anything until
	// the role is upgraded to viewer or better.
	//  Read permissions: none
	//  Write permissions: none
	ClientRoleNone = ""

	// ClientRoleAdmin lets a client publish and subscribe to any sources and invoke all services
	//  Read permissions: subEvents, subActions
	//  Write permissions: pubEvents, pubActions, pubConfig
	ClientRoleAdmin = "admin"

	// ClientRoleDevice lets a client publish thing events and subscribe to device actions
	//  Read permissions: subActions
	//  Write permissions: pubTDs, pubEvents
	ClientRoleDevice = "device"

	// ClientRoleManager lets a client subscribe to Thing TD, events, publish actions and update configuration
	//  Read permissions: subEvents
	//  Write permissions: pubActions, pubConfig
	ClientRoleManager = "manager"

	// ClientRoleOperator lets a client subscribe to events and publish actions
	//  Read permissions: subEvents
	//  Write permissions: pubActions
	ClientRoleOperator = "operator"

	// ClientRoleService lets a client acts as an admin user and a device
	//  Read permissions: subEvents, subActions, subConfig
	//  Write permissions: pubEvents, pubActions, pubConfig
	ClientRoleService = "service"

	// ClientRoleViewer lets a client subscribe to Thing TD and Thing Events
	//  Read permissions: subEvents
	//  Write permissions: none
	ClientRoleViewer = "viewer"
)

Predefined user roles.

const AddDeviceMethod = "addDevice"

AddDeviceMethod is the request name to add a device with public key

const AddServiceMethod = "addService"

AddServiceMethod is the request name to add a service with public key

const AddUserMethod = "addUser"

AddUserMethod is the request name to add a user with password

const AuthManageClientsCapability = "manageClients"

AuthManageClientsCapability is the name of the Thing/Capability that handles management requests

const AuthManageRolesCapability = "roles"

AuthManageRolesCapability is the name of the Thing/Capability that handles role requests

const AuthProfileCapability = "profile"

AuthProfileCapability is the name of the Thing/Capability that handles client requests

const AuthRolesCapability = "roles"

AuthRolesCapability defines the 'capability' address part used in sending messages

const AuthServiceName = "auth"

AuthServiceName default ID of the authentication and authorization service

const CreateRoleReq = "createRole"

CreateRoleReq defines the request to create a new custom role

const DefaultAclFilename = "authz.acl"

const DefaultAdminUserID = "admin"

DefaultAdminUserID is the client ID of the default administrator account

const DefaultLauncherServiceID = "launcher"

DefaultLauncherServiceID is the client ID of the launcher service auth creates a key and auth token for the launcher on startup

const DefaultPasswordFile = "hub.passwd"

DefaultPasswordFile is the recommended password filename for Hub authentication

const DeleteRoleReq = "deleteRole"

DeleteRoleReq defines the request to delete a custom role.

const GetClientProfileMethod = "getClientProfile"

GetClientProfileMethod is the request name to get any client's profile

const GetCountMethod = "getCount"

const GetProfileMethod = "getProfile"

GetProfileMethod defines the request to get the current client's profile

const GetProfilesMethod = "getProfiles"

GetProfilesMethod is the request name to get a list of all client profiles

const NewTokenMethod = "newToken"

NewTokenMethod requests a new jwt token for password based login This returns a short-lived auth token that can be used to connect to the message server The token can be refreshed to extend it without requiring a login password. A public key must be on file for this to work.

const RefreshTokenMethod = "refresh"

RefreshTokenMethod requests a new token for the current client

This returns a new short-lived auth token that can be used to authenticate with the hub This requires the client's public key on file.

const RemoveClientMethod = "removeClient"

RemoveClientMethod is the request name to remove a client The caller must be an administrator or service.

const SetServicePermissionsMethod = "setServicePermissions"

SetServicePermissionsMethod is for use by services. This sets the client roles that are allowed to use the service. This fails if the client is not a service.

const UpdateClientMethod = "updateClient"

UpdateClientMethod is the request name to update a client's profile The caller must be an administrator or service.

const UpdateClientPasswordMethod = "updateClientPassword"

UpdateClientPasswordMethod is the request name to update a client's password The caller must be an administrator or service.

const UpdateClientRoleMethod = "updateRole"

UpdateClientRoleMethod is the request name to change a client's role

const UpdateNameMethod = "updateName"

UpdateNameMethod requests changing the display name of the current client

const UpdatePasswordMethod = "updatePassword"

UpdatePasswordMethod requests changing the password of the current client

const UpdatePubKeyMethod = "updatePubKey"

UpdatePubKeyMethod requests changing the public key on file of the current client. The public key is used in token validation and generation. This takes effect immediately. Existing connection must be closed and re-established.

Variables

var DefaultRolePermissions = map[string][]msgserver.RolePermission{
	ClientRoleNone:     nil,
	ClientRoleDevice:   devicePermissions,
	ClientRoleService:  servicePermissions,
	ClientRoleViewer:   viewerPermissions,
	ClientRoleOperator: operatorPermissions,
	ClientRoleManager:  managerPermissions,
	ClientRoleAdmin:    adminPermissions,
}

DefaultRolePermissions contains the default pub/sub permissions for each user role

Types

type AddDeviceArgs

type AddDeviceArgs struct {
	DeviceID    string `json:"deviceID"`
	DisplayName string `json:"displayName"`
	PubKey      string `json:"pubKey"`
}

AddDeviceArgs request message to add a device. The caller must be an administrator or service.

type AddDeviceResp

type AddDeviceResp struct {
	Token string `json:"token"`
}

type AddServiceArgs

type AddServiceArgs struct {
	ServiceID   string `json:"serviceID"`
	DisplayName string `json:"displayName"`
	PubKey      string `json:"pubKey"`
}

AddServiceArgs request message to add a service. The caller must be an administrator or service.

type AddServiceResp

type AddServiceResp struct {
	Token string `json:"token"`
}

type AddUserArgs

type AddUserArgs struct {
	UserID      string `json:"userID"`
	DisplayName string `json:"DisplayName,omitempty"`
	Password    string `json:"password,omitempty"`
	PubKey      string `json:"pubKey,omitempty"`
	Role        string `json:"role,omitempty"`
}

AddUserArgs request message to add a user. The caller must be an administrator or service.

type AddUserResp

type AddUserResp struct {
	Token string `json:"token"`
}

type AuthnEntry

type AuthnEntry struct {
	// Client's profile
	ClientProfile

	// PasswordHash password encrypted with argon2id or bcrypt
	PasswordHash string
}

AuthnEntry containing client profile and password hash For internal use.

type ClientProfile

type ClientProfile struct {
	// The client ID.
	//  for users this is their email
	//  for IoT devices or services, use the bindingID
	//  for services the service instance ID
	ClientID string `json:"clientID,omitempty"`
	// ClientType identifies the client as a ClientTypeDevice, ClientTypeService or ClientTypeUser
	ClientType string `json:"clientType,omitempty"`
	// The client presentation name
	DisplayName string `json:"displayName,omitempty"`
	// The client's public key
	PubKey string `json:"pubKey,omitempty"`
	// timestamp in 'Millisec-Since-Epoc' the entry was last updated
	UpdatedMSE int64 `json:"updatedMSE,omitempty"`
	// TokenValidityDays nr of days that issued JWT tokens are valid for or 0 for default
	TokenValidityDays int `json:"tokenValidityDays,omitempty"`
	// The client's role
	Role string `json:"role,omitempty"`
}

ClientProfile contains client information of sources and users

type CreateRoleArgs

type CreateRoleArgs struct {
	Role string `json:"role"`
}

type DeleteRoleArgs

type DeleteRoleArgs struct {
	Role string `json:"role"`
}

type GetClientProfileArgs

type GetClientProfileArgs struct {
	ClientID string `json:"clientID"`
}

type GetCountResp

type GetCountResp struct {
	N int `json:"n"`
}

type GetProfileResp

type GetProfileResp struct {
	Profile ClientProfile `json:"profile"`
}

GetProfileResp response message to get the client's profile. The message address MUST contain the client sending the action to whom this applies

type GetProfilesResp

type GetProfilesResp struct {
	Profiles []ClientProfile `json:"profiles"`
}

GetProfilesResp response to listClient actions

type IAuthnStore

type IAuthnStore interface {
	// Add adds a device, service or user to the store with authn settings
	// If the client already exists, it is updated with the profile.
	//
	//  clientID is the client's identity
	//  profile to add. Empty fields can receive valid defaults.
	Add(clientID string, profile ClientProfile) error

	// Close the store
	Close()

	// Count returns the number of clients in the store
	Count() int

	// GetAuthClientList provides a list of clients in a format that can
	// directly be applied to the message server.
	GetAuthClientList() []msgserver.ClientAuthInfo

	// GetEntries returns a list of client profiles including the password hash
	// Intended to obtain auth info to apply to the messaging server
	// For internal auth usage only.
	GetEntries() (entries []AuthnEntry)

	// GetProfile returns the client's profile
	// Returns an error if the clientID doesn't exist
	GetProfile(clientID string) (profile ClientProfile, err error)

	// GetProfiles returns all client profiles in the store
	GetProfiles() (entries []ClientProfile, err error)

	// Open the store
	Open() error

	// Remove the client from the store
	// If the client doesn't exist, no error is returned
	Remove(clientID string) (err error)

	// SetPassword stores the hash of the password for the given user.
	// If the clientID doesn't exist, this returns an error.
	//
	// The hashing algorithm is embedded in the store.
	//  clientID is the login ID of the user whose hash to write
	//  password is the password whose hash to store
	// Returns error if the store isn't writable
	SetPassword(clientID string, password string) error

	// Update updates client information
	// If the clientID doesn't exist, this returns an error.
	// This fails if the client doesn't exist.
	Update(clientID string, entry ClientProfile) error

	// VerifyPassword verifies the given password against the stored hash
	// Returns the client profile and an error if the verification fails.
	VerifyPassword(loginID, password string) (ClientProfile, error)
}

IAuthnStore defined the interface for storing authentication data

type NewTokenArgs

type NewTokenArgs struct {
	// Password to verify identity
	Password string `json:"password"`
}

type NewTokenResp

type NewTokenResp struct {
	Token string `json:"Token"`
}

type RefreshTokenResp

type RefreshTokenResp struct {
	Token string `json:"token"`
}

type RemoveClientArgs

type RemoveClientArgs struct {
	ClientID string `json:"clientID"`
}

type SetServicePermissionsArgs

type SetServicePermissionsArgs struct {
	// The service capability to set
	Capability string `json:"capability"`
	// The roles that can use the capability
	Roles []string `json:"roles"`
}

type UpdateClientArgs

type UpdateClientArgs struct {
	ClientID string        `json:"clientID"`
	Profile  ClientProfile `json:"profile"`
}

type UpdateClientPasswordArgs

type UpdateClientPasswordArgs struct {
	ClientID string `json:"clientID"`
	Password string `json:"password"`
}

type UpdateClientRoleArgs

type UpdateClientRoleArgs struct {
	ClientID string `json:"clientID"`
	Role     string `json:"role"`
}

type UpdateNameArgs

type UpdateNameArgs struct {
	NewName string `json:"newName"`
}

type UpdatePasswordArgs

type UpdatePasswordArgs struct {
	NewPassword string `json:"newPassword"`
}

type UpdatePubKeyArgs

type UpdatePubKeyArgs struct {
	NewPubKey string `json:"newPubKey"`
}