auth

README

Auth - Authentication and Authorization service

Auth service provides authentication features as an API for managing authentication keys as well as administering groups of entities - things and users.

Authentication

User service is using Auth service gRPC API to obtain login token or password reset token. Authentication key consists of the following fields:

• ID - key ID
• Type - one of the three types described below
• IssuerID - an ID of the Mainflux User who issued the key
• Subject - user email
• IssuedAt - the timestamp when the key is issued
• ExpiresAt - the timestamp after which the key is invalid

There are three types of authentication keys:

• User key - keys issued to the user upon login request
• API key - keys issued upon the user request
• Recovery key - password recovery key

Authentication keys are represented and distributed by the corresponding JWT.

User keys are issued when user logs in. Each user request (other than registration and login) contains user key that is used to authenticate the user.

API keys are similar to the User keys. The main difference is that API keys have configurable expiration time. If no time is set, the key will never expire. For that reason, API keys are the only key type that can be revoked. This also means that, despite being used as a JWT, it requires a query to the database to validate the API key. The user with API key can perform all the same actions as the user with login key (can act on behalf of the user for Thing, Channel, or user profile management), except issuing new API keys.

Recovery key is the password recovery key. It's short-lived token used for password recovery process.

For in-depth explanation of the aforementioned scenarios, as well as thorough understanding of Mainflux, please check out the official documentation.

The following actions are supported:

• create (all key types)
• verify (all key types)
• obtain (API keys only)
• revoke (API keys only)

Groups

User and Things service are using Auth gRPC API to get the list of ids that are part of a group. Groups can be organized as tree structure. Group consists of the following fields:

• ID - ULID id uniquely representing group
• Name - name of the group, name of the group is unique at the same level of tree hierarchy for a given tree.
• ParentID - id of the parent group
• OwnerID - id of the user that created a group
• Description - free form text, up to 1024 characters
• Metadata - Arbitrary, object-encoded group's data
• Path - tree path consisting of group ids
• CreatedAt - timestamp at which the group is created
• UpdatedAt - timestamp at which the group is updated

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable	Description	Default
MF_AUTH_LOG_LEVEL	Service level (debug, info, warn, error)	error
MF_AUTH_DB_HOST	Database host address	localhost
MF_AUTH_DB_PORT	Database host port	5432
MF_AUTH_DB_USER	Database user	mainflux
MF_AUTH_DB_PASSWORD	Database password	mainflux
MF_AUTH_DB	Name of the database used by the service	auth
MF_AUTH_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
MF_AUTH_DB_SSL_CERT	Path to the PEM encoded certificate file
MF_AUTH_DB_SSL_KEY	Path to the PEM encoded key file
MF_AUTH_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file
MF_AUTH_HTTP_PORT	Auth service HTTP port	8180
MF_AUTH_GRPC_PORT	Auth service gRPC port	8181
MF_AUTH_SERVER_CERT	Path to server certificate in pem format
MF_AUTH_SERVER_KEY	Path to server key in pem format
MF_AUTH_SECRET	String used for signing tokens	auth
MF_AUTH_LOGIN_TOKEN_DURATION	The login token expiration period	10h
MF_JAEGER_URL	Jaeger server URL	localhost:6831

Deployment

The service itself is distributed as Docker container. Check the auth service section in docker-compose to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
go get github.com/MainfluxLabs/mainflux

cd $GOPATH/src/github.com/MainfluxLabs/mainflux

# compile the service
make auth

# copy binary to bin
make install

# set the environment variables and run the service
MF_AUTH_LOG_LEVEL=[Service log level] MF_AUTH_DB_HOST=[Database host address] MF_AUTH_DB_PORT=[Database host port] MF_AUTH_DB_USER=[Database user] MF_AUTH_DB_PASS=[Database password] MF_AUTH_DB=[Name of the database used by the service] MF_AUTH_DB_SSL_MODE=[SSL mode to connect to the database with] MF_AUTH_DB_SSL_CERT=[Path to the PEM encoded certificate file] MF_AUTH_DB_SSL_KEY=[Path to the PEM encoded key file] MF_AUTH_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] MF_AUTH_HTTP_PORT=[Service HTTP port] MF_AUTH_GRPC_PORT=[Service gRPC port] MF_AUTH_SECRET=[String used for signing tokens] MF_AUTH_SERVER_CERT=[Path to server certificate] MF_AUTH_SERVER_KEY=[Path to server key] MF_JAEGER_URL=[Jaeger server URL] MF_AUTH_LOGIN_TOKEN_DURATION=[The login token expiration period] $GOBIN/mainfluxlabs-auth

If MF_EMAIL_TEMPLATE doesn't point to any file service will function but password reset functionality will not work.

Usage

For more information about service capabilities and its usage, please check out the API documentation.

Documentation

Index

• Constants
• Variables
• type Authn
• type Authz
• type AuthzReq
• type Backup
• type Group
• type GroupPoliciesPage
• type GroupPolicy
• type GroupPolicyByID
• type GroupsPage
• type Identity
• type Key
  • func (k Key) Expired() bool
• type KeyRepository
• type Org
• type OrgGroup
• type OrgGroupsPage
• type OrgMember
• type OrgMembersPage
• type OrgMetadata
• type OrgRepository
• type Orgs
• type OrgsPage
• type PageMetadata
• type Policies
• type PoliciesRepository
• type Roles
• type RolesRepository
• type Service
  • func New(orgs OrgRepository, tc mainflux.ThingsServiceClient, ...) Service
• type Tokenizer
• type User

Constants

const (
	// LoginKey is temporary User key received on successful login.
	LoginKey uint32 = iota
	// RecoveryKey represents a key for resseting password.
	RecoveryKey
	// APIKey enables the one to act on behalf of the user.
	APIKey
)

const (
	// RoleRootAdmin is the super admin role.
	RoleRootAdmin = "root"
	// RoleAdmin is the admin role.
	RoleAdmin = "admin"
)

const (
	ViewerRole   = "viewer"
	AdminRole    = "admin"
	OwnerRole    = "owner"
	EditorRole   = "editor"
	RootSubject  = "root"
	GroupSubject = "group"
	ReadAction   = "read"
	WriteAction  = "read_write"
	RPolicy      = "read"
	RwPolicy     = "read_write"
)

Variables

var (
	// ErrInvalidKeyIssuedAt indicates that the Key is being used before it's issued.
	ErrInvalidKeyIssuedAt = errors.New("invalid issue time")

	// ErrKeyExpired indicates that the Key is expired.
	ErrKeyExpired = errors.New("use of expired key")

	// ErrAPIKeyExpired indicates that the Key is expired
	// and that the key type is API key.
	ErrAPIKeyExpired = errors.New("use of expired API key")
)

var (
	// ErrAssignMember indicates failure to assign member to org.
	ErrAssignMember = errors.New("failed to assign member to org")

	// ErrUnassignMember indicates failure to unassign member from an org.
	ErrUnassignMember = errors.New("failed to unassign member from org")

	// ErrAssignGroup indicates failure to assign group to org.
	ErrAssignGroup = errors.New("failed to assign group to org")

	// ErrUnassignGroup indicates failure to unassign group from org.
	ErrUnassignGroup = errors.New("failed to unassign group from org")

	// ErrOrgNotEmpty indicates org is not empty, can't be deleted.
	ErrOrgNotEmpty = errors.New("org is not empty")

	// ErrOrgMemberAlreadyAssigned indicates that members is already assigned.
	ErrOrgMemberAlreadyAssigned = errors.New("org member is already assigned")

	// ErrOrgGroupAlreadyAssigned indicates that group is already assigned.
	ErrOrgGroupAlreadyAssigned = errors.New("org group is already assigned")
)

var (
	// ErrFailedToRetrieveMembers failed to retrieve group members.
	ErrFailedToRetrieveMembers = errors.New("failed to retrieve org members")

	// ErrFailedToRetrieveMembership failed to retrieve memberships
	ErrFailedToRetrieveMembership = errors.New("failed to retrieve memberships")
)

Types

type Authn

type Authn interface {
	// Issue issues a new Key, returning its token value alongside.
	Issue(ctx context.Context, token string, key Key) (Key, string, error)

	// Revoke removes the Key with the provided id that is
	// issued by the user identified by the provided key.
	Revoke(ctx context.Context, token, id string) error

	// RetrieveKey retrieves data for the Key identified by the provided
	// ID, that is issued by the user identified by the provided key.
	RetrieveKey(ctx context.Context, token, id string) (Key, error)

	// Identify validates token token. If token is valid, content
	// is returned. If token is invalid, or invocation failed for some
	// other reason, non-nil error value is returned in response.
	Identify(ctx context.Context, token string) (Identity, error)
}

Authn specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics). Token is a string value of the actual Key and is used to authenticate an Auth service request.

type Authz

type Authz interface {
	Authorize(ctx context.Context, ar AuthzReq) error
	AddPolicy(ctx context.Context, token, groupID, policy string) error
}

Authz represents a authorization service. It exposes functionalities through `auth` to perform authorization.

type AuthzReq

type AuthzReq struct {
	Token   string
	Object  string
	Subject string
	Action  string
}

AuthzReq represents an argument struct for making an authz related function calls.

type Backup

type Backup struct {
	Orgs          []Org
	OrgMembers    []OrgMember
	OrgGroups     []OrgGroup
	GroupPolicies []GroupPolicy
}

type Group

type Group struct {
	ID          string
	OwnerID     string
	Name        string
	Description string
}

type GroupPoliciesPage

type GroupPoliciesPage struct {
	PageMetadata
	GroupPolicies []GroupPolicy
}

type GroupPolicy

type GroupPolicy struct {
	GroupID  string
	MemberID string
	Email    string
	Policy   string
}

type GroupPolicyByID

type GroupPolicyByID struct {
	MemberID string
	Policy   string
}

type GroupsPage

type GroupsPage struct {
	PageMetadata
	Groups []Group
}

type Identity

type Identity struct {
	ID    string
	Email string
}

Identity contains ID and Email.

type Key

type Key struct {
	ID        string
	Type      uint32
	IssuerID  string
	Subject   string
	IssuedAt  time.Time
	ExpiresAt time.Time
}

Key represents API key.

func (Key) Expired

func (k Key) Expired() bool

Expired verifies if the key is expired.

type KeyRepository

type KeyRepository interface {
	// Save persists the Key. A non-nil error is returned to indicate
	// operation failure
	Save(context.Context, Key) (string, error)

	// Retrieve retrieves Key by its unique identifier.
	Retrieve(context.Context, string, string) (Key, error)

	// Remove removes Key with provided ID.
	Remove(context.Context, string, string) error
}

KeyRepository specifies Key persistence API.

type Org

type Org struct {
	ID          string
	OwnerID     string
	Name        string
	Description string
	Metadata    OrgMetadata
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Org represents the org information.

type OrgGroup

type OrgGroup struct {
	GroupID   string
	OrgID     string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type OrgGroupsPage

type OrgGroupsPage struct {
	PageMetadata
	OrgGroups []OrgGroup
}

type OrgMember

type OrgMember struct {
	MemberID  string
	OrgID     string
	Role      string
	CreatedAt time.Time
	UpdatedAt time.Time
	Email     string
}

type OrgMembersPage

type OrgMembersPage struct {
	PageMetadata
	OrgMembers []OrgMember
}

OrgMembersPage contains page related metadata as well as list of members that belong to this page.

type OrgMetadata

type OrgMetadata map[string]interface{}

OrgMetadata defines the Metadata type.

type OrgRepository

type OrgRepository interface {
	// Save orgs
	Save(ctx context.Context, orgs ...Org) error

	// Update an org
	Update(ctx context.Context, org Org) error

	// Delete an org
	Delete(ctx context.Context, owner, id string) error

	// RetrieveByID retrieves org by its id
	RetrieveByID(ctx context.Context, id string) (Org, error)

	// RetrieveByOwner retrieves orgs by owner.
	RetrieveByOwner(ctx context.Context, ownerID string, pm PageMetadata) (OrgsPage, error)

	// RetrieveAll retrieves all orgs.
	RetrieveAll(ctx context.Context) ([]Org, error)

	// RetrieveByAdmin retrieves all orgs with pagination.
	RetrieveByAdmin(ctx context.Context, pm PageMetadata) (OrgsPage, error)

	// RetrieveMemberships list of orgs that member belongs to
	RetrieveMemberships(ctx context.Context, memberID string, pm PageMetadata) (OrgsPage, error)

	// AssignMembers adds members to an org.
	AssignMembers(ctx context.Context, oms ...OrgMember) error

	// UnassignMembers removes members from an org
	UnassignMembers(ctx context.Context, orgID string, memberIDs ...string) error

	// UpdateMembers updates members role in an org.
	UpdateMembers(ctx context.Context, oms ...OrgMember) error

	// RetrieveRole retrieves role of member identified by memberID in org identified by orgID.
	RetrieveRole(ctx context.Context, memberID, orgID string) (string, error)

	// RetrieveMembers retrieves members assigned to an org identified by orgID.
	RetrieveMembers(ctx context.Context, orgID string, pm PageMetadata) (OrgMembersPage, error)

	// RetrieveAllOrgMembers retrieves all org members.
	RetrieveAllOrgMembers(ctx context.Context) ([]OrgMember, error)

	// AssignGroups adds groups to an org.
	AssignGroups(ctx context.Context, ogs ...OrgGroup) error

	// UnassignGroups removes groups from an org
	UnassignGroups(ctx context.Context, orgID string, groupIDs ...string) error

	// RetrieveGroups retrieves groups assigned to an org identified by orgID.
	RetrieveGroups(ctx context.Context, orgID string, pm PageMetadata) (OrgGroupsPage, error)

	// RetrieveByGroupID retrieves org where group is assigned.
	RetrieveByGroupID(ctx context.Context, groupID string) (Org, error)

	// RetrieveAllOrgGroups retrieves all org groups.
	RetrieveAllOrgGroups(ctx context.Context) ([]OrgGroup, error)
}

OrgRepository specifies an org persistence API.

type Orgs

type Orgs interface {
	// CreateOrg creates new org.
	CreateOrg(ctx context.Context, token string, org Org) (Org, error)

	// UpdateOrg updates the org identified by the provided ID.
	UpdateOrg(ctx context.Context, token string, org Org) (Org, error)

	// ViewOrg retrieves data about the org identified by ID.
	ViewOrg(ctx context.Context, token, id string) (Org, error)

	// ListOrgs retrieves orgs.
	ListOrgs(ctx context.Context, token string, pm PageMetadata) (OrgsPage, error)

	// ListOrgMemberships retrieves all orgs for member that is identified with memberID belongs to.
	ListOrgMemberships(ctx context.Context, token, memberID string, pm PageMetadata) (OrgsPage, error)

	// RemoveOrg removes the org identified with the provided ID.
	RemoveOrg(ctx context.Context, token, id string) error

	// AssignMembers adds members with member emails into the org identified by orgID.
	AssignMembers(ctx context.Context, token, orgID string, oms ...OrgMember) error

	// UnassignMembers removes members with member ids from org identified by orgID.
	UnassignMembers(ctx context.Context, token string, orgID string, memberIDs ...string) error

	// UpdateMembers updates members role in an org.
	UpdateMembers(ctx context.Context, token, orgID string, oms ...OrgMember) error

	// ListOrgMembers retrieves members assigned to an org identified by orgID.
	ListOrgMembers(ctx context.Context, token, orgID string, pm PageMetadata) (OrgMembersPage, error)

	// ViewMember retrieves member identified by memberID in org identified by orgID.
	ViewMember(ctx context.Context, token, orgID, memberID string) (OrgMember, error)

	// AssignGroups adds groups with groupIDs into the org identified by orgID.
	AssignGroups(ctx context.Context, token, orgID string, groupIDs ...string) error

	// UnassignGroups removes groups with groupIDs from org identified by orgID.
	UnassignGroups(ctx context.Context, token, orgID string, groupIDs ...string) error

	//ViewGroupMembership retrieves orgs where group is assigned.
	ViewGroupMembership(ctx context.Context, token, groupID string) (Org, error)

	// ListOrgGroups retrieves groups assigned to an org identified by orgID.
	ListOrgGroups(ctx context.Context, token, orgID string, pm PageMetadata) (GroupsPage, error)

	// Backup retrieves all orgs, org members and org groups. Only accessible by admin.
	Backup(ctx context.Context, token string) (Backup, error)

	// Restore adds orgs, org members and org groups from a backup. Only accessible by admin.
	Restore(ctx context.Context, token string, backup Backup) error
}

Orgs specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

type OrgsPage

type OrgsPage struct {
	PageMetadata
	Orgs []Org
}

OrgsPage contains page related metadata as well as list of orgs that belong to this page.

type PageMetadata

type PageMetadata struct {
	Total    uint64
	Offset   uint64
	Limit    uint64
	Name     string
	Metadata OrgMetadata
}

PageMetadata contains page metadata that helps navigation.

type Policies

type Policies interface {
	// CreateGroupPolicies creates group policies.
	CreateGroupPolicies(ctx context.Context, token, groupID string, gps ...GroupPolicyByID) error

	// ListGroupPolicies retrieves page of group policies.
	ListGroupPolicies(ctx context.Context, token, groupID string, pm PageMetadata) (GroupPoliciesPage, error)

	// UpdateGroupPolicies updates group policies.
	UpdateGroupPolicies(ctx context.Context, token, groupID string, gps ...GroupPolicyByID) error

	// RemoveGroupPolicies removes group policies.
	RemoveGroupPolicies(ctx context.Context, token, groupID string, memberIDs ...string) error
}

type PoliciesRepository

type PoliciesRepository interface {
	// SaveGroupPolicies saves group policies.
	SaveGroupPolicies(ctx context.Context, groupID string, gps ...GroupPolicyByID) error

	// RetrieveGroupPolicy retrieves group policy.
	RetrieveGroupPolicy(ctc context.Context, gp GroupPolicy) (string, error)

	// RetrieveGroupPolicies retrieves page of group policies.
	RetrieveGroupPolicies(ctx context.Context, groupID string, pm PageMetadata) (GroupPoliciesPage, error)

	// RetrieveAllGroupPolicies retrieves all group policies. This is used for backup.
	RetrieveAllGroupPolicies(ctx context.Context) ([]GroupPolicy, error)

	// RemoveGroupPolicies removes group policies.
	RemoveGroupPolicies(ctx context.Context, groupID string, memberIDs ...string) error

	// UpdateGroupPolicies updates group policies.
	UpdateGroupPolicies(ctx context.Context, groupID string, gps ...GroupPolicyByID) error
}

type Roles

type Roles interface {
	// AssignRole assigns a role to a user.
	AssignRole(ctx context.Context, id, role string) error

	// RetrieveRole retrieves a role for a user.
	RetrieveRole(ctx context.Context, id string) (string, error)
}

type RolesRepository

type RolesRepository interface {
	// SaveRole saves the user role.
	SaveRole(ctx context.Context, id, role string) error
	// RetrieveRole retrieves the user role.
	RetrieveRole(ctx context.Context, id string) (string, error)
	// UpdateRole updates the user role.
	UpdateRole(ctx context.Context, id, role string) error
	// RemoveRole removes the user role.
	RemoveRole(ctx context.Context, id string) error
}

type Service

type Service interface {
	Authn
	Authz
	Roles
	Orgs
	Policies
}

Service specifies an API that must be fulfilled by the domain service implementation, and all of its decorators (e.g. logging & metrics). Token is a string value of the actual Key and is used to authenticate an Auth service request.

func New

func New(orgs OrgRepository, tc mainflux.ThingsServiceClient, uc mainflux.UsersServiceClient, keys KeyRepository, roles RolesRepository, policies PoliciesRepository, idp mainflux.IDProvider, tokenizer Tokenizer, duration time.Duration) Service

New instantiates the auth service implementation.

type Tokenizer

type Tokenizer interface {
	// Issue converts API Key to its string representation.
	Issue(Key) (string, error)

	// Parse extracts API Key data from string token.
	Parse(string) (Key, error)
}

Tokenizer specifies API for encoding and decoding between string and Key.

type User

type User struct {
	ID     string
	Email  string
	Status string
}