#12: cleanup and documentation

grails-app/controllers/com/odobo/grails/plugin/springsecurity/rest/OauthController.groovy

@@ -11,18 +11,30 @@ class OauthController {
     def oauthService
     def grailsApplication
 
+    /**
+     * Starts the OAuth 2.0 authentication flow, redirecting to the provider's Login URL
+     */
     def authenticate(String provider) {
         BaseOAuth20Client client = oauthService.getClient(provider)
         WebContext context = new J2EContext(request, response)
-        redirect url: client.getRedirectionUrl(context)
-    }
 
+        def redirectionUrl = client.getRedirectionUrl(context)
+        log.debug "Redirecting to ${redirectionUrl}"
+        redirect url: redirectionUrl
+    }
 
+    /**
+     * Handles the OAuth 2.0 provider callback. It uses {@link OauthService} to generate and store a token for that user,
+     * and finally redirects to the configured frontend callback URL, where the token is in the URL. That way, the
+     * frontend application can store the REST API token locally for subsequent API calls.
+     */
     def callback(String provider) {
-        BaseOAuth20Client client = oauthService.getClient(provider)
         WebContext context = new J2EContext(request, response)
         String tokenValue = oauthService.storeAuthentication(provider, context)
-        redirect url: grailsApplication.config.grails.plugin.springsecurity.rest.oauth.frontendCallbackUrl.call(tokenValue)
+
+        def frontendCallbackUrl = grailsApplication.config.grails.plugin.springsecurity.rest.oauth.frontendCallbackUrl.call(tokenValue)
+        log.debug "Redirecting to ${redirectionUrl}"
+        redirect url: frontendCallbackUrl
     }
 
 

grails-app/services/com/odobo/grails/plugin/springsecurity/rest/OauthService.groovy

@@ -13,6 +13,9 @@ import org.springframework.security.core.context.SecurityContextHolder
 import org.springframework.security.core.userdetails.UserDetails
 import org.springframework.security.core.userdetails.UserDetailsService
 
+/**
+ * Deals with pac4j library to fetch a user profile from the selected OAuth provider, and stores it on the security context
+ */
 class OauthService {
 
     TokenGenerator tokenGenerator
@@ -23,31 +26,38 @@ class OauthService {
 
 
     private BaseOAuth20Client<OAuth20Profile> getClient(String provider) {
+        log.debug "Creating OAuth 2.0 client for provider: ${provider}"
         def providerConfig = grailsApplication.config.grails.plugin.springsecurity.rest.oauth."${provider}"
         def ClientClass = providerConfig.client
 
         BaseOAuth20Client<OAuth20Profile> client = ClientClass.newInstance(providerConfig.key, providerConfig.secret)
-        client.callbackUrl = grailsLinkGenerator.link controller: 'oauth', action: 'callback', params: [provider: provider], mapping: 'oauth', absolute: true
+
+        String callbackUrl = grailsLinkGenerator.link controller: 'oauth', action: 'callback', params: [provider: provider], mapping: 'oauth', absolute: true
+        log.debug "Callback URL is: ${callbackUrl}"
+        client.callbackUrl = callbackUrl
+
         client.scope = providerConfig.scope
+
         return client
     }
 
     String storeAuthentication(String provider, WebContext context) {
         BaseOAuth20Client<OAuth20Profile> client = getClient(provider)
         OAuthCredentials credentials = client.getCredentials context
+
+        log.debug "Querying provider to fetch User ID"
         OAuth20Profile profile = client.getUserProfile credentials
 
         log.debug "User's ID: ${profile.id}"
 
         String tokenValue = tokenGenerator.generateToken()
-        log.debug "Generated token: ${tokenValue}"
+        log.debug "Generated REST authentication token: ${tokenValue}"
 
         UserDetails userDetails = userDetailsService.loadUserByUsername profile.id
 
+        log.debug "Storing token on the token storage"
         tokenStorageService.storeToken(tokenValue, userDetails)
-
         Authentication authenticationResult = new RestAuthenticationToken(userDetails, userDetails.password, userDetails.authorities, tokenValue)
-
         SecurityContextHolder.context.setAuthentication(authenticationResult)
 
         return tokenValue