Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Authentication Service 2.0"
m (Added link to Authentication Service 1.1 UI) |
|||
Line 1: | Line 1: | ||
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}} [[Image:Higgins logo 76Wx100H.jpg|right]] | {{#eclipseproject:technology.higgins|eclipse_custom_style.css}} [[Image:Higgins logo 76Wx100H.jpg|right]] | ||
− | This page describes a new network [[ | + | This page describes a new network [[Authentication Service 1.1]]. |
== Objective == | == Objective == | ||
Line 57: | Line 57: | ||
*Selector requests CAPTCHA | *Selector requests CAPTCHA | ||
*Auth service sends CAPTCHA ID (selector may load captcha image by using ''GET /captcha/<captchaId>'') | *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'') | + | *Selector sends username, hash-of-password for obtain session token (''POST /sessiontoken'') |
− | *Auth service returns session token | + | *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/<captchaId>/<captcha answer>'') and http Authorization header (''Authorization: HWS <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/<captchaId>/<captcha answer>'') and http Authorization header (''Authorization: HWS <session_token>'') |
*Auth service sends OTP via out-of-band channel (email, sms, etc) | *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>'') | + | *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) | *returns with an access token which includes (selector public key, username) | ||
=== Selector authentication and access token issuance === | === 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'') | + | *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) | *Returns a fresh access token containing (username, selector public key) | ||
*Access token is signed by private key of auth service | *Access token is signed by private key of auth service | ||
Line 77: | Line 77: | ||
*Selector sends request "get reset password OTP" message containing username, selector serial number , CAPTCHA ID and CAPTCHA answer ''(POST /otppwr/<captchaId>/<captcha_answer>)'' | *Selector sends request "get reset password OTP" message containing username, selector serial number , CAPTCHA ID and CAPTCHA answer ''(POST /otppwr/<captchaId>/<captcha_answer>)'' | ||
*Auth service sends OTP via out-of-band channel which was used for adding last user selector | *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>)'' | + | *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 | *"reset password" request should be signed by selector private key | ||
*Auth service returns an access token which includes (selector public key, username) | *Auth service returns an access token which includes (selector public key, username) | ||
Line 142: | Line 142: | ||
== Rest API == | == Rest API == | ||
− | {| cellspacing="1" cellpadding="1" border="1 | + | {| width="100%" cellspacing="1" cellpadding="1" border="1" |
|- | |- | ||
| align="center" | '''HTTP operation''' | | align="center" | '''HTTP operation''' | ||
Line 196: | Line 196: | ||
|- | |- | ||
− | | POST | + | | POST |
− | | /user/<captchaId>/<captcha_answer> | + | | /user/<captchaId>/<captcha_answer> |
| | | | ||
− | Path parameters:<br>String : captchaId<br>String : captcha answer | + | Path parameters:<br>String : captchaId<br>String : captcha answer |
− | Request parameters:<br>UserCredential : userCredential | + | Request parameters:<br>UserCredential : userCredential |
| | | | ||
− | Creates new user accounts, | + | Creates new user accounts, |
− | returns http status code 201 | + | returns http status code 201 |
|- | |- | ||
− | | PUT | + | | PUT |
− | | /user/<otppwr> | + | | /user/<otppwr> |
| | | | ||
− | Path parameters:<br>String : OTP | + | Path parameters:<br>String : OTP |
− | Request parameters:<br>UserCredential : userCredential | + | Request parameters:<br>UserCredential : userCredential |
| | | | ||
− | Validates OTP, | + | Validates OTP, |
− | updates usee password hash, | + | updates usee password hash, |
− | returns http status code 200 | + | returns http status code 200 |
|- | |- | ||
Line 243: | Line 243: | ||
|- | |- | ||
− | | POST | + | | POST |
− | | /otppwr/<captchaId>/<captcha_answer> | + | | /otppwr/<captchaId>/<captcha_answer> |
− | | Request parameters:<br>UserCredential : userCredential | + | | Request parameters:<br>UserCredential : userCredential |
| Validates captcha,<br>sends OTP via out-of-band channel which was used for adding last user selector | | Validates captcha,<br>sends OTP via out-of-band channel which was used for adding last user selector | ||
|- | |- | ||
Line 271: | Line 271: | ||
| Validates session token,<br>update selector name, key and status,<br>returns http status code 200<br> | | Validates session token,<br>update selector name, key and status,<br>returns http status code 200<br> | ||
|- | |- | ||
− | | DELETE | + | | DELETE |
| /selector/<selectorSerialNumber> | | /selector/<selectorSerialNumber> | ||
| Headers:<br>Authorization: HWS <session_token><br>Path parameters:<br>String : selectorSerialNumber | | Headers:<br>Authorization: HWS <session_token><br>Path parameters:<br>String : selectorSerialNumber | ||
| Validates session token,<br>delete selector.<br> | | Validates session token,<br>delete selector.<br> | ||
|- | |- | ||
− | | | + | | <br> |
− | | | + | | <br> |
− | | | + | | <br> |
− | | | + | | <br> |
|} | |} | ||
Line 294: | Line 294: | ||
== See Also == | == See Also == | ||
− | + | *[[Authentication Service 1.1 UI]] | |
*[[Selector Authentication]] | *[[Selector Authentication]] |
Revision as of 19:38, 24 October 2009
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}This page describes a new network Authentication Service 1.1.
Contents
- 1 Objective
- 2 Background
- 3 High Level Requirements
- 4 High Level Design of the Auth Service
- 5 High Level Design of the Higgins Selector
- 5.1 On startup
- 5.2 Using access token to authenticate to services
- 5.3 Secure local storage
- 5.4 Login user interface
- 5.5 Authenticating the user
- 5.6 Credential storage
- 5.7 Cloud selector authentication
- 5.8 Adding a new selector to user's auth service account
- 5.9 Removing a selector from the user's auth service account
- 6 Rest API
- 7 Implementation characteristics
- 8 Open Issues
- 9 See Also
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, CAPTCHA ID and CAPTCHA answer (POST /user/<captchaId>/<captcha_answer>).
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/<captchaId>/<captcha answer>) 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/<captchaId>/<captcha_answer>)
- 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 | none | Generates new captcha and returns <captchaId> |
GET | /captcha/<captchaId> |
Path parameters: String : captcheId |
Returns captcha image |
GET | /channel | none | Returns all supported transport channels
|
POST |
/accesstoken |
Request parameters: UserCredential : userCredential |
Validates user credential, returns SAML access token |
POST | /sessiontoken |
Request parameters: UserCredential : userCredential |
Validates user credential, return session token |
POST | /user/<captchaId>/<captcha_answer> |
Path parameters: Request parameters: |
Creates new user accounts, returns http status code 201 |
PUT | /user/<otppwr> |
Path parameters: Request parameters: |
Validates OTP, updates usee password hash, returns http status code 200 |
POST | /otp/<captchaId>/<captcha answer> |
Headers: Path parameters: String : captchaId String : captcha answer Request parameters: |
Validates session token, sends OTP via out-of-band channel |
POST | /otppwr/<captchaId>/<captcha_answer> | Request parameters: UserCredential : userCredential |
Validates captcha, sends OTP via out-of-band channel which was used for adding last user selector |
POST | /selector/<otp> |
Headers: String : otp Request parameters: Selector : selector |
Validates session token, persists selector, returns http status code 201 |
GET | /selector | Headers: Authorization: HWS <session_token> |
Validates session token, returns list of user selectors |
PUT | /selector | Headers: Authorization: HWS <session_token> Request parameters: Selector : selector |
Validates session token, update selector name, key and status, returns http status code 200 |
DELETE | /selector/<selectorSerialNumber> | Headers: Authorization: HWS <session_token> Path parameters: String : selectorSerialNumber |
Validates session token, delete selector. |
|
|
|
|
Implementation characteristics
- RESTful web service
- Security is of course important
- Uses open standards where possible
Open Issues
- Are there any performance issues with all this public key stuff?
- Should we worry about "idle time"?