Technical/OAuth2-Concepts.md

+# Extension of Git Search for Authentication against GitLab (or any other OAuth2 Service like Google or Facebook)
+
+## Basic Authentication Process
+
+### Classic Login with JWT (Java Web Token): 
+
+```plantuml
+participant Server
+participant Angular
+Angular -> Server: http://localhost:8080/
+Server -> Angular: Response
+activate Angular #FFBBBB
+activate Angular #DarkSalmon
+Angular -> Angular: Login Form
+Angular -> Server: http://localhost:8080/api/authenticate (mit username/Password)
+Server -> Angular: Java Web Token (JWT)
+deactivate Angular
+
+Angular -> Angular: Search
+activate Angular #DarkSalmon
+Angular -> Angular: Use Java Web Token for Authentication in future requests
+Angular -> Server: Send JWT Token
+Server -> Angular: send results
+deactivate Angular
+deactivate Angular
+
+```
+The Git Search service is state less. The JWT is created and decoded in the class `TokenProvider`. The client browser transfers the JWT for each successive request in the "Authorization: Bearer ..."-Header. The JWT contains a base64-encoded JSON-String with the user subject and  list of user authorities together with a signature. 
+
+###  Login with OAuth2: 
+
+The client is redirected to an OpenId-Service (i.e. GitLab). This OpenId-Service returns (via a complex redirect cascade) an authentication token back to the git search service.
+```plantuml
+participant Server
+participant Angular
+participant OpenIdService
+
+Angular -> Server: http://localhost:8080/
+Server -> Angular: Response
+activate Angular #FFBBBB
+activate Angular #DarkSalmon
+Angular -> Angular: Login Form (click auf "Login with GitLab")
+Angular -> Server: http://localhost:8080/oauth2/authorization/oidc
+Server -> Angular: redirect auf https://sharing.codeability-austria.uibk.ac.at/oauth/authorize
+note left of Angular
+   response_type=code&client_id=...&
+   redirectURI=https://localhost:8080/login.oauth2/code/oidc
+end note
+Angular -> OpenIdService: https://sharing.codeability-austria.uibk.ac.at/oauth/authorize...
+
+activate OpenIdService
+OpenIdService -> OpenIdService: login or identification of user
+note right of OpenIdService
+  code=0a2MVVw%3D...
+  state=VG...
+end note
+return redirect http://localhost:8080/login/oauth2/code/oidc
+deactivate OpenIdService
+Angular -> Server: http://localhost:8080/login/oauth2/code/oidc
+activate Server
+Server -> OpenIdService: https://sharing.codeability-austria.uibk.ac.at/oauth/token
+activate OpenIdService
+return OAuth Token
+
+Server -> OpenIdService: https://sharing.codeability-austria.uibk.ac.at/oauth/userinfo (with OAuthToken)
+activate OpenIdService
+return UserInfo
+
+return redirect to http://localhost:8080/ with shortterm-Cookie tempRequestToken  <- JWT Token
+
+note left of Angular
+   short term JWT Token is encoded as Cooke in tempRequestToken  
+   livetime of this JWT Token = 2 sec?
+end note
+
+Angular -> Server: http://localhost:8080/api/refreshJWTToken
+activate Server
+return refreshed Token
+deactivate Server
+
+Angular -> Server: http://localhost:8080/api/account
+activate Server
+return accountInfo
+
+deactivate Server
+deactivate Angular
+
+Angular -> Angular: Search
+activate Angular #DarkSalmon
+Angular -> Angular: Use Java Web Token for Authentication in future requests
+Angular -> Server: Send JWT Token
+Server -> Angular: send results
+deactivate Angular
+deactivate Angular
+```
+
+The access token is now stored in the jwt on the client. Thus it is available on subsequent request.
+Also we do not need state-full session management. However the Spring-OAuth2 component stores for a short time a random state-Token in order to reidentify the answer to the oauth2 request.
+
+If we plan to run the sharing plattform on several nodes, then we have to store the state-tokens in a database.
+
+The Git Search Service uses the Email-Adress as user id.
+
+After a successful authentication, the Git Search Service tries to fetch user details directly from the GitLab-Service via the `UserDetailsFetcher`. It uses GitLabApi-Library to connect to the GitLab Service via the REST Interface.
+
+Gitsearch must run behind a reverse proxy that forwards the original request URL. Otherwise, the redirectURI (see chart above) is not constructed correctly. Additionally, a spring `ForwardedHeaderFilter` must be activated in the SecurityConfig.
+
+Gitlab returns an avatar-URL in the userinfo. Therefore the security-config for img-src was lessened to allow loading of images from *.uibk.ac.at and *.gravatar.com .
+
+Details for configuration are available at https://extgit.iaik.tugraz.at/codeability/codeability/sharingplattform/file-hooks/-/blob/metadata_v0.2/docs/source/git_search.rst (and hopefully on https://codeability.pages.iaik.tugraz.at/codeability/sharingplattform/file-hooks/ soon).
+
+## Open Issues/TODOs
+ 1. User Details in GitLab are not really well mappable to Git Search User Details (GitLab uses Full Name: "Michael Breu", Git Search/JHipster uses first name ("michael") and last name ("Breu")).
+ 2. The GitLabApi in the `UserDetailsFetcher` logs a `Caused by: javax.naming.NoInitialContextException: Need to specify class name in environment or system property, or in an application resource file: java.naming.factory.initial`. However this seems to have no impact on the execution.
+ 3. The access token to use the GitLabApi-Library is now stored in the JWT. However we do not store the timeout for the token.
+ 5. A logout in git search, does not automatically logout in gitlab (and vice versa). This is currently intended.
+ 7. Not sure, whether it was a wise decision to use the email as the user id. Different users need different emails (enforced by GitLab anyway)
+ 8. Not all user functionality (user settings, change password) are still making sense for OAuth2-Authentication. This should be switched off, if user is logged in by OAuth2.
\ No newline at end of file