DEV Community: Mohammadali Forouzesh

Complete Guide on OAuth 2.0 Reference tokens in Asp.Net Core 7 Using Openiddict

Mohammadali Forouzesh — Thu, 29 Dec 2022 23:49:25 +0000

Introduction

Refresh tokens are an important part of the OAuth and OpenID Connect protocols, which are used to authenticate and authorize users in web and mobile applications. Refresh tokens are issued to the client application along with an access token, which is used to authenticate requests to protected resources. The access token has a limited lifespan, usually a few hours, and when it expires, the client application can use the refresh token to obtain a new access token.

Refresh tokens are important because they allow the client application to continue accessing protected resources on behalf of the user, without the user having to re-enter their login credentials. This helps to improve the user experience and reduce the risk of unauthorized access to protected resources. Refresh tokens are typically long-lived, with a lifespan of several weeks or months, and are stored securely by the client application. They can be revoked by the user or the authorization server at any time, which means that the client application must be prepared to handle the case where a refresh token is no longer valid.

Configure the use of Refresh Tokens

Here is an example of how you can configure refresh tokens in a C# application using the OpenIDDict library:

First, you will need to install the OpenIDDict NuGet package in your project. You can do this using the following command in the Package Manager Console:



dotnet add package OpenIddict.AspNetCore

Next, you can configure the refresh token flow in your Program.cs file by adding the following code after creating the webapplication builder instance:



builder.Services.AddOpenIddict()
    .AddCore(options =>
    {
        // Configure OpenIddict to use the Entity Framework Core stores and entities.
        options.UseEntityFrameworkCore()
            .UseDbContext<ApplicationDbContext>();
    })
    .AddServer(options =>
    {
        // Enable the authorization, token, and refresh token endpoints.
        options.SetAuthorizationEndpointUris("/connect/authorize")
            .SetTokenEndpointUris("/connect/token")
            .SetRefreshTokenEndpointUris("/connect/token/refresh");

        // Enable the password flow.
        options.AllowPasswordFlow();

        // Accept token responses that are sent as form-encoded data.
        options.AcceptFormEncodedResponse = true;

        // Enable the refresh token flow.
        options.UseRefreshTokens();
    });

(Here we assume that the application uses Entity Framework Core for communication with the database and the configuration for that is correctly in place.)

This code configures OpenIDDict to use the Entity Framework Core stores and entities, and enables the authorization, token, and refresh token endpoints. It also enables the password flow and the refresh token flow, and sets the endpoint URIs for each flow.

Finally, you can add the following code in the Configure method to enable the refresh token flow in the OAuth2 middleware:



app.UseOAuthValidation();
app.UseOpenIddict();

With these changes, your C# application should be able to issue and refresh access tokens using the OpenIDDict library.

Configure it to use reference tokens for refresh tokens

To configure OpenIDDict to use reference tokens for refresh tokens, you can add the following code in the configure services section of your Program.cs file:



builder.Services.AddOpenIddict()
    .AddCore(options =>
    {
         // Omitted code for brevity
    })
    .AddServer(options =>
    {
         // Omitted code for brevity

        // Enable the refresh token flow.
        options.UseRefreshTokens(new OpenIddictServerOptions.RefreshTokenFormatOptions
        {
            // Use reference tokens for refresh tokens.
            UseReferenceTokens = true
        });
    });

This code configures OpenIDDict to use reference tokens for refresh tokens by setting the UseReferenceTokens property to true. Reference tokens are tokens that are stored in the authorization server and are associated with a unique identifier. When a client application wants to refresh an access token, it sends the refresh token identifier to the authorization server, which uses it to look up the corresponding reference token and issue a new access token.

Configure it to use reference tokens for access tokens too

To configure OpenIDDict to use reference tokens for both access and refresh tokens, you can add the following code in the configure services method of your Program.cs file:



builder.Services.AddOpenIddict()
    .AddCore(options =>
    {
        // Omitted code for brevity
    })
    .AddServer(options =>
    {
       // Omitted code for brevity

        // Use reference tokens for access tokens.
        options.UseReferenceAccessTokens();
    });

This code configures OpenIDDict to use reference tokens for both access and refresh tokens by setting the UseReferenceTokens property to true in the UseRefreshTokens method and by calling the UseReferenceAccessTokens method. Reference tokens are tokens that are stored in the authorization server and are associated with a unique identifier. When a client application wants to refresh an access token or access a protected resource, it sends the token identifier to the authorization server, which uses it to look up the corresponding reference token and issue a new access token or return the requested resource.

By using reference tokens for both access and refresh tokens, you can improve the security of your OAuth2 implementation, as the actual tokens are not stored on the client side and are less likely to be compromised. However, it is important to note that reference tokens do have some limitations, such as the need to store the tokens in a secure, centralized location, and the need to handle token revocation properly.

Set Introspection Endpoint

When you use reference tokens as access tokens, they need to be introspected against the issuer, to check the validity of the token.

To configure an introspection endpoint in an OpenIDDict-based OAuth2 implementation, you can add the following code in the configure services section of your Program.cs file:



builder.Services.AddOpenIddict()
    .AddCore(options =>
    {
        // Omitted code for brevity
    })
    .AddServer(options =>
    {
        // Omitted code for brevity

        // Enable the introspection endpoint.
        options.SetIntrospectionEndpointUris("/connect/introspect");
    });

This code configures OpenIDDict to enable the introspection endpoint and sets the endpoint URI to /connect/introspect. The introspection endpoint is an OAuth2-defined endpoint that allows a client application to verify the status and validity of an access token. When a client application sends an access token to the introspection endpoint, the authorization server responds with a JSON object that contains information about the token, such as its expiration time, the associated client application, and the scope of the associated resources.

By enabling the introspection endpoint, you can allow client applications to verify the status of an access token before making a request to a protected resource, which can help to improve the security of your OAuth2 implementation. However, it is important to note that the introspection endpoint requires secure communication and should be protected by TLS/SSL.

Last thing to configure, is to override the introspection server event to include the token payload in the response for correct authorization at the API level:



builder.Services.AddOpenIddict()
    .AddCore(options =>
    {
        // Omitted code for brevity
    })
    .AddServer(options =>
    {
        // Omitted code for brevity
 options.AddEventHandler<OpenIddictServerEvents.ApplyIntrospectionResponseContext>(
                                   o => o.UseScopedHandler<AuthServerApplyIntrospectionResponse>());
    });



internal sealed class
        AuthServerApplyIntrospectionResponse : IOpenIddictServerHandler<OpenIddictServerEvents.ApplyIntrospectionResponseContext>
{
    private readonly OpenIddictTokenManager<AuthServerToken> _tokenManager;

    public SosicredApplyIntrospectionResponse( OpenIddictTokenManager<AuthServerToken> tokenManager )
    {
        _tokenManager = tokenManager;
    }


    public async ValueTask HandleAsync( OpenIddictServerEvents.ApplyIntrospectionResponseContext context )
    {
        if ( context.Request?.Token is not null ) // Bonus part. Try to figure it out on your own and leave a comment.
        {
            if ( await _tokenManager.FindByReferenceIdAsync(context.Request.Token).ConfigureAwait(false) is not
                {
                    ExpirationDate: { }
                } authServerToken ) return;

            if ( authServerToken.Type == OpenIddictConstants.TokenTypeHints.AccessToken )
                if ( authServerToken.ExpirationDate.Value <= DateTime.UtcNow.AddMinutes(15) )
                {
                    authServerToken.ExpirationDate = authServerToken.ExpirationDate.Value.AddMinutes(30);
                    await _tokenManager.UpdateAsync(authServerToken).ConfigureAwait(false);
                }

            context.Response.AddParameter("token_payload", new OpenIddictParameter(authServerToken.Payload));
        }
    }
}

Configure you API to correctly introspect reference tokens

At you API side, you need following authentication configuration to correctly distinguish between reference tokens and normal JWT tokens, and in case of a reference token, introspect the token against the authorization server for checking the validity and getting user information.

Add the following package reference to your csproj file:



<PackageReference Include="IdentityModel.AspNetCore.AccessTokenValidation" Version="1.0.0-preview.3" />

Then insert the following code in the configure services section of your Program.cs:



builder.Services.AddOptions<JwtBearerOptions>().Configure(o => ConfigureJwtOptions(o, configuration));

builder.Services.AddAuthentication()      
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, o => ConfigureJwtOptions(o, configuration))
  .AddOAuth2Introspection(
                    "introspection", o => {
                        o.Authority          = new Uri(configuration["PublicHost"]!).ToString();
                        o.SkipTokensWithDots = true;
                        o.SaveToken          = true;

                        o.Events = new OAuth2IntrospectionEvents
                        {
                            OnTokenValidated = context => {
                                var tokenPayload = context.Principal?.FindFirstValue("token_payload");
                                if ( !string.IsNullOrWhiteSpace(tokenPayload) ) ExtractClaimsFromTokenPayload(context, tokenPayload);

                                return Task.CompletedTask;
                            }
                        };
                    });



private static void ConfigureJwtOptions( JwtBearerOptions o, IConfiguration configuration )
    {
        o.Authority    = new Uri(configuration["PublicHost"]!).ToString();
        o.ClaimsIssuer = new Uri(configuration["PublicHost"]!).ToString();
        o.SaveToken    = true;

        o.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType            = OpenIddictConstants.Claims.Subject,
            RoleClaimType            = OpenIddictConstants.Claims.Role,
            ValidIssuer              = new Uri(configuration["PublicHost"]!).ToString(),
            ValidateIssuer           = true,
            ValidateIssuerSigningKey = true,
            TokenDecryptionKey = new X509SecurityKey(
                new X509Certificate2(Resources.encryption_certificate, configuration["ENCRYPTION_KEY_PASSWORD"])),
            IssuerSigningKey = new X509SecurityKey(
                new X509Certificate2(Resources.signing_certificate, configuration["SIGNING_KEY_PASSWORD"])),
            ValidateAudience = true,
            ValidAudiences   = new[] { "authserver" }
        };

        o.Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = context => {
                Log.Information(context.Exception, "Failed authentication by bearer token.");

                return Task.CompletedTask;
            }
        };

        // if token does not contain a dot, it is a reference token
        o.ForwardDefaultSelector = Selector.ForwardReferenceToken("introspection");
    }



private static void ExtractClaimsFromTokenPayload(
        IdentityModel.AspNetCore.OAuth2Introspection.TokenValidatedContext context, string tokenPayload )
    {
        var jwtOptions = context.HttpContext.RequestServices.GetRequiredService<IOptions<JwtBearerOptions>>().Value;
        foreach (var validator in jwtOptions.SecurityTokenValidators)
        {
            if ( !validator.CanReadToken(tokenPayload) ) continue;

            try
            {
                context.Principal = validator.ValidateToken(tokenPayload, jwtOptions.TokenValidationParameters, out _);

                break;
            }
            catch (Exception ex)
            {
                if ( jwtOptions is { RefreshOnIssuerKeyNotFound: true, ConfigurationManager: { } }
                     && ex is SecurityTokenSignatureKeyNotFoundException ) jwtOptions.ConfigurationManager.RequestRefresh();
            }
        }
    }

Congratulation! With this setup, you now should have a completely working authentication server that supports reference tokens.

Evaluation and conclusion

I was able to gain 77X lower data being sent over the wire in each API request just by using reference tokens. Original JWT tokens (shown in the picture below) were around 3.2KB:

While the equivalent reference token is only 44B. With this improvement, your servers must be able to handle more parallel requests, therefore the whole service is reachable to more users concurrently.

However, performance is always subjective to the use case. Even though this improvement reduce the amount of data being sent over the wire in each API request, it increases background API calls for introspecting tokens which also requires database call. In the context of SaaS, server resources are often assumed to be very high and cheap whereas client resources are considered limited and more precious, therefore such pitfalls must be tolerable.

Mohammadali Forouzesh - A passionate software engineer
06/11/2022
LinkedIn - Instagram

A cleaner and more reliable DevOps routine using build automation tools

Mohammadali Forouzesh — Sun, 06 Nov 2022 17:12:49 +0000

Yes it’s all about reliability. The thing that makes a commercial software stands up and stick to people’s mind. I think the statement is self explanatory but to provide an example, if Google was buggy, it was not the first search engine that comes to everybody’s mind 😉.

Preface

The first key in having a good software is having a good development process. At #matelso we are committed to provide an efficient and reliable digital experience platform as a SaaS. Therefore in today's article, I want to write about how I keep my DevOps routine clean, fast, reliable and efficient using build automation tools.

Disclaimer

This article is not a tutorial nor the explanation on DevOps. It's just my approach to tackle building and deploying software component which in my opinion is good enough but might not be in yours. All in all, there might not be a perfect solution to this challenge so let's share our thoughts and experience to learn and improve our knowledge. Don't hesitate to criticize or support my opinion.

Remark: This article is meant for intermediate to advance programmers who are interested in cloud based software engineering.

Background

In the world of microservice software architecture, every component of a software is a standalone project. Therefore it needs to go through the whole development and operation chain as shown in the famous DevOps picture below:

Doing it all by hand sounds quite cumbersome and being honest who likes to do that? 😢
Nah, we are programmers so we should be able to do better. Let's automate it 💪.

General tools that I use for automating the process

My daily tech routine is quite simple. I code on my windows laptop, commit to git repository, push my git repository to GitLab and from there run my CI/CD pipeline to build, test and deploy my code. However, the key point in this routine is the CI/CD script that I run. This script can get long and unmaintainable if you decide to use only shell scripting, which I was also using even recently, but that's the exact reason why I switched to build automation tools. If you wanna see how, continue reading ;)

Build automation tool

...Is in fact a software that builds your software. I know it might sound complicated at first :) but it's fairly simple.

When we talk about building a project, in today's world what we really mean is "dockerising" that project which is the process of creating a docker image out of your compiled code which can then be run on any container runtime such as docker-compose or Kubernetes.

Of course that is not all and a CI/CD script might include other routines such as QC, test, publish packages and etc. We refer to all of those as CI/CD stages.

My CI/CD script

My projects are mainly C# web projects which then require following stages to go on production:

build
test
quality assurance
pack and publish NuGet packages
rollout

Each of these stages require different tooling and environment. For example the build stage involves docker CLI command while the pack stage needs dotnet CLI and the rollout stage needs Helm and Kubectl. Therefore, integrating all these stages in shell scripts are not that easy all the time. With build automation tools you will have a wrapper around the shell commands which can also ensures the correct environment for that particular stage. Let's see how much the script can differ while using or not using these tools.

Old school: shell scripting

Let's take only the build stage into account. This is a glance of what I've been using in the past:

build:
  stage: build
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - if [ $? -ne 0 ]; then echo "ERROR MISSING DEPLOYMENT Token (create gitlab-deploy-token)"; exit $BUILD_REPLY; fi
    - echo "--== CI running on ${HOSTNAME} ==--"
    - echo "--== CI-BUILD for ${CI_PROJECT_PATH} ==--"
    - GIT_TAG=$(git describe --tags)
    - DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
    - ENV_PREFIX=$(echo $CI_ENVIRONMENT_NAME | tr /a-z/ /A-Z/)
  script:
    - TO_DOCKERISE=$(find . -iname "*.sln" -exec basename -s .sln {} \;)
    - echo "dockerising project $TO_DOCKERISE"
    - docker build -f src/SOSICRED.Server/Dockerfile -t $CI_REGISTRY_IMAGE:$CI_BUILD_REF_NAME -t $CI_REGISTRY_IMAGE:$GIT_TAG -t $CI_REGISTRY_IMAGE:latest .
    - BUILD_REPLY=$?
    - echo "image build returned $BUILD_REPLY"
    - if [ $BUILD_REPLY -ne 0 ]; then echo "ERROR DOCKER IMAGE BUILD FAILED!!!"; exit $BUILD_REPLY; fi
    - echo "--== PUSHING IMAGE TO GITLAB REGISTRY ==--"
    - docker push $CI_REGISTRY_IMAGE:$CI_BUILD_REF_NAME
    - docker push $CI_REGISTRY_IMAGE:$GIT_TAG
    - docker push $CI_REGISTRY_IMAGE:latest
  after_script:
    - echo "--== DONE ==--"
  allow_failure: false
  environment:
    name: build
    url: https://10.8.3.64:3005/publicsuffixtree/json
  when: always
  only:
    - development
    - tags
  tags:
  - build # the GitLab runner's tag

As you see the script is fairly long for only building an image and worse that that, it involves logics that gets out of control really fast like dealing with git tags. If any of my colleagues read this, they'll remember that pain :)

Modern approach: build automation

For that I use NUKE execution engine which I forked and modified based on my own tastes and use cases. Here is the link to their repository that you can check it out https://github.com/nuke-build/nuke

I named it SKBA as in Sky Build Automation :) and up to today I don't have any plans of releasing it as open source and I more like to find commercial collaboration for this evenings project of mine. Here is what I could achieve using SKBA:

build:
  stage: build
  script:
    - skba build-and-push-docker-image --docker-file .\src\SOSICRED.Server\Dockerfile
  allow_failure: false
  rules:
    - if: ($CI_COMMIT_BRANCH == "developemnt" || $CI_COMMIT_TAG =~ /^\d+\.\d+\.\d+$/)
      when: always
    - if: $CI_COMMIT_BRANCH == "master"
      when: never
    - if: $CI_COMMIT_BRANCH
      when: manual
  tags:
  - skba-runner

As you can see with one single command it takes care of building, tagging, versioning and pushing my docker images to the container registry of GitLab. Isn't that interesting 🥳

Additionally, it brings many security enhancements as well. For instance, the first command in the old school approach is docker login command with an argument to pass a plain text password. This approach is not secure and even creates a warning by docker CLI. In the cleaner approach however, there is not foot path of authorizing or any password. All is being handled by SKBA software.

Here is how the logs from this job looks on GitLab:

As you see it even comes with GitLab theming integration where you can collapse the log of a stage plus the summary of what went well and what went wrong in the end.

Is that all?

Well as I mentioned, my CI/CD script includes 5 stages and for all of these stages I only fire a single command of the SKBA tool which minimal number of arguments. As an example, here is the stage that pack and publish all NuGet packages of my project:

pack:
  stage: pack
  script:
    - skba pack-and-push-nuget-packages 
       --nuget-package-name SOSICRED.Client 
       --name-of-projects-to-pack SOSICRED.Client+SOSICRED.Domain
       --restore-nuget-sources [[hidden]
       --push-nuget-source [[hidden]]
       --push-nuget-source-api-key [[hidden]]
       --push-nuget-no-prompt 
  allow_failure: false
  rules:
    - if: ($CI_COMMIT_BRANCH == "development" || $CI_COMMIT_TAG =~ /^\d+\.\d+\.\d+$/)
      when: on_success
    - if: $CI_COMMIT_BRANCH == "master"
      when: never
    - if: $CI_COMMIT_BRANCH
      when: on_success
  tags:
  - skba-runner

Again the cool thing is that I don't need to be worried about the version of my packages as it will be intelligently determined based on the last version that is published, the git version and the branch that runs the pipeline.

Further work

I am planning to add many more features to this tool. Things like sending notifications by email and chat message as well as publishing change log and release articles for the project. Integrating it into Jira workflow is also one my dreams as it replaces some of the manual work I need to do in my daily job. So far I got the initial required set of features implemented in SKBA and I'm very happy with it.

One remark that is worth mentioning, is that I will always keep this tool tailored to the tech stack of my choice which is Git, GitLab, Dotnet and Kubernetes. I think it's quite a lot of work to come up with something general that works with every DevOps tech stack. Every team may build one of these tools for themselves.

Collaboration

As I mentioned earlier, I am not planning release open source version of SKBA, however, I am very interested in collaborating on similar tools if you decide to build one for your own. If you use a different tech stack and still want to integrate build automation into your continuous development routine, we can talk and I can help you with building one. If you have a team that uses similar tech stack as mine, and you want to try SKBA, feel free to contact me and we can talk.

Conclusion

In this article I demonstrated how I made my DevOps routine cleaner and more eloquent by using build automation tools like NUKE. I mainly wrote about building and packaging stages of a CI/CD pipeline while there is more to that. If this sounds interesting to you, stay tuned for my future similar articles on the deployment stage using Kubectl and Helm.

I hope you enjoyed following along with my journey and learn something new. Stay tuned for possible and probable future parts of this article including more challenges and their solutions.

Mohammadali Forouzesh - A passionate software engineer
06/11/2022
LinkedIn - Instagram

A journey to build a central identity management service in .Net with Vue.js SPA frontend

Mohammadali Forouzesh — Sun, 06 Nov 2022 15:30:19 +0000

Have you ever tried implementing authentication and authorization in .Net and felt like you are stuck with the default template of Asp.Net Core framework which only uses razor pages? I mean, using framework features is great but "Never Marry The Framework". In this article, I am going to walk you through my experience of implementing an OAuth and OpenID Connect central identity service which uses .Net features and capabilities while maintaining best practices and full control of the project design.

Preface

Every tools used in this article is available with free commercial license. This article is suitable for intermediate to advance .Net programmers.

List of mentioned tools and libraries:

Asp.Net Core framework (of course!)
Openiddict library
Web API Empty project template
Vue.js frontend
Docker, Kubernetes and GitLab for GitOps

Feel free to comment your thoughts and correct my mistakes. Every software design may have its own pitfalls.

Disclaimer

This article is not a tutorial on how to build an authorization server. There are tons of such tutorials out there but feel free to contact me in case you had implementation questions.

The journey begins with...

An empty Asp.Net Core project template of course. One of my main goals was to decouple different layers of the application architecturally, and stick with the default provided templates as much as I can. Furthermore, I limited the implementation to my use case which for instance did not include two factor authorization (whereas TFA comes with Asp.Net Core Identity template by default).

I wanted to have two main modules in this project: OAuth and a Rest API. While I think OAuth is self explanatory, the REST API in my case is created to be responsible for user management, role and permission management, token management and etc. Next, I separated core functionalities and the domain specific classes of the project into two different class libraries. The domain project would be referenced by the Core project and the Core project will then be referenced by the Server project which serves the whole application. The final setup of the solution can be seen in the following hierarchy:

solution

Core
- DbContext
- EmailSender
- ...
Domain
- User.cs
- Role.cs
- UserRole.cs
- ...
Server
- Areas
  - OAuth
    - AuthenticationController.cs
    - AuthorizationController.cs
  - Rest
    - UsersController.cs
    - RolesController.cs
- Migrations
- Framework
- Healthchecks
- ...

The relation between the packages can be seen in the picture below.

Next stop: Implementing OAuth

To implement an OAuth server together with OpenID connect specification, I used a free and open source framework called Openiddict. You should checkout their GitHub repository at github.com/openiddict/openiddict-core. It is a nice and feature rich tool which help you get started very fast. However, comparing to alternatives like identity server, it needs more implementation rather functionalities coming out of the box.

One remark I want to mention here is that, when you come across a new framework or library or any open source GitHub page, don't stay limited to their "get started" documentation. Be sure to check out some deep parts of it like many hidden gems are not mentioned in the "get started" document.

For instance, I wanted to implement "Refresh Token OAuth Authorization Flow" but didn't quite liked the default implementation of Openiddict cause it pollutes the database so fast (of course, only if you persist tokens in database which you should). I therefore explored every server events that can be subscribed in Openiddict and manipulate the result in the way I prefer. Which then allowed me return the last old valid refresh token along with the access token instead of always generating a new one.

SPA frontend with Vue.js

As I mentioned earlier, my goal was to decouple every possible layers of this web application, mainly backend and frontend. I used Asp.Net Core Identity framework for default user, role and sign in management but as you know, the default Asp.Net Core Identity comes with UI implementation in Razor Pages which is not my preference. To me as a backend engineer, UI is a whole different topic than backend logic and if you keep these two parts of your application separated, you users are going to have the better look and feel of the software as the UI could then be enhanced by the UI expert. Microsoft tries hard to give backend developers as much UI tools and possible like Blazor, MAUI, Razor Pages, etc. so that they could also make the front of web applications with less JavaScript knowledge but trust me, that's not the professional way of doing it. If you want your software to be professionally maintainable, testable and reliable, do not opt in for server side rendered UI pages or any mix that includes server side rendered UI.

Cut to the point, together with UI experts in the team, we created the frontend using Vue 2.7 and Vuetify material design UI kit. Our UI only needed to have 4 different section: login form, logout page, forgot and reset password page. At first, the low number of UI modules might create the false perception that it's easy, BUT it is really not :) Specially when you want to add external logins using Google or Twitter for example., which was one of our main requirements.

Main Challenges

I can name two main challenges that we had to deal with which mainly cause by not having server side rendered pages and serving the UI from a different host. Those challenges were: cookies and redirect URIs. Let's go deeper into those topics.

Cookies

Cookies are one of the main part of authentication in today's web applications. They are many websites which rely on cookies for recognizing if a user has signed in on a browser. The problem is, there some restrictions in terms of sending a cookie to a client after checking his/her username/password for instance. In Asp.Net Core and Asp.Net Core Identity, cookies have some default settings which prevents them from being sent to an application which is on a different host than the server. The property that prevents this action is MinimumSameSitePolicy and to change that, you need to apply following configuration in your startup:

internal static WebApplication UseMyCookiePolicy( this WebApplication app )
{
    app.UseCookiePolicy(
        new CookiePolicyOptions
        {
            MinimumSameSitePolicy = SameSiteMode.None,
            Secure                = CookieSecurePolicy.Always,
            HttpOnly              = HttpOnlyPolicy.Always
        });

    return app;
}

You can read about it more on Microsoft documentations at: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/cookie?view=aspnetcore-6.0

Redirect URIs

When you divide your Identity service into two standalone applications that are served under different hosts, one obvious expectation is that you would have more complicated redirect Uris. Additionally, you need to have some PermanentRedirect responses from you backend server. For instance when the UI query to see if the user is logged in, in case the user is NOT logged in, the authentication middleware in backend tries to redirect the user to the login page within the backend application. But we know that our login page is being hosted elsewhere hence the permanent redirect.

Speaking of redirect Uris, we should not be afraid of nested redirect Uris. In some cases we reached up to 4 level nested redirect Uri when we attempt to login by external provider like Google. The important point here is to correctly encode those redirect Uris in the main Uri. Asp.Net Core intelligently decodes the action inputs and also encodes route values when redirecting to action. In frontend, using a promising library like qs can be an absolute time saver. For the sake of completeness, it might be worth mentioning that when encoding parameters of a Uri, you should be careful that the parameters are not already encoded. In which case, you get double encoding and of course wrong behavior. I'm sure you don't want to spend the amount of time I spent to debug that :)

Last round of fight: Kubernetes

Yes, that's right. When you finish dealing with all I mentioned above, there is one last thing we need to fight with. Of course this only applies if you want to deploy to K8s, otherwise the challenge might be different, but in my case, I wanted to deploy to K8s as it's easier to monitor and well adopted in my team.

This experience could also vary depending on you K8s cluster setup. In my case I was using not secure communication inside the cluster as the whole network is properly demilitarized behind firewalls. This could cause a serious issue as many part of OAuth and OpenID Connect specification required https always. Additionally, I had a reverse proxy in front of my cluster which will override the host of the request when forwarding the request to the pod. Nevertheless, I didn't want to give up this fight so early :)

As a solution, given all the conditions and issues I explained above, I decided to override every automatically inferred value based on host of the request. For instance the URL of the authority and token endpoint in the discovery document at /.well-known/openid-configuration. The would give me the flexibility to even change these Uris in the future easily. And it's now fully configurable for different environment such as Production, Staging or Development. Gladly, Openiddict comes with easy to use fluent API for configuring the server and you can simply set the issuer via a method call. But thing were not as easy as in Openiddict when it gets to login by Google authentication handler. :/

To override the google authentication handler you need to explore the code behind their easy to use AddGoogle(...) method. You will then find a class called GoogleHandler which is also responsible for building Uris. Gladly the two interesting methods are defined virtual so we can simple inherit from this class and override them. Not forget to mention the obvious that you need to have Microsoft.AspNetCore.Authentication.Google package installed. Here an example:

public class MyGoogleHandler : GoogleHandler
{
    private readonly IConfiguration _configuration;

    public MyGoogleHandler(
        IOptionsMonitor<GoogleOptions> options, ILoggerFactory logger,
        UrlEncoder                     encoder, ISystemClock   clock,
        IConfiguration                 configuration )
            : base(
                options, logger, encoder,
                clock)
    {
        _configuration = configuration;
    }

    protected override string BuildChallengeUrl( AuthenticationProperties properties, string redirectUri )
    {
        var newRedirectUri = "http://my-auth-server.com/loginByGoogle"; // or read from configuration
        return base.BuildChallengeUrl(properties, newRedirectUri);
    }

    protected override Task InitializeHandlerAsync()
    {
        // This ignores the fact that we have http communication inside the cluster and treat is as https
        Request.Scheme = "https";
        // Request.Host is also modifiable at this point 
        return base.InitializeHandlerAsync();
    }
}

After this, you need to find the correct way for registering you handler instead of the default one. And there was the place where I crawled the internet and found nothing, then decide to go actually read the code behind the registration to finally find the correct approach. Luckily you don't have to spend that much time to find it :) here is the code: (don't forget the cookie configuration as explained above)

internal static void AddMyAuthentication(this IServiceCollection services, IConfiguration configuration)
{
    services.AddAuthentication()
        .AddOAuth<GoogleOptions, MyGoogleHandler>( // this is the important part
                    GoogleDefaults.AuthenticationScheme, GoogleDefaults.DisplayName, o => {
                        o.ClientId           = configuration["Authentication:Google:ClientId"];
                        o.ClientSecret       = configuration["Authentication:Google:ClientSecret"];
                        o.ReturnUrlParameter = "after";
                        o.CallbackPath       = "/loginByGoogle";
                        o.Scope.Add("https://www.googleapis.com/auth/userinfo.email");
                        o.Scope.Add("https://www.googleapis.com/auth/userinfo.profile");
                        o.ClaimActions.MapJsonKey("urn:google:picture", "picture", "url");
                        o.CorrelationCookie.SecurePolicy = CookieSecurePolicy.Always;
                        o.CorrelationCookie.SameSite     = SameSiteMode.None;
                        o.CorrelationCookie.Name         = "coockies.CorrelationCookie";
                    })
};

Conclusion

Building the service with the characteristics mentioned above, was stressful yet definitely fun. There are a lot of additional elements you need to consider which are not mentioned here. Even though this article is lengthy enough by nature, it's still just the scratch of the surface of what needs to be thought of when building a central identity service. For instance things like how best to design your database, how best to tackle database migrations and cleanup, How best to take care of registering OpenID clients and keep their configuration up to date, how to make the application stateless and scalable, how to take control over access token and reference token generations and using reference tokens, how to handle authorization by JWT token and reference token with introspection, secrets and certificates, dockerising, build automation and GitOps, and many more topics are not mentioned here while being crucial parts of the server.

I hope you enjoyed following along with my journey and learn something new. Say tuned for possible and probable future parts of this article including more challenges and their solutions.

Mohammadali Forouzesh - just a passionate software engineer
01/11/2022
LinkedIn - Instagram