Add hooks to highlight the possibilities of the framework (#673)

Add hooks to highlight the possibilities of the framework

1 files changed, 69 insertions, 18 deletions

diff --git a/docs/oauth2/oauth2provider-server.dot b/docs/oauth2/oauth2provider-server.dot
index ec24078..934bd20 100644
--- a/docs/oauth2/oauth2provider-server.dot
+++ b/docs/oauth2/oauth2provider-server.dot
@@ -5,6 +5,7 @@ digraph oauthlib {
     webapi_ : oauthlib entry/exit points in shape=hexagon
     if_ : internal conditions
     r_ : used when returning from two functions into one for improving clarity
+    h_ : callbacks/hooks available but not required
     */
     center="1"
     edge [ style=bold ];
@@ -62,6 +63,7 @@ digraph oauthlib {
         f_is_within_original_scope [ label="{{<top>is_within_original_scope|{refresh_scopes|refresh_token|request}}|{<true>True|<false>False}}"; ];
         f_validate_user [ label="{{<top>validate_user|{username|password|client|request}}|{<true>True|<false>False}}"; ];
         f_introspect_token [ label="{{<top>introspect_token|{token|token_type_hint|request}}|{<claims>\{claims\}|<none>None}}"; ];
+        f_rotate_refresh_token [ label="{{<top>rotate_refresh_token|{request}}|{<true>True|<false>False}}"; ];
     }
 
     /* OAuthlib Conditions */
@@ -115,11 +117,41 @@ digraph oauthlib {
         f_is_within_original_scope;
     }
 
+    {
+        node [ shape=record,color=grey ];
+        edge [ color=grey ];
+
+        h_pre_auth [ label="{{<top>pre_auth|<arg>request}|<resp>\{credentials\}}}"; ];
+        h_post_auth [ label="{{<top>post_auth|<arg>request}|<resp>\{credentials\}}}"; ];
+        h_pre_token [ label="{{<top>pre_token|<arg>request}|<resp>}}"; ];
+        h_pre_token_password [ label="{{<top>pre_token|<arg>request}|<resp>}}"; ];
+        h_pre_token_implicit [ label="{{<top>pre_token|<arg>request}|<resp>}}"; ];
+        h_post_token [ label="{{<top>post_token|<arg>request}|<resp>}}"; ];
+        h_token_modifiers [ label="{{<top>token_modifiers|{token|token_handler|<arg>request}}|<resp>\{token\}}}"; ];
+        h_code_modifiers [ label="{{<top>code_modifiers|{grant|token_handler|<arg>request}}|<resp>\{grant\}}}"; ];
+        h_generate_access_token [ label="{{<top>generate_access_token|<arg>request}|<resp>\{access token\}}}"; ];
+        h_generate_refresh_token [ label="{{<top>generate_refresh_token|<arg>request}|<resp>\{refresh token\}}}"; ];
+
+        h_pre_auth:resp:se -> h_pre_auth:arg:ne;
+        h_post_auth:resp:se -> h_post_auth:arg:ne;
+        h_pre_token:resp:se -> h_pre_token:arg:ne;
+        h_pre_token_password:resp:se -> h_pre_token_password:arg:ne;
+        h_pre_token_implicit:resp:se -> h_pre_token_implicit:arg:ne;
+        h_post_token:resp:se -> h_post_token:arg:ne;
+        h_token_modifiers:resp:se -> h_token_modifiers:arg:ne;
+        h_code_modifiers:resp:se -> h_code_modifiers:arg:ne;
+    }
+    {
+            rank = same;
+            h_token_modifiers;
+            h_code_modifiers;
+    }
+
     /* Authorization Code - Access Token Request */
     {
         edge [ color=darkgreen ];
 
-        endpoint_token:authorization_code:s -> f_client_authentication_required;
+        endpoint_token:authorization_code:s -> h_pre_token -> f_client_authentication_required;
         f_client_authentication_required:true:s -> f_authenticate_client;
         f_client_authentication_required:false:s -> f_authenticate_client_id;
         f_authenticate_client:true:s -> r_client_authenticated [ arrowhead=none ];
@@ -134,8 +166,12 @@ digraph oauthlib {
         if_redirect_uri_missing -> f_get_default_redirect_uri;
         f_get_default_redirect_uri:redirect_uri:s -> f_confirm_redirect_uri;
 
-        f_confirm_redirect_uri:true:s -> f_save_bearer_token;
-        f_save_bearer_token -> f_invalidate_authorization_code;
+        f_confirm_redirect_uri:true:s -> h_post_token;
+
+        h_post_token -> h_generate_access_token -> f_rotate_refresh_token;
+        f_rotate_refresh_token:true:s -> h_generate_refresh_token -> h_token_modifiers;
+        f_rotate_refresh_token:false:s -> h_token_modifiers;
+        h_token_modifiers -> f_save_bearer_token ->
         f_invalidate_authorization_code -> webapi_response;
     }
     /* Authorization Code - Authorization Request */
@@ -149,8 +185,9 @@ digraph oauthlib {
         if_redirect_uri_present -> f_validate_redirect_uri;
         if_redirect_uri_missing -> f_get_default_redirect_uri;
 
-        f_validate_redirect_uri:true:s -> f_validate_response_type;
-        f_get_default_redirect_uri:redirect_uri:s -> f_validate_response_type;
+        f_validate_redirect_uri:true:s -> h_pre_auth;
+        f_get_default_redirect_uri:redirect_uri:s -> h_pre_auth;
+        h_pre_auth -> f_validate_response_type;
         f_validate_response_type:true:s -> f_is_pkce_required;
         f_is_pkce_required:true:s -> if_code_challenge;
         f_is_pkce_required:false:s -> f_validate_scopes;
@@ -158,7 +195,8 @@ digraph oauthlib {
         if_code_challenge -> f_validate_scopes [ label="present" ];
         if_code_challenge -> e_normal [ label="missing",style=dashed ];
 
-        f_validate_scopes:true:s -> f_save_authorization_code;
+        f_validate_scopes:true:s -> h_post_auth;
+        h_post_auth -> h_code_modifiers -> f_save_authorization_code;
         f_save_authorization_code -> webapi_response;
     }
 
@@ -173,10 +211,13 @@ digraph oauthlib {
         if_redirect_uri_present -> f_validate_redirect_uri;
         if_redirect_uri_missing -> f_get_default_redirect_uri;
 
-        f_validate_redirect_uri:true:s -> f_validate_response_type;
-        f_get_default_redirect_uri:redirect_uri:s -> f_validate_response_type;
+        f_validate_redirect_uri:true:s -> h_pre_auth;
+        f_get_default_redirect_uri:redirect_uri:s -> h_pre_auth;
+        h_pre_auth -> h_pre_token_implicit -> f_validate_response_type;
+
         f_validate_response_type:true:s -> f_validate_scopes;
-        f_validate_scopes:true:s -> f_save_bearer_token;
+        f_validate_scopes:true:s -> h_post_auth -> h_post_token ->
+        h_generate_access_token -> h_token_modifiers ->
         f_save_bearer_token -> webapi_response;
     }
 
@@ -189,15 +230,19 @@ digraph oauthlib {
         f_client_authentication_required:false:s -> f_authenticate_client_id;
         f_authenticate_client:true:s -> r_client_authenticated [ arrowhead=none ];
         f_authenticate_client_id:true:s -> r_client_authenticated [ arrowhead=none ];
-        r_client_authenticated -> f_validate_user;
+        r_client_authenticated -> h_pre_token_password -> f_validate_user;
         f_validate_user:true:s -> f_validate_grant_type;
 
         f_validate_grant_type:true:s -> if_scopes;
         if_scopes -> f_validate_scopes [ label="present" ];
         if_scopes -> f_get_default_scopes [ label="missing" ];
 
-        f_validate_scopes:true:s -> f_save_bearer_token;
-        f_get_default_scopes -> f_save_bearer_token;
+        f_validate_scopes:true:s -> h_post_token;
+        f_get_default_scopes -> h_post_token;
+
+        h_post_token -> h_generate_access_token -> f_rotate_refresh_token;
+        f_rotate_refresh_token:true:s -> h_generate_refresh_token -> h_token_modifiers;
+        f_rotate_refresh_token:false:s -> h_token_modifiers ->
         f_save_bearer_token -> webapi_response;
     }
 
@@ -205,10 +250,13 @@ digraph oauthlib {
     {
         edge [ color=blue ];
 
-        endpoint_token:client_credentials:s -> f_authenticate_client;
+        endpoint_token:client_credentials:s -> h_pre_token -> f_authenticate_client;
+
         f_authenticate_client:true:s -> f_validate_grant_type;
         f_validate_grant_type:true:s -> f_validate_scopes;
-        f_validate_scopes:true:s -> f_save_bearer_token;
+        f_validate_scopes:true:s -> h_post_token;
+
+        h_post_token -> h_generate_access_token -> h_token_modifiers ->
         f_save_bearer_token -> webapi_response;
     }
 
@@ -216,7 +264,7 @@ digraph oauthlib {
     {
         edge [ color=brown ];
 
-        endpoint_token:refresh_token:s -> f_client_authentication_required;
+        endpoint_token:refresh_token:s -> h_pre_token -> f_client_authentication_required;
         f_client_authentication_required:true:s -> f_authenticate_client;
         f_client_authentication_required:false:s -> f_authenticate_client_id;
         f_authenticate_client:true:s -> r_client_authenticated [ arrowhead=none ];
@@ -227,9 +275,12 @@ digraph oauthlib {
         f_validate_refresh_token:true:s -> f_get_original_scopes;
         f_get_original_scopes -> if_all;
         if_all -> f_is_within_original_scope [ label="True" ];
-        if_all -> f_save_bearer_token [ label="False" ];
-        f_is_within_original_scope:true:s -> f_save_bearer_token;
-        f_save_bearer_token -> webapi_response;
+        if_all -> h_post_token [ label="False" ];
+        f_is_within_original_scope:true:s -> h_post_token;
+        h_post_token -> h_generate_access_token -> f_rotate_refresh_token;
+        f_rotate_refresh_token:true:s -> h_generate_refresh_token -> h_token_modifiers;
+        f_rotate_refresh_token:false:s -> h_token_modifiers;
+        h_token_modifiers -> f_save_bearer_token -> webapi_response;
     }
 
     /* Introspect Endpoint  */