Authentication Service 2.0

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

This page describes a new network Authentication Service 1.1.

Objective

A new service that performs authentication of selector clients and issues an access token that can be consumed by both the Higgins Selector (e.g. GTK Selector 1.1-Win) and all of its various supporting services including the I-Card Service 1.1, CardSync Service 1.1.

Background

At present authentication is performed within the RPPS Package within the I-Card Service. Here are some implications:

• In deployments where the I-Card Service and CardSync Service are co-resident, the CardSync Service can rely on this same authentication capability within RPPS Package. However if these services are deployed separately, the [[CardSync Service will have no way to authenticate the selector client.
• As we move towards Higgins 1.1 other new services may be added that also need to authenticate the selector client. With the current design this is difficult.
• We can envision deployment architectures where organization A would host the authentication service, and organization B would host the others. By having a separate authentication service, this deployment option becomes available.

High Level Requirements

• Separate authentication, provisioning and some account management to a separate "auth" service
• Allow all the existing Higgins services to rely on this auth service to authenticate users/selectors instead of doing it themselves
• Allow the auth service to evolve independently
• Supports uses where one organizational entity is running the auth service and other organizations run the other Higgins services
• Higgins reference implementation of auth service for Higgins 1.1
• Any organization/service that can implement the auth service API can act as a Higgins selector authenticator (no need to use the Higgins reference implementation)
• Auth service can authenticate both client-based and cloud-based selectors
• Allows remote de-authorization of selectors
• Secure design/architecture

High Level Design of the Auth Service

Account management

• Maintains accounts for users.
• Each account is identified by a unique (to this service) account id (aka username)
• Each account holds multiple selector entries, each of which consists of:
  • selector public key
  • selector serial number
  • selector name (human friendly)
  • selector state (active/disabled)

Register new user account

• Selector requests CAPTCHA (GET /captcha)
• Auth service returns CAPTCHA ID (selector may load captcha image by using GET /captcha/<captchaId>)
• Selector checks user name (GET /user/<username>/<captchaId>/<captcha_answer>)
• Auth service returns 404 http status code if user doesn't exists, otherwise 302 - found. (Selector may re-use that captchaId not more than 5 times.)
• Selector sends add user account request containing username, hash-of-password, email address, email marketing permission, CAPTCHA ID and CAPTCHA answer, and (optionally) selector serial number (POST /user).
  • Auth service sends OTP via out-of-band channel (email, sms, etc)
  • Selector sends "add selector" message containing OTP, selector name, selector serial number and selector public key (POST /selector/<otp>) over either SSL or with message encrypted using auth service's certificate and http Authorization header (Authorization: HWS <session_token>)
  • returns with an access token which includes (selector public key, username)
• If selector serial number is not sent, then account is created in non-serialized (low security) mode.

Adding a new selector to user's account

• Selector requests list of supported transport channels
• Auth service sends list with channel names (email, sms, etc) (it'll be pluggable feature, so it depends on deployment configuration)
• Selector requests CAPTCHA
• Auth service sends CAPTCHA ID (selector may load captcha image by using GET /captcha/<captchaId>)
• Selector sends username, hash-of-password for obtain session token (POST /sessiontoken) 
• Auth service returns session token
• Selector sends "request add selector token" message containing, transport channel (email, sms, etc), address (it depends on selected transport channel  like email->email@example.com or sms->1-201-793-9022), CAPTCHA ID and CAPTCHA answer (POST /otp) and http Authorization header (Authorization: HWS <session_token>)
• Auth service sends OTP via out-of-band channel (email, sms, etc)
• Selector sends "add selector" message containing OTP, selector name, selector serial number and selector public key (POST /selector/<otp>) over either SSL or with message encrypted using auth service's certificate and http Authorization header (Authorization: HWS <session_token>)
• returns with an access token which includes (selector public key, username)

Selector authentication and access token issuance

• Receives a "request for access token" message from (non-cloud) selector containing (username, hash-of-password, selector serial number) in message that was signed by selector's private key (POST /accesstoken)
• Returns a fresh access token containing (username, selector public key)
• Access token is signed by private key of auth service
• Access token contains an expiration date/time

Password reset

• Selector requests CAPTCHA (GET /captcha)
• Auth service sends CAPTCHA ID (selector may load captcha image by using GET  /captcha/<captchaId>)
• Selector sends request "get reset password OTP" message containing username, selector serial number , CAPTCHA ID and CAPTCHA answer (POST /otppwr)
• Auth service sends OTP via out-of-band channel which was used for adding last user selector
• Selector sends request "reset password" message containing (username, OTP, selector serial number, new hash-of-password) over either SSL or with message encrypted using auth service's certificate (PUT /user/<otppwr>)
• "reset password" request should be signed by selector private key
• Auth service returns an access token which includes (selector public key, username)

Removing a selector from user's account

• to-be-written

Cloud-selector authentication

• to-be-written: For clientless access (i.e., cloud selector) this could be a two-step process: Step 1: userid + password. Then auth service initiates an out-of-band (i.e. email, sms, voice call, etc.) OTP to the user. Then step 2 is user enters this OTP to get the access token.

High Level Design of the Higgins Selector

On startup

• Selector generates an asymmetric (private/public) key pair
• Selector validates auth service certificate
• Selector sends (username, hash-of-password, selector serial number, selector public key) to auth service

Using access token to authenticate to services

• After getting an access token from the auth service, the selector will, before using any other service (e.g. CardSync) send this access token to the service and get a session token in response
• If the service responds with an error code that indicates that the access token has expired then it will request a fresh access token from the auth service and repeat the process

Secure local storage

• After installation the selector securely stores for each local username/account
  • this selector's serial number
  • this selector's private key

Login user interface

• Has UI that prompts the user for username and password
  • The purpose of the username is to allow a set of the user's selectors to be treated as a logical group by the auth service
  • The purpose of the password is to authenticate the user to the selector (and to a lesser extent the user to the auth service)

Authenticating the user

• Selector pops up the UI described above
• Selector checks that the username entered by the user matches the stored username and that the hash of the password stored locally matches the hash of the stored password
• Selector sends "request for access token" message that contains (username, hash-of-password, proof of serial number possession) either (a) encrypted by using the auth service's certificate or (b) delivered over SSL
• Selector gets an access token in response
• Selector sends this access token to a Higgins service (e.g. CardSync service) and gets a session token in response
• Selector uses this session token to access service

Credential storage

• The selector never stores the password, only a hash of the password
• The selector locally stores the username

Cloud selector authentication

• to-be-written

Adding a new selector to user's auth service account

• to-be-written

Removing a selector from the user's auth service account

• to-be-written

Rest API

HTTP operation	Path	Parameters	Note
GET	/captcha	___________________________	Generates new captcha and returns CaptchaTO
GET	/captcha/<captchaId>	Path parameters: String : captcheId	Returns captcha image
! GET	/channel	____________________________	Returns all supported transport channels
! POST	/accesstoken	Request parameters: UserCredential : userCredential	Validates user credential, returns SAML access token
POST	/sessiontoken	Request parameters: CredentialTO : userCredential	Validates user credential, return SessionTokenTO with status code 200 if user has 'serialized' selectors, but CredentialTO doesn't contain serial number status code will be 230, this session token may be used just for asking new access code GET /otp (see case 2)
POST	/user/check/<captchaId>/<answer> /user/check (just for testing)	Path parameters: String : captchaId String : captcha answer Request parameters: BaseTO: id is user name	Validates captcha, returns BaseTO with status code 404 if user doesn't exists, otherwise 302 - found.
POST	/user/<captchaId>/<answer> /user (just for testing)	Path parameters: String : captchaId String : captcha answer Request parameters: UserTO: userTO	Creates new user accounts, sends Access Code by using  userTO.address value, returns SessionTokenTO with status code 201
PUT	/user/<otp>	Path parameters: String : otp Request parameters: UserCredential : userCredential	Validates OTP, updates user UserCredential, returns BaseTO with status code 200
GET	/user	Headers:Authorization: HWS <session_token>	Validates session token, returns UserTO with empty credential set.
DELETE	/user	Headers:Authorization: HWS <session_token>	Validates session token, deletes user account, returns BaseTO with status code 200
POST	/otp/<captchaId>/<answer> /otp (just for testing)	Headers:Authorization: HWS <session_token>	Validates captcha, sends Access Code to all confirmed email addresses, returns BaseTO with status code 200  (see case 2)
POST	/otp/pw/<captchaId>/<answer> /otp/pw (just for testing)	Path parameters: String : captchaId String : captcha answer Request parameters: BaseTO: id is user name	Validates captcha, check userId, sends password reset code to all confirmed email addresses, returns BaseTO with status code 200
POST	/address	Headers:Authorization: HWS <session_token> Request parameters: AddressTO :  address	Validates session token, returns created AddressTO with status 201.
PUT	/address	Headers:Authorization: HWS <session_token> Request parameters: AddressTO :  address	Validates session token, returns updated  AddressTO if old addres value does not equal new address value, confirmed field will be false.
POST	/address/otp	Headers:Authorization: HWS <session_token> Request parameters: AddressTO :  address	Validates session token, sends access code for confirming email address, returns BaseTO with status code 200
POST	/address/otp/<otp>	Headers:Authorization: HWS <session_token> Path parameter String : otp	Validates session token and access code (otp), update corresponding address, returns updated AddressTO.
DELETE	/address/<addressId>	Headers:Authorization: HWS <session_token>	Validates session token, deletes address, returns BaseTO with status code 200
POST	/selector/<otp>	Headers: Authorization: HWS <session_token> Path parameter String : otp Request parameters: SelectorTO : selector	Validates session token and access code (otp), generate new serial number, persists selector,  returns SelectorTO  with status code 201
PUT	/selector	Headers: Authorization: HWS <session_token> Request parameters: SelectorTO: selector	Validates session token, update selector name, key and status, returns SelectorTO
DELETE	/selector/<selectorSerialNumber>	Headers: Authorization: HWS <session_token> Path parameters: String : selectorSerialNumber	Validates session token, delete selector.

Authentication Service TOs

Implementation characteristics

1. RESTful web service
2. Security is of course important
3. Uses open standards where possible

Open Issues

1. Are there any performance issues with all this public key stuff?
2. Should we worry about "idle time"?
3. We can't support non-secure http connection for non-serialized selectors due to we don't have selector public key. So Authentication Service has to redirect to https, or non-serialized selector has to generate new key pair every time and send public key with UserCredential.

See Also

• Authentication Service 1.1 UI
• Selector Authentication