====== How does it work? ======

======Overviews======

The protocol is a modified version of CAS((https://en.wikipedia.org/wiki/Central_Authentication_Service)) protocol. The enhancement provided by Chula SSO is the application authentication. The application authentication allows the system to control which application should be allowed to use the SSO system. The workflow is provided below. 

===== Access from App1 =====
<uml>
actor User
participant Client
participant "SSO Server" as SSO

== Request Access to App1 ==
User -> Client : To "app1"
activate Client

Client -> App1 : GET http://www.app1.com 
activate App1
App1 -> Client : 302 Location: http://account.sso.com/login?service=http://www.app1.com/
deactivate App1


== Login ==
Client -> SSO  : GET http://account.sso.com/logon?service=http://www.app1.com/
activate Client
activate SSO
SSO -> Client : SSO login form
deactivate SSO

Client -> User : SSO login form
User -> Client : submit credential

Client -> SSO : POST http://account.sso.com/login?service=http://www.app1.com/
activate SSO
note right
username and password
end note
SSO -> SSO    : authenticate user
SSO-> Client  : Set-Cookie: DeeTGT=TGT-SAMPLE\n302 Location: http://www.app1.com/?ticket=DEMO-TICKET
deactivate SSO
deactivate Client


== Ticket Validation ==
activate App1
Client -> App1 : GET http://www.app1.com/?ticket=DEMO-TICKET
App1 -> SSO    : Header: DeeAppId=DEMOAPPID\nHeader: DeeAppSecret=DEMOAPPSECRET\nHeader: DeeTicket=DEMO-TICKET\nGET http://account.sso.com/serviceValidation

activate SSO
SSO -> App1    : On success\n\t200 [User Object]\nOn error\n\t401 [error info]
deactivate SSO

App1 -> Client : Set-Cookie: App1Session=SESS12345\n302 Location: http://www.app1.com/
deactivate App1


== App Access ==
Client -> App1 : Cookie: App1Session=SESS12345\nGET http://www.app1.com/
activate App1

App1 -> App1   : validate session cookie
App1 -> Client : 200 [content]
deactivate App1
Client -> User : Display "app1"
deactivate Client



== Second Access to App1 ==
User -> Client : Request for service 
activate Client
Client -> App1 : Cookie: App1Session=SESS12345\nGET http://www.app1.com/service
activate App1

App1 -> App1   : validate session cookie
App1 -> Client : 200 [resource content]
deactivate App1
Client -> User : Display [service content]
deactivate Client

</uml>
===== Access from App2 =====
<uml>
actor User
participant Client
participant "SSO Server" as SSO

== First Access to App2 ==
User -> Client : To "app2"
activate Client
Client -> App2 : GET http://www.app2.com 
activate App2
App2 -> Client : 302 Location: http://account.sso.com/login?service=http://www.app2.com/
deactivate App2
Client -> SSO  : Cookie: DeeTGT=TGT-SAMPLE\nGET http://account.sso.com/login?service=http://www.app2.com/
activate SSO
activate Client
SSO -> SSO     : validate DeeTGT
SSO -> Client  : 302 Location: http://www.app2.com/?ticket=DEMO-APP2-TICKET
deactivate Client
deactivate SSO
== Ticket Validation ==
Client -> App2 : GET http://www.app2.com/?ticket=DEMO-APP2-TICKET

activate App2

App2 -> SSO    : Header: DeeAppId=DEMOAPP2ID\nHeader: DeeAppSecret=DEMOAPP2SECRET\nHeader: DeeTicket=DEMO-TICKET\nGET http://account.sso.com/serviceValidation

activate SSO
SSO -> App2    : On success\n\t200 [User Object]\nOn error\n\t401 [error info]
deactivate SSO

App2 -> Client : Set-Cookie: App2Session=PHP12345\n302 Location: http://www.app2.com/
deactivate App2

Client -> App2 : Cookie: App2Session=PHP12345\nGET http://www.app2.com/
activate App2
App2 -> App2   : validate session cookie
App2 -> Client : 200 [app2 content]
deactivate App2

Client -> User : Display [app2 content]
deactivate Client

</uml>

====== Software Architecture ======
The SSO application is based on a Java EE7 Web application. In addition to Glassfish 4.1, it has been tested extensive with Tomcat 8.0 running on Java 1.8. The default database is MongoDB. 





====== Servlet API References ======
There are five servlets for the application to connect with the SSO. They are Login, Logout, ServiceValidation, activation, and forget.
===== Login =====
End Point: **/login**\\
Method: **GET/POST**\\
Description\\
  The login service for validating and generating TGT (session).
Parameters 
  * service : a url  to redirect to after successful authentication
  * username : a username (email)
  * password : a password
  * remember : [0:1] if remember!=0 the session will never expire
Return
  * Without a valid session,  302 redirect to /html/login.html with service parameter.
  * With a valid session,  302 redirect to a service url with ticket parameter.

===== Logout =====
End Point: **/logout**\\
Method: **GET/POST**\\
Description\\
  The logout service for killing the session.
Parameters: 
  * service : a url  to redirect to after successful authentication. If not specify, the default value is /html/logout.html
Return:
  * 302 Redirect to the service url.

===== ServiceValidation=====
End Point: **/serviceValidation**\\
Method: **GET/POST**\\
Description
  Validate Ticket
Headers:
  * DeeAppId : Application identification
  * DeeAppSecret : Application secret key
  * DeeTicket : ticketid for validation
Parameters:
<del>  * ticket : ticketid for validation</del>

Return:
  * On success, Status 200 - content is the json object representing user information<code json>
{
"uid" : "0001",
"username" : "demo",
"gecos" : "Demo Account",
"email" : "demo@example.com"
"roles" : ["faculty","student"]
"ouid" : {employeeid or studentid}
}
</code>
  * On failed, Status 401 - content is the json object representing error.<code json>
{
"type" : "error",
"content" : "invalid ticket/permission"
}
</code>