chore(auth): Added integration tests and snippets for session management (#178)

* chore(auth): Added integration tests and snippets for cookie management

* Added extra cookie options

* Cleaned up snippet code after testing

Author: hiranya911

FirebaseAdmin/FirebaseAdmin.IntegrationTests/FirebaseAuthTest.cs

@@ -487,6 +487,39 @@ public async Task SignInWithEmailLink()
             }
         }
 
+        [Fact]
+        public async Task SessionCookie()
+        {
+            var customToken = await FirebaseAuth.DefaultInstance.CreateCustomTokenAsync("testuser");
+            var idToken = await SignInWithCustomTokenAsync(customToken);
+
+            var options = new SessionCookieOptions()
+            {
+                ExpiresIn = TimeSpan.FromHours(1),
+            };
+            var sessionCookie = await FirebaseAuth.DefaultInstance.CreateSessionCookieAsync(
+                idToken, options);
+            var decoded = await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(sessionCookie);
+            Assert.Equal("testuser", decoded.Uid);
+
+            await Task.Delay(1000);
+            await FirebaseAuth.DefaultInstance.RevokeRefreshTokensAsync("testuser");
+            decoded = await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(sessionCookie);
+            Assert.Equal("testuser", decoded.Uid);
+
+            var exception = await Assert.ThrowsAsync<FirebaseAuthException>(
+                async () => await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(
+                    sessionCookie, true));
+            Assert.Equal(ErrorCode.InvalidArgument, exception.ErrorCode);
+            Assert.Equal(AuthErrorCode.RevokedSessionCookie, exception.AuthErrorCode);
+
+            idToken = await SignInWithCustomTokenAsync(customToken);
+            sessionCookie = await FirebaseAuth.DefaultInstance.CreateSessionCookieAsync(
+                idToken, options);
+            decoded = await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(sessionCookie, true);
+            Assert.Equal("testuser", decoded.Uid);
+        }
+
         private static async Task<UserRecord> CreateUserForActionLinksAsync()
         {
             var randomUser = RandomUser.Create();

FirebaseAdmin/FirebaseAdmin.Snippets/FirebaseAdmin.Snippets.csproj

@@ -9,6 +9,8 @@
 
   <ItemGroup>
     <PackageReference Include="Google.Apis.Auth" Version="1.40.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Http" Version="2.2.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
   </ItemGroup>
 
   <ItemGroup>

FirebaseAdmin/FirebaseAdmin.Snippets/FirebaseAuthSnippets.cs

@@ -16,6 +16,8 @@
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using FirebaseAdmin.Auth;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
 
 namespace FirebaseAdmin.Snippets
 {
@@ -346,5 +348,176 @@ internal static async Task GenerateSignInWithEmailLink()
         // Place holder method to make the compiler happy. This is referenced by all email action
         // link snippets.
         private static void SendCustomEmail(string email, string displayName, string link) { }
+
+        public class LoginRequest
+        {
+            public string IdToken { get; set; }
+        }
+
+        public class SessionCookieSnippets : ControllerBase
+        {
+            // [START session_login]
+            // POST: /sessionLogin
+            [HttpPost]
+            public async Task<ActionResult> Login([FromBody] LoginRequest request)
+            {
+                // Set session expiration to 5 days.
+                var options = new SessionCookieOptions()
+                {
+                    ExpiresIn = TimeSpan.FromDays(5),
+                };
+
+                try
+                {
+                    // Create the session cookie. This will also verify the ID token in the process.
+                    // The session cookie will have the same claims as the ID token.
+                    var sessionCookie = await FirebaseAuth.DefaultInstance
+                        .CreateSessionCookieAsync(request.IdToken, options);
+
+                    // Set cookie policy parameters as required.
+                    var cookieOptions = new CookieOptions()
+                    {
+                        Expires = DateTimeOffset.UtcNow.Add(options.ExpiresIn),
+                        HttpOnly = true,
+                        Secure = true,
+                    };
+                    this.Response.Cookies.Append("session", sessionCookie, cookieOptions);
+                    return this.Ok();
+                }
+                catch (FirebaseAuthException)
+                {
+                    return this.Unauthorized("Failed to create a session cookie");
+                }
+            }
+
+            // [END session_login]
+
+            // [START session_verify]
+            // POST: /profile
+            [HttpPost]
+            public async Task<ActionResult> Profile()
+            {
+                var sessionCookie = this.Request.Cookies["session"];
+                if (string.IsNullOrEmpty(sessionCookie))
+                {
+                    // Session cookie is not available. Force user to login.
+                    return this.Redirect("/login");
+                }
+
+                try
+                {
+                    // Verify the session cookie. In this case an additional check is added to detect
+                    // if the user's Firebase session was revoked, user deleted/disabled, etc.
+                    var checkRevoked = true;
+                    var decodedToken = await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(
+                        sessionCookie, checkRevoked);
+                    return ViewContentForUser(decodedToken);
+                }
+                catch (FirebaseAuthException)
+                {
+                    // Session cookie is invalid or revoked. Force user to login.
+                    return this.Redirect("/login");
+                }
+            }
+
+            // [END session_verify]
+
+            // [START session_clear]
+            // POST: /sessionLogout
+            [HttpPost]
+            public ActionResult ClearSessionCookie()
+            {
+                this.Response.Cookies.Delete("session");
+                return this.Redirect("/login");
+            }
+
+            // [END session_clear]
+
+            // [START session_clear_and_revoke]
+            // POST: /sessionLogout
+            [HttpPost]
+            public async Task<ActionResult> ClearSessionCookieAndRevoke()
+            {
+                var sessionCookie = this.Request.Cookies["session"];
+                try
+                {
+                    var decodedToken = await FirebaseAuth.DefaultInstance
+                        .VerifySessionCookieAsync(sessionCookie);
+                    await FirebaseAuth.DefaultInstance.RevokeRefreshTokensAsync(decodedToken.Uid);
+                    this.Response.Cookies.Delete("session");
+                    return this.Redirect("/login");
+                }
+                catch (FirebaseAuthException)
+                {
+                    return this.Redirect("/login");
+                }
+            }
+
+            // [END session_clear_and_revoke]
+
+            internal async Task<ActionResult> CheckAuthTime(string idToken)
+            {
+                // [START check_auth_time]
+                // To ensure that cookies are set only on recently signed in users, check auth_time in
+                // ID token before creating a cookie.
+                var decodedToken = await FirebaseAuth.DefaultInstance.VerifyIdTokenAsync(idToken);
+                var authTime = new DateTime(1970, 1, 1).AddSeconds(
+                    (long)decodedToken.Claims["auth_time"]);
+
+                // Only process if the user signed in within the last 5 minutes.
+                if (DateTime.UtcNow - authTime < TimeSpan.FromMinutes(5))
+                {
+                    var options = new SessionCookieOptions()
+                    {
+                        ExpiresIn = TimeSpan.FromDays(5),
+                    };
+                    var sessionCookie = await FirebaseAuth.DefaultInstance.CreateSessionCookieAsync(
+                        idToken, options);
+                    // Set cookie policy parameters as required.
+                    this.Response.Cookies.Append("session", sessionCookie);
+                    return this.Ok();
+                }
+
+                // User did not sign in recently. To guard against ID token theft, require
+                // re-authentication.
+                return this.Unauthorized("Recent sign in required");
+                // [END check_auth_time]
+            }
+
+            internal async Task<ActionResult> CheckPermissions(string sessionCookie)
+            {
+                // [START session_verify_with_permission_check]
+                try
+                {
+                    var checkRevoked = true;
+                    var decodedToken = await FirebaseAuth.DefaultInstance.VerifySessionCookieAsync(
+                        sessionCookie, checkRevoked);
+                    object isAdmin;
+                    if (decodedToken.Claims.TryGetValue("admin", out isAdmin) && (bool)isAdmin)
+                    {
+                        return ViewContentForAdmin(decodedToken);
+                    }
+
+                    return this.Unauthorized("Insufficient permissions");
+                }
+                catch (FirebaseAuthException)
+                {
+                    // Session cookie is invalid or revoked. Force user to login.
+                    return this.Redirect("/login");
+                }
+
+                // [END session_verify_with_permission_check]
+            }
+
+            private static ActionResult ViewContentForUser(FirebaseToken token)
+            {
+                return null;
+            }
+
+            private static ActionResult ViewContentForAdmin(FirebaseToken token)
+            {
+                return null;
+            }
+        }
     }
 }