Improved authorization demo

.vscode/cspell.json

@@ -15,11 +15,14 @@
     "contentfiles",
     "Datagram",
     "decoratee",
+    "Decryptor",
     "docfx",
     "ECONNRESET",
+    "Encryptor",
     "EPIPE",
     "Finalizers",
     "globaltool",
+    "Hmac",
     "icecertutils",
     "icerpc",
     "lalrpop",

examples/Authorization/Authenticator.slice

@@ -0,0 +1,15 @@
+// Copyright (c) ZeroC, Inc.
+
+module AuthorizationExample
+
+/// The encrypted identity token.
+typealias EncryptedIdentityToken = sequence<uint8>
+
+/// Represents a service that authenticates a user and return an identity token.
+interface Authenticator {
+    /// Authenticates a user.
+    /// @param name: The user name.
+    /// @param password: The user password.
+    /// @returns: The encrypted identity token.
+    authenticate(name: string, password: string) -> EncryptedIdentityToken
+}

examples/Authorization/Client/AuthenticationInterceptor.cs

@@ -0,0 +1,28 @@
+// Copyright (c) ZeroC, Inc.
+
+using IceRpc;
+using System.Buffers;
+
+namespace AuthorizationExample;
+
+/// <summary>An interceptor that adds the encrypted identity token field to each request.</summary>
+internal class AuthenticationInterceptor : IInvoker
+{
+    private readonly ReadOnlySequence<byte> _identityToken;
+    private readonly IInvoker _next;
+
+    public Task<IncomingResponse> InvokeAsync(OutgoingRequest request, CancellationToken cancellationToken)
+    {
+        request.Fields = request.Fields.With(IdentityTokenFieldKey.Value, _identityToken);
+        return _next.InvokeAsync(request, cancellationToken);
+    }
+
+    /// <summary>Constructs an authentication interceptor.</summary>
+    /// <param name="next">The invoker to call next.</param>
+    /// <param name="identityToken">The encrypted identity token.</param>
+    internal AuthenticationInterceptor(IInvoker next, ReadOnlyMemory<byte> identityToken)
+    {
+        _next = next;
+        _identityToken = new ReadOnlySequence<byte>(identityToken);
+    }
+}

examples/Authorization/Client/Client.csproj

@@ -1,9 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
-    <SliceC Include="../Authorization.slice" />
+    <SliceC Include="../Greeter.slice" />
+    <SliceC Include="../GreeterAdmin.slice" />
+    <SliceC Include="../Authenticator.slice" />
     <PackageReference Include="IceRpc.Slice.Tools" Version="$(IceRpcVersion)" PrivateAssets="All" />
     <PackageReference Include="IceRpc" Version="$(IceRpcVersion)" />
-    <Compile Include="../SessionFieldKey.cs" Link="SessionFieldKey.cs" />
+    <Compile Include="../IdentityTokenFieldKey.cs" Link="IdentityTokenFieldKey.cs" />
   </ItemGroup>
 </Project>

examples/Authorization/Client/PipelineExtensions.cs

@@ -4,14 +4,14 @@
 
 namespace IceRpc;
 
-/// <summary>This class provides an extension method to add a <see cref="SessionInterceptor" />
+/// <summary>This class provides an extension method to add an <see cref="AuthenticationInterceptor" />
 /// to a <see cref="Pipeline" />.</summary>
 internal static class PipelineExtensions
 {
-    /// <summary>Adds a <see cref="SessionInterceptor" /> to the pipeline.</summary>
+    /// <summary>Adds an <see cref="AuthenticationInterceptor" /> to the pipeline.</summary>
     /// <param name="pipeline">The pipeline being configured.</param>
-    /// <param name="token">The session token.</param>
+    /// <param name="identityToken">The encrypted identity token.</param>
     /// <returns>The pipeline being configured.</returns>
-    internal static Pipeline UseSession(this Pipeline pipeline, Guid token) =>
-        pipeline.Use(next => new SessionInterceptor(next, token));
+    internal static Pipeline UseAuthentication(this Pipeline pipeline, ReadOnlyMemory<byte> identityToken) =>
+        pipeline.Use(next => new AuthenticationInterceptor(next, identityToken));
 }

examples/Authorization/Client/Program.cs

@@ -5,35 +5,50 @@
 
 await using var connection = new ClientConnection(new Uri("icerpc://localhost"));
 
-// A `Hello` proxy that doesn't use any authentication. An authentication token is not needed to call `SayHello`.
-var unauthenticatedHelloProxy = new HelloProxy(connection, new Uri("icerpc:/hello"));
+var authenticatorProxy = new AuthenticatorProxy(connection, new Uri("icerpc:/authenticator"));
 
-// Unauthenticated hello; prints generic greeting.
-Console.WriteLine(await unauthenticatedHelloProxy.SayHelloAsync());
+// Authenticate the alice user and get its identity token.
+ReadOnlyMemory<byte> aliceToken = await authenticatorProxy.AuthenticateAsync("alice", "password");
 
-// A `SessionManager` proxy that doesn't use any authentication. Used to create new session tokens.
-var sessionManagerProxy = new SessionManagerProxy(connection, new Uri("icerpc:/sessionManager"));
+// A greeter proxy that doesn't use any identity token.
+var unauthenticatedGreeterProxy = new GreeterProxy(connection, new Uri("icerpc:/greeter"));
 
-// Get an authentication token. The token is used to authenticate future requests.
-var token = new Guid(await sessionManagerProxy.CreateSessionAsync("friend"));
+// The Greet invocation on the unauthenticated greeter proxy prints a generic message.
+Console.WriteLine(await unauthenticatedGreeterProxy.GreetAsync());
 
-// Add an interceptor to the invocation pipeline that inserts the token into a request field.
-Pipeline authenticatedPipeline = new Pipeline().UseSession(token).Into(connection);
+// Create a greeter proxy that uses a pipe line to insert the "alice" token into a request field.
+Pipeline alicePipeline = new Pipeline().UseAuthentication(aliceToken).Into(connection);
+var aliceGreeterProxy = new GreeterProxy(alicePipeline, new Uri("icerpc:/greeter"));
 
-// A `Hello` proxy that uses the authentication pipeline. When an authentication token is used, `SayHello`
-// will return a personalized greeting.
-var helloProxy = new HelloProxy(authenticatedPipeline, new Uri("icerpc:/hello"));
+// The Greet invocation on the authenticated "alice" greeter proxy prints a custom message for "alice".
+Console.WriteLine(await aliceGreeterProxy.GreetAsync());
 
-// A `HelloAdmin` proxy that uses the authentication pipeline. An authentication token is needed to change the greeting.
-var helloAdminProxy = new HelloAdminProxy(authenticatedPipeline, new Uri("icerpc:/helloAdmin"));
+// A greeter admin proxy that uses the "alice" pipeline is not authorized to change the greeting message because "alice"
+// doesn't have administrative privileges.
+var greeterAdminProxy = new GreeterAdminProxy(alicePipeline, new Uri("icerpc:/greeterAdmin"));
+try
+{
+    await greeterAdminProxy.ChangeGreetingAsync("Bonjour");
+}
+catch (DispatchException exception) when (exception.StatusCode == StatusCode.Unauthorized)
+{
+    Console.WriteLine("The 'alice' user is not authorized to change the greeting message.");
+}
 
-// Authenticated hello.
-Console.WriteLine(await helloProxy.SayHelloAsync());
+// Authenticate the "admin" user and get its identity token.
+ReadOnlyMemory<byte> adminToken = await authenticatorProxy.AuthenticateAsync("admin", "admin-password");
 
-// Change the greeting using the authentication token.
-await helloAdminProxy.ChangeGreetingAsync("Bonjour");
+// Create a greeter admin proxy that uses a pipe line to insert the "admin" token into a request field.
+Pipeline adminPipeline = new Pipeline().UseAuthentication(adminToken).Into(connection);
+greeterAdminProxy = new GreeterAdminProxy(adminPipeline, new Uri("icerpc:/greeterAdmin"));
 
-// Authenticated hello with updated greeting.
-Console.WriteLine(await helloProxy.SayHelloAsync());
+// Changing the greeting message should succeed this time because the "admin" user has administrative privilege.
+await greeterAdminProxy.ChangeGreetingAsync("Bonjour");
+
+// The Greet invocation should print a greeting with the updated greeting message.
+Console.WriteLine(await aliceGreeterProxy.GreetAsync());
+
+// Change back the greeting message to Hello.
+await greeterAdminProxy.ChangeGreetingAsync("Hello");
 
 await connection.ShutdownAsync();

examples/Authorization/Greeter.slice

@@ -0,0 +1,10 @@
+// Copyright (c) ZeroC, Inc.
+
+module AuthorizationExample
+
+/// A service to get a personalized greeting message.
+interface Greeter {
+    /// Creates a personalized "hello" greeting.
+    /// @returns: The greeting.
+    greet() -> string
+}

examples/Authorization/GreeterAdmin.slice

@@ -0,0 +1,10 @@
+// Copyright (c) ZeroC, Inc.
+
+module AuthorizationExample
+
+/// Represents a service to configure the greeting of the greeter service.
+interface GreeterAdmin {
+    /// Changes the greeting returned by the Greeting service.
+    /// @param greeting: The new greeting.
+    changeGreeting(greeting: string)
+}

examples/Authorization/IdentityTokenFieldKey.cs

@@ -0,0 +1,11 @@
+// Copyright (c) ZeroC, Inc.
+
+using IceRpc;
+
+namespace AuthorizationExample;
+
+/// <summary>The shared <see cref="RequestFieldKey" /> used to carry the identity token in a request's field.</summary>
+public static class IdentityTokenFieldKey
+{
+    public const RequestFieldKey Value = (RequestFieldKey)100;
+}

examples/Authorization/README.md

@@ -1,14 +1,18 @@
 # Authorization
 
-This example application illustrates how to create an authorization interceptor and middleware that can be used
-to authorize requests.
+This demo demonstrates how token based authorization and authentication can be implemented with an interceptor and two
+middleware. The token carries the name of the user and its administrative privilege.
 
-The server is configured with two middleware components: `LoadSession` and `HasSession`. The first middleware is
-responsible for loading the session from the request field and storing it in a corresponding request feature. The second
-middleware is responsible for checking if the session is present in the corresponding request feature and
-returning an error if it is not.
+The server dispatch pipeline is configured with two middleware:
+- The `AuthenticationMiddleware` is responsible for validating the request's identity token field and setting the
+  request's identity feature.
+- The `AuthorizationMiddleware` is responsible for checking if the request's identity feature is authorized.
 
-The client creates an authorization pipeline that is responsible for adding the session token as a request field.
+The client invocation pipeline is configured with an `AuthenticationInterceptor` interceptor, which is responsible for adding a request field with the encrypted identity token. The client obtains its identity token by authenticating itself with the `Authenticator` service.
+
+The server supports two identity token types:
+- A custom Slice based identity token encrypted with AES (the default).
+- A JWT identity token.
 
 ## Running the example
 
@@ -24,11 +28,19 @@ In a separate window, start the Client:
 dotnet run --project Client/Client.csproj
 ```
 
-The client first calls `SayHelloAsync` without a session token and the server responds with generic a greeting.
+The client first calls `GreetAsync` without an identity token and the server responds with a generic greeting.
+
+Next, the client gets an identity token for the user `alice` and uses it to construct an authentication invocation
+pipeline that adds the `alice` identity token to each request. The client then calls `GreetAsync` using the `alice`
+authentication pipeline and receives a personalized message.
+
+Next, the client calls `ChangeGreetingAsync` using the `alice` authentication pipeline to change the greeting. The user `alice` doesn't have administrative privilege so the invocation fails with a `DispatchException`.
 
-Next, the client gets an authentication token and uses it to construct an authenticated invocation pipeline that adds
-the token to each request. The client then calls `SayHelloAsync` using the authenticated pipeline and receives
-a personalized message.
+Finally, the client authenticates the user `admin` and calls `ChangeGreetingAsync` using an `admin` authentication
+pipeline. The call succeeds because the user `admin` has administrative privilege.
 
-Finally, the client calls `ChangeGreetingAsync` using the authenticated pipeline to change the greeting and then calls
-`SayHelloAsync` a final time.
+To use JTW token instead of AES tokens, start the Server with the `--jwt` argument:
+
+```shell
+dotnet run --project Server/Server.csproj --jwt
+```

examples/Authorization/Server/AesBearerAuthenticationHandler.cs

@@ -0,0 +1,62 @@
+// Copyright (c) ZeroC, Inc.
+
+using IceRpc.Slice;
+using System.Buffers;
+using System.IO.Pipelines;
+using System.Security.Cryptography;
+
+namespace AuthorizationExample;
+
+/// <summary>This is an implementation of <see cref="IBearerAuthenticationHandler" /> to create and validate a Slice
+/// based identity token encrypted with AES.</summary>
+internal sealed class AesBearerAuthenticationHandler : IBearerAuthenticationHandler, IDisposable
+{
+    private readonly Aes _aes;
+
+    public async Task<IIdentityFeature> ValidateIdentityTokenAsync(ReadOnlySequence<byte> identityTokenBytes)
+    {
+        // Decrypt the identity token buffer.
+        using var sourceStream = new MemoryStream(identityTokenBytes.ToArray());
+        using var cryptoStream = new CryptoStream(sourceStream, _aes.CreateDecryptor(), CryptoStreamMode.Read);
+        using var destinationStream = new MemoryStream();
+        await cryptoStream.CopyToAsync(destinationStream);
+
+        // Decode the identity token.
+        AesIdentityToken identityToken = DecodeIdentityToken(destinationStream.ToArray());
+
+        Console.WriteLine(
+            $"Decoded AES identity token {{ name = '{identityToken.Name}' isAdmin = '{identityToken.IsAdmin}' }}");
+
+        return new IdentityFeature(identityToken.Name, identityToken.IsAdmin);
+
+        AesIdentityToken DecodeIdentityToken(ReadOnlyMemory<byte> buffer)
+        {
+            var decoder = new SliceDecoder(destinationStream.ToArray(), SliceEncoding.Slice2);
+            return new AesIdentityToken(ref decoder);
+        }
+    }
+
+    public void Dispose() => _aes.Dispose();
+
+    public ReadOnlyMemory<byte> CreateIdentityToken(string name, bool isAdmin)
+    {
+        // Setup the stream to encrypt the encoded identity token.
+        using var destinationStream = new MemoryStream();
+        using var cryptoStream = new CryptoStream(destinationStream, _aes.CreateEncryptor(), CryptoStreamMode.Write);
+
+        // Encode the identity token.
+        var writer = PipeWriter.Create(cryptoStream, new StreamPipeWriterOptions(leaveOpen: true));
+        var encoder = new SliceEncoder(writer, SliceEncoding.Slice2);
+        new AesIdentityToken(isAdmin, name).Encode(ref encoder);
+        writer.Complete();
+
+        cryptoStream.FlushFinalBlock();
+        return destinationStream.ToArray();
+    }
+
+    internal AesBearerAuthenticationHandler()
+    {
+        _aes = Aes.Create();
+        _aes.Padding = PaddingMode.Zeros;
+    }
+}

examples/Authorization/Server/AesIdentityToken.slice

@@ -0,0 +1,12 @@
+// Copyright (c) ZeroC, Inc.
+
+module AuthorizationExample
+
+/// An identity token.
+struct AesIdentityToken {
+    /// true if the authenticated user has administrative privilege, false otherwise.
+    isAdmin: bool
+
+    /// The user name.
+    name: string
+}