aah Authentication

Since v0.7 Authentication is the process of identity verification – system trying to validate an subject/user is who they say they are. To do so, a subject/user needs to provide some sort of proof of identity that your system understands and trust.

Familiarize yourself with aah security Terminology, Design and Permissions.

Table of Contents

Terminology to know

TermDescription
SubjectSecurity specific user view of an application user. It can be a human being, a third-party process, a server connecting to an application, or even a cron job. Basically, it is anything or anyone communicating with application.
PrincipalsA subjects identifying attributes. First name, last name, email address, username, social security number, etc.
CredentialSecret data that are used to verify identities. Passwords, x509 certificates, etc.
AuthenticatorAn application implements the interface authc.Authenticator to provide authentication information for authenticating subject/user.

Authentication Schemes

aah supports one or more Authentication Scheme (aka Auth Scheme) for the application. Auth schemes are configured in security.conf, configuration goes under -

# -----------------------------------------------------------------------------
# app name - Security Configuration
#
# Refer documentation to explore and customize the configurations.
#
# Doc: https://docs.aahframework.org/security-config.html
# -----------------------------------------------------------------------------
security {
  auth_schemes {
    # auth scheme config goes here
  }
}

Those defined auth scheme can be mapped per route basis in routes.conf via attributes called default_auth and auth.

aah provides ready to use Auth Scheme -

Authenticator Interface

Based on chosen auth scheme, aah user have to implement interface security/authc.Authenticator to provide security/authc.AuthenticationInfo. For e.g.: it used in Form, Basic, Generic auth scheme.

// Authenticator interface is used to provide authentication information of application
// during a login.
type Authenticator interface {
	// Init method gets called by aah during an application start.
	Init(appCfg *config.Config) error

	// GetAuthenticationInfo method called by auth scheme to get subject's authentication
	// info for given authentication token.
	GetAuthenticationInfo(authcToken *AuthenticationToken) (*AuthenticationInfo, error)
}

Security Best Practice:

Always give generic login failure messages to users because you do not want to aid an attacker trying to break into your system.

How to check Subject is Authenticated on view files

aah provides function isauthenticated to check whether subject is authenticated or not.

{{ if isauthenticated . }}
<a href="/logout">Logout</a>
{{ end }}

Know more about authorization view template functions here.

How to Logout Subject?

To logout the subject/user from application is as follows. It clear all the subject values and session.

ctx.Subject().Logout()