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"
(→Rest API) |
|||
Line 42: | Line 42: | ||
=== Register new user account === | === 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 requests CAPTCHA (''GET /captcha'') |
− | *Selector checks user name (GET /user/ | + | *Auth service returns CAPTCHA ID (selector may load captcha image by using ''GET /captcha/<captchaId>'') |
− | *Auth service returns 404 http status code if user doesn't exists, otherwise 302 - found. (Selector may re-use that captchaId not more 5 times.) | + | *Selector checks user name (''GET /user/<username>/<captchaId>/<captcha_answer>'') |
− | *Selector sends add user account request containing username, hash-of-password, CAPTCHA ID and CAPTCHA answer (POST /user/ | + | *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>''). | ||
<br> | <br> | ||
− | |||
− | |||
=== Adding a new selector to user's account === | === Adding a new selector to user's account === | ||
*Selector requests list of supported transport channels | *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 | + | *Auth service sends list with channel names (email, sms, etc) (it'll be pluggable feature, so it depends on deployment configuration) |
*Selector requests CAPTCHA | *Selector requests CAPTCHA | ||
− | *Auth service sends CAPTCHA ID (selector may load captcha image by using GET | + | *Auth service sends CAPTCHA ID (selector may load captcha image by using ''GET /captcha/<captchaId>'') |
− | *Selector sends "request add selector token" message containing | + | *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) | *Auth service sends OTP via out-of-band channel (email, sms, etc) | ||
− | *Selector sends "add selector" message containing | + | *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 | + | *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 72: | Line 73: | ||
=== Password reset === | === Password reset === | ||
− | *Selector requests CAPTCHA | + | *Selector requests CAPTCHA ''(GET /captcha)'' |
− | *Auth service sends CAPTCHA ID (selector may load captcha image by using GET | + | *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 | + | *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 | + | *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 |
*"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 143: | Line 144: | ||
{| cellspacing="1" cellpadding="1" border="1" width="100%" | {| cellspacing="1" cellpadding="1" border="1" width="100%" | ||
|- | |- | ||
− | | align="center" | '''HTTP operation''' | + | | align="center" | '''HTTP operation''' |
| align="center" | '''Path''' | | align="center" | '''Path''' | ||
− | | align="center" | '''Parameters''' | + | | align="center" | '''Parameters''' |
| align="center" | '''Note''' | | align="center" | '''Note''' | ||
|- | |- | ||
− | | GET | + | | GET |
| /captcha | | /captcha | ||
− | | none | + | | none |
| Generates new captcha and returns <captchaId> | | Generates new captcha and returns <captchaId> | ||
|- | |- | ||
− | | GET | + | | GET |
| /captcha/<captchaId> | | /captcha/<captchaId> | ||
| | | | ||
− | Path parameters: | + | Path parameters: |
− | String | + | String : captcheId |
| Returns captcha image | | Returns captcha image | ||
|- | |- | ||
− | | GET | + | | GET |
− | | /channel | + | | /channel |
− | | none | + | | none |
| Returns all supported transport channels | | Returns all supported transport channels | ||
− | + | ||
|- | |- | ||
− | | POST<br> | + | | POST<br> |
− | | /accesstoken | + | | /accesstoken |
| | | | ||
− | Request parameters: | + | Request parameters: |
− | UserCredential | + | UserCredential : userCredential |
| | | | ||
− | Validates user credential, | + | Validates user credential, |
− | returns SAML access token | + | returns SAML access token |
|- | |- | ||
− | | POST | + | | POST |
− | | /sessiontoken | + | | /sessiontoken |
| | | | ||
− | Request parameters: | + | Request parameters: |
− | UserCredential | + | UserCredential : userCredential |
| | | | ||
− | Validates user credential, | + | Validates user credential, |
− | return session token | + | return session token |
|- | |- | ||
− | | POST | + | | POST |
− | | /otp/<captchaId>/<captcha answer> | + | | /otp/<captchaId>/<captcha answer> |
| | | | ||
− | Headers:<br>Authorization: HWS <session_token> | + | Headers:<br>Authorization: HWS <session_token> |
− | Path parameters: | + | Path parameters: |
− | String | + | String : captchaId |
− | String | + | String : captcha answer |
− | Request parameters:<br>Channel | + | Request parameters:<br>Channel : channel |
| | | | ||
− | Validates session token, | + | Validates session token, |
− | sends OTP via out-of-band channel | + | sends OTP via out-of-band channel |
|- | |- | ||
− | | POST | + | | POST |
− | | /selector/<otp> | + | | /selector/<otp> |
| | | | ||
− | Headers:<br>Authorization: HWS <session_token><br>Path parameters:<br> | + | Headers:<br>Authorization: HWS <session_token><br>Path parameters:<br> |
− | String | + | String : otp |
− | Request parameters: | + | Request parameters: |
− | Selector | + | Selector : selector |
| Validates session token,<br> persists selector, <br>returns SAML access token.<br> | | Validates session token,<br> persists selector, <br>returns SAML access token.<br> | ||
|- | |- | ||
− | | GET | + | | GET |
− | | /selector | + | | /selector |
− | | Headers:<br>Authorization: HWS <session_token> | + | | Headers:<br>Authorization: HWS <session_token> |
| Validates session token,<br>returns list of user selectors<br> | | Validates session token,<br>returns list of user selectors<br> | ||
|- | |- | ||
− | | PUT | + | | PUT |
− | | /selector | + | | /selector |
− | | Headers:<br>Authorization: HWS <session_token><br>Request parameters:<br>Selector | + | | Headers:<br>Authorization: HWS <session_token><br>Request parameters:<br>Selector : selector<br> |
| Validates session token,<br>update selector name, key and status,<br>returns updated selector.<br> | | Validates session token,<br>update selector name, key and status,<br>returns updated selector.<br> | ||
|- | |- | ||
− | | DELETE | + | | DELETE |
− | | /selector/<selectorSerialNumber> | + | | /selector/<selectorSerialNumber> |
− | | Headers:<br>Authorization: HWS <session_token><br>Path parameters:<br>String | + | | 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> | ||
|- | |- |
Revision as of 11:36, 22 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
- "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 | /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 | /selector/<otp> |
Headers: String : otp Request parameters: Selector : selector |
Validates session token, persists selector, returns SAML access token. |
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 updated selector. |
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"?