Forem: Palomino

Automate your custom sign-in UI deployment with GitHub Actions workflow

Palomino — Fri, 20 Sep 2024 01:07:11 +0000

Let's show you how to automate the deployment of your custom sign-in UI to Logto Cloud in your devops pipeline with a GitHub Actions workflow.

Background

Logto is your better choice of Customer Identity and Access Management (CIAM) solution. Recently, we launched the "Bring your own UI" feature on Logto Cloud, enabling developers to fully customize their sign-in UI.

In a previous blog post, we also provided a step-to-step guide on creating your own sign-in UI, which includes:

Developing a custom sign-in page with code samples
Setting up the @logto/tunnel CLI for local debugging
Building and zipping your custom UI assets
Uploading the zip package and deploying to Logto Cloud via the Console UI

However, as an app developer with a DevOps mindset, you may find this process cumbersome when making changes to your custom sign-in page. Is there a way to automate the entire process?

We’ve listened to your feedback, and are excited to introduce a new deploy CLI command in @logto/tunnel. This command allows you to automate the deployment process by executing the command in your terminal, or integrating it into a GitHub Actions workflow, which is particularly useful for building your CI/CD pipeline. Let's dive in!

Prerequisites

Before we dive into the setup, ensure you have the following:

Logto Cloud account with subscription plan.
A machine-to-machine application with Management API permissions in your Logto tenant.
Your project source code should be hosted on GitHub.
Install @logto/tunnel CLI tool as a dev dependency in your project.

npm install --save-dev @logto/tunnel

Step 1: Create a GitHub Actions workflow

In your GitHub repository, create a new workflow file. You can do this by navigating to .github/workflows/ and creating a file named deploy.yml.

name: Deploy to Logto Cloud

on:
  push:
    branches:
      - main # Change it to "master" if that's the name of your default branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy to Logto Cloud
        env:
          LOGTO_AUTH: ${{ secrets.LOGTO_AUTH }} # Your M2M credentials. E.g. `<m2m-app-id>:<m2m-app-secret>`.
          LOGTO_ENDPOINT: ${{ secrets.LOGTO_ENDPOINT }} # Your Logto endpoint.
          LOGTO_RESOURCE: ${{ secrets.LOGTO_RESOURCE }} # Your Logto resource. Required if custom domain is enabled in your Logto Cloud tenant.
        run: npx logto-tunnel deploy --path ./dist # Change "./dist" to your actual build output folder if necessary.

Explanation of the GitHub Actions workflow

Trigger: The workflow is triggered on every push to the main branch.
Jobs: The deploy job runs on the latest Ubuntu environment, and will execute the follow steps.
Steps:
- Checkout code: This step checks out your repository code.
- Set up Node.js: This step sets up the Node.js environment.
- Install dependencies: This step installs your project dependencies.
- Build: This step builds your project source code into html assets. Let's assuming the output folder is named dist in the root directory.
- Deploy to Logto Cloud: This step runs the Tunnel CLI command to deploy html assets in ./dist directory to your Logto Cloud tenant. It uses environment variables for sensitive information.

For more information on GitHub Actions. visit the GitHub Actions Documentation.

Step 2: Configure action secrets in GitHub

To keep your credentials secure, you should store them as secrets in your GitHub repository:

Go to your GitHub repository.
Click on "Settings".
Navigate to "Secrets and variables > Actions"
Click on New repository secret and add the following secrets:
- LOGTO_AUTH: Your Logto M2M application credentials in the format <m2m-app-id>:<m2m-app-secret>.
- LOGTO_ENDPOINT: Your Logto Cloud endpoint URI.
- LOGTO_RESOURCE: Your Logto Management API resource indicator. Can be found in "API resources -> Logto Management API". Required if custom domain is enabled in your Logto Cloud tenant.

Step 3: Test your workflow

Once you have set up the workflow and configured the secrets, you can test it by merging a PR into the master branch. The GitHub Actions workflow will automatically trigger, and your custom sign-in UI will be deployed to Logto Cloud.

Conclusion

By integrating the @logto/tunnel CLI command into your GitHub Actions workflow, you can streamline the deployment process of your custom sign-in UI to Logto Cloud. This automation allows you to focus on development while ensuring that your changes are continuously tested in a live environment.

Happy coding!

Try Logto Cloud for free

5 go-to-market lessons I learned from driving a developer-led growth product

Palomino — Thu, 19 Sep 2024 06:41:50 +0000

Lessons and practices learned in driving Logto’s growth with developers.

Logto is an open-source, developer-focused product. Here’s our go-to-market timeline:

We released the open-source version in July 2022.
In January 2023, we launched the cloud preview (beta cloud).
By July 2023, it was production-ready with full pricing.

Coming from a background in product-led growth for productivity tools, the teams and I tried different go-to-market strategies for Logto. After two years, I’ve reflected on those efforts and the steps we took. I want to share part of that journey and explain why some things didn’t work at the time. These aren’t “mistakes,” but valuable lessons from our experience. I hope these insights help others working on similar projects or startups.

Traditional onboarding strategies may not work

Job-to-be-done onboarding, so users can solve their problems right away.
During onboarding, include options like “book a call” or “email us” for human outreach to increase conversion rates—something that works well with bigger businesses.

These strategies had been very successful in my past experience. So when Logto launched its cloud-hosted version, I applied them immediately. However, I encountered some confusion and challenges:

What exactly is Logto’s “Job-to-be-done”? Unlike straightforward products like productivity tools (e.g., writing documents or creating artwork), Logto deals with building authentication systems or managing user identities. But how can users achieve this in just a day?
Sure, we added a Calendly link for scheduling calls, but we didn’t receive many bookings, and it didn’t boost our conversion rate as expected.

Why #1 Doesn't Work

For developer products, it’s difficult to solve a problem in a short time even if it can be truly self-serve. Even for a single developer, the process involves several stages: integrating with the right tech stack, creating a proof of concept, testing in a development environment, and then moving to production. At any point in this journey, users can drop off. The "job-to-be-done" isn’t a simple, one-step task. Developer needs are often complex, requiring a range of features or technical scenarios that need thoughtful design leveraging our existing capabilities. Solving such problems takes time and can’t be rushed.

Why #2 Doesn't Work

Looking back, it’s clear why this approach didn’t succeed. When we first launched, our daily sign-ups and organic traffic were quite low. Most of our traffic came from the open-source community, which naturally didn’t bring in larger clients. It’s no surprise we didn’t see bigger clients booking calls during this stage. The low traffic and the source of our users made it unrealistic to expect significant call bookings early on.

Freemium or free trial? Before struggling, understand your product first

Choose the model that fits your product, based on the time needed for user activation. Don’t let industry norms restrict you.

When building a SaaS product, one of the key go-to-market (GTM) questions is whether to choose freemium or a free trial. Common wisdom suggests:

Free Trial: Users get full access for a limited time, then must pay to continue.
- Best for: Complex or premium products where users need to experience the full features to see the value.
Freemium: Users access a basic version for free, with paid upgrades for advanced features.
- Best for: Products with a wide range of features, where free users may upgrade as their needs grow.

We initially chose a freemium model for a quick launch, placing a hard paywall between the free and paid plans. However, developers couldn’t access advanced features like SSO or Organization in the free tier.

While there’s plenty of debate online about which model is better, it’s crucial to step back and consider your product’s activation timeline. For Logto, we’ve observed that in real world, the testing phase can last up to 6 months. This isn’t due to complexity of Logto but rather the engineer’s work schedule, project planning, team workflows, and other factors we hadn’t anticipated.

Given this long activation period, it’s important to provide developers full access to all features for testing. That’s why we fully utilize the development tenant to unlock the product’s full capabilities. This is common practice for developer tools but worth noting as it explains why traditional freemium or free trial strategies may not work for us.

The choice should align with the nature of your product and its adoption timeline. Understand your product’s unique characteristics, and choose a model that fits—not one that pushes users too quickly through your conversion funnel.

If you don't understand your customers, your content will come across as self-centered

Executing a GTM with a bottom-up strategy often involves SEO, product marketing, and content marketing. We all know it’s important to start early, so we began creating content right after launching the open-source version. But when we first decided to write articles, I had a big question: What should I write?

As a product designer, my instinct was to write about why we designed certain features, explaining the thought process and philosophy behind them.

"In this article, we'll go over the history of Sign-in Experience, including its conception, design decisions, and product tradeoffs. You will also gain a better grasp of how to construct a successful and frictionless sign-in or sign-up experience." - Our blog post 2 years ago The design considerations for a seamless sign-in experience (First Chapter)

I was eager to share my thoughts on our features and design because I put so much effort into them. But looking back, I realize this is what you'd call "self-absorbed" content. It's common in well-established companies with a strong EPD (Engineering, Product, Design) culture.

If you’re doing product-led growth (PLG), especially when your product hasn’t yet reached the stage where "people are talking about you," it’s necessary to ensure your content has clear value and a goal for your audience. Avoid being too self-focused.

For instance, instead of focusing on why a feature was designed, create educational articles that explain specific terms, or tutorials that show how to integrate a cool technology or tool to solve a common technical issue.

As you learn more about your product and customers, you’ll naturally develop strong opinions about what really matters to your audience. Keeping a “customer-centric” approach will help you improve content quality. Over time, you’ll be able to write content that resonates with your audience. Otherwise, your content risks feeling self-absorbed.

Features or best practice

Traditional marketing often emphasizes “best practices” or “solutions” when selling to businesses or individuals, based on the idea that SaaS products primarily drive efficiency and productivity. Many strategies focus on numbers, showing financial savings to highlight benefits. While this can work well for mature companies with a broad customer base, it can be off-putting for developers.

Two years ago, I focused heavily on building value propositions and crafting a big-picture narrative for our product. However, this approach didn’t always connect with the developer audience.
Look at the webpage we had 2 years ago—"Shaping the future"… Wow!
When it comes to satisfying developers and solving their problems, you need to be very practical and grounded. Developers aren’t swayed by lofty benefits; they care about feature availability and flexibility—specifically, how easily your product can integrate into their existing tech stack. If it can’t, don’t try to sell it.

Now, our content strategy is much more focused. We highlight the specific features we deliver, allowing users to quickly understand what we offer from the first screen, without relying on buzzwords or high-level messages.

Is the open-source version a threat to the commercial version?

When we first launched our hosted commercial version, there was always a heated discussion within the team: Would open-source hurt our hosted version since it's free, and our target audience is developers? We also debated whether to limit some of our advanced features in the open-source version.

So far, we've kept the core features of both the open-source and hosted versions almost the same. The growth of our open-source community has built significant trust with enterprise leads, and more larger businesses are coming onboard. Interestingly, some of these enterprises started out as developers in our community. This has given us a lot of confidence. As long as we continue to build great products, provide excellent services, and help developers solve their problems, whether it's through self-serve growth or direct enterprise sales, success will come naturally.

In the end, it’s all about solving developer problems, whether through product or service. Stay patient and focused, and everything will fall into place naturally.

Thanks for reading, and feel free to share your experiences and thoughts if you’re working on something similar!

Try Logto Cloud for free

Opaque token vs JWT

Palomino — Wed, 11 Sep 2024 06:34:59 +0000

Understand the differences between opaque tokens and JWTs, their use cases, and how they are validated in OIDC-based systems.

In Logto, as an OIDC-based comprehensive CIAM platform, authorization tokens play a crucial role in securing user interactions and managing access to resources. Among the various types of tokens used for authorization, opaque tokens and JWTs (JSON Web Tokens) are the most important.

We've received several questions from our community, such as: What is the difference between an opaque token and a JWT? Why can't I decode the access token I received, and why does the token length seem short? This blog post aims to clarify these concepts and help you understand the distinctions between opaque tokens and JWTs, their use cases, and why you might encounter different behaviors when working with them.

What is an opaque token?

An opaque token is a type of access token that, as the name suggests, is opaque or non-transparent to the client or any external party. This means that the token itself does not carry any readable information about the user or the authorization granted.

When you receive an opaque token, it often appears as a seemingly random string of characters, and attempting to decode it will yield no meaningful data.

Here's an example of an opaque token:

JjVXhOl3UiWBMDdvS3Dt0bFjRlrkNDIsANSrS_7AUGg

Since the actual content of the token is only known to the authorization server that issued it, to validate an opaque token, the client must send it back to the server, which then verifies its authenticity and determines the associated permissions. This approach ensures that sensitive information remains hidden, providing an extra layer of security, but it also requires additional server communication to validate the token.

Pros:

secure: Opaque tokens do not expose any sensitive information to the client. The token's content is only known to the authorization server.
revocable: Since the token is stored on the server, and the only way to validate it is through the introspection endpoint on the authorization server, the server can easily revoke the token if needed and prevent unauthorized access.
small size: Opaque tokens are typically shorter than JWTs, which can be beneficial for performance and storage considerations.

Cons:

stateful: Opaque tokens require the authorization server to maintain state to validate the token, which can introduce additional complexity and overhead.
performance: The need for additional server communication to validate the token can impact performance, especially in high-traffic scenarios.

What is a JWT?

In contrast to opaque tokens, a JWT (JSON Web Token) is a self-contained, stateless token that carries information in a structured and readable format.

A JWT is composed of three parts: a header, a payload, and a signature, each encoded in Base64URL.

Here's an example of a JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The header contains information about the type of token and the algorithm used for signing. For example, {"alg": "HS256", "typ": "JWT"}.
The payload section contains claims—pieces of information about the user or the authorization—such as user ID, expiration time, and scopes. Because this data is encoded but not encrypted, anyone who has the token can decode it to see the claims, though they cannot alter it without invalidating the signature. Based on the specification and authorization server configuration, various claims can be included in the payload. This gives the token its self-contained nature. For example, {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}.
The signature is generated by combining the header, payload, and a secret key using the specified algorithm. This signature is used to verify the integrity of the token and ensure that it has not been tampered with.

JWTs are commonly used because they can be verified locally by the client or any service, without needing to interact with the authorization server. This makes JWTs particularly efficient for distributed systems, where multiple services might need to verify the token's authenticity independently.

However, this convenience also comes with the responsibility of ensuring that the token's claims are not excessively exposed, as they are visible to anyone who has access to the token. Also, JWTs are typically short lived, and the expiration time is included in the token's claims to ensure that the token is not valid indefinitely.

Pros:

stateless: JWTs are self-contained and do not require server-side state to validate.
cross-service compatibility: JWTs can be easily shared and verified across different services, making them ideal for distributed systems.
extensible: The payload of a JWT can contain custom claims, allowing for flexible authorization and information sharing.
standard: JWT tokens follow a well-defined standard (RFC 7519), making them widely supported and interoperable.

Cons:

exposure: The claims in a JWT are visible to anyone who has access to the token, so sensitive information should not be included in the payload.
large size: JWTs can be larger than opaque tokens due to the additional information they carry, which can impact performance and storage considerations. The claims in a JWT tokens should be kept to a minimum to reduce the token size.
revocation complexity: Since JWTs are stateless, they are typically valid for a short period of time, and there is no built-in mechanism for revoking tokens before they expire, meaning that a compromised token may remain valid until it expires.

Opaque access token validation

A opaque access token is validated by sending it back to the authorization server for verification. The authorization server maintains the state of issued tokens and can determine the token's validity based on its internal storage.

The client requests an access token from the authorization server.
The authorization server issues an opaque token.
The client sends the resource access request with the opaque token in the header.
The resource provider sends a token introspection request to the authorization server to validate the token.
The authorization server responds with the token information.

JWT access token validation (offline)

A JWT access token can be validated offline by the client or any service that has access to the token's public key.

0.The resource provider pre-fetches the authorization server's public key from the OIDC discovery endpoint. The public key is used to verify the token's signature and ensure its integrity.
1.The client requests an access token from the authorization server.
2.The authorization server issues a JWT token.
3.The client sends the resource access request with the JWT token in the header.
4.The resource provider decodes and validates the JWT token using the public key obtained from the authorization server.
5.The resource provider grants access based on the token's validity.

Use cases in OIDC

In the context of OIDC (OpenID Connect), opaque tokens and JWTs serve different purposes and are used in distinct scenarios.

Opaque tokens

User profile retrieval:
By default, when a client requests an access token without specifying a resource and includes the openid scope, the authorization server issues an opaque access token. This token is primarily used to retrieve user profile information from the OIDC /oidc/userinfo endpoint. Upon receiving a request with the opaque access token, the authorization server checks its internal storage to retrieve the associated authorization information and verifies the token's validity before responding with the user profile details.
Refresh token exchange:
Refresh tokens are designed to be exchanged only between the client and the authorization server, without needing to be shared with resource providers. As such, refresh tokens are typically issued as opaque tokens. When the current access token expires, the client can use the opaque refresh token to obtain a new access token, ensuring continuous access without re-authenticating the user.

JWTs

1.ID token:
In OIDC, the ID token is a JWT that contains user information and is used to authenticate the user. Typically issued alongside the access token, the ID token allows the client to verify the user's identity. For example:

// Decoded payload of an ID token
{
  "iss": "https://logto.io",
  "sub": "1234567890",
  "aud": "client_id",
  "exp": 1630368000,
  "name": "John Doe",
  "email": "john.doe@mail.com",
  "picture": "https://example.com/johndoe.jpg"
}

The client can validate the ID token to ensure the user's identity and extract user information for personalization or authorization purposes. ID token is for one-time use only and should not be used for API resource authorization.

2.API resource access:
When a client requests an access token with a specific resource indicator, the authorization server issues a JWT access token intended for accessing that resource. The JWT contains claims that the resource provider can use to authorize the client's access. For example:

// Decoded payload of a JWT access token
{
  "iss": "https://dev.logto.app",
  "sub": "1234567890",
  "aud": "https://api.example.com",
  "scope": "read write",
  "exp": 1630368000
}

The resource provider can validate the request by checking the claims:

iss: Confirms the token was issued by a trusted authorization server.
sub: Identifies the user associated with the token.
aud: Ensures the token is intended for the specific resource.
scope: Verifies the permissions granted to the user.

Conclusion

In summary, opaque tokens and JWTs serve different purposes in OIDC-based systems, with opaque tokens providing a secure and stateful approach to authorization and JWTs offering a self-contained and stateless alternative. Understanding the distinctions between these token types and their use cases is essential for designing secure and efficient authentication and authorization mechanisms in your applications.

Discover more access token features in Logto:

Try Logto Cloud for free

Conventional commits won't save your commit messages

Palomino — Wed, 11 Sep 2024 03:03:48 +0000

Explore why simply following conventional commits isn't enough to write good commit messages, and introduce key thinking strategies to improve your development process and naturally create meaningful commits.

A quick search on the internet will reveal a plethora of articles teaching you how to write commit messages. 90% of these articles tell you to use conventional commits. However, a considerable number of developers still struggle with this. They know they should follow these conventions, but they find it difficult to apply them in practice. Every time they commit code, they agonize over whether to write "refactor" or "chore". I've even seen projects where the commit message list consists entirely of the same message: "feat: add page", because writing commit messages was too challenging for them, and they simply gave up.

It's too early to talk about conventional commits

I'm not saying that conventional commits are bad. They have many well-known benefits:

They provide a unified format, making commit messages more standardized
They are easy for automated tools to parse, enabling automatic changelog generation
They help team members understand the purpose and scope of code changes
They allow for quick identification of different types of code changes

However, when a developer is still struggling to write good commit messages even after using conventional commits, throwing an article at them about how to use conventional commits, teaching them what feat type means, what fix type means, is actually meaningless. It's like giving an advanced cookbook to someone who doesn't know how to cook, without teaching them how to use basic ingredients and utensils. Yet, such articles are everywhere on the internet. Little do they know, conventional commits can only truly be effective when developers have clear thinking and the ability to divide tasks precisely.

So, conventional commits aren't bad, but before we get to that, we need to establish the right development mindset and use scientific developer thinking to do things.

Key thinking for writing good commit messages

Code changes should do one thing at a time

In software development, "do one thing at a time" is an important principle. This applies not only to writing code but also to committing code. When we focus on one specific task or change at a time, our code becomes clearer and our intentions more explicit. This method not only improves code readability but also greatly simplifies the code review process. Reviewers can more easily understand and verify the purpose of each change.

Moreover, this method provides convenience for potential code rollbacks. If problems occur, we can more easily locate and revert specific changes without affecting other unrelated parts. Most importantly, when each change does only one thing, the commit message describing this change naturally becomes more precise and meaningful.

In practice, this means we need to clearly define the task to be completed before we start coding. After completing a task, we should immediately commit the code, rather than waiting until multiple tasks are completed before committing together. If we discover other areas that need modification while completing the current task, the best approach is to note them down and handle them separately after completing the current task. For example, when you're implementing a feature and discover some existing bugs, what you should do is not fix the bug right away along with your new feature code, but rather implement the feature first, then fix the bug you discovered in another commit, or fix the bug first and then commit the feature.

Commit messages actually exist before writing code

Many developers only start thinking about how to write commit messages after completing the code, but in reality, commit messages should exist before we start coding. This is because commit messages essentially reflect the steps we take to complete a task. In other words, they are our todo items.

When we start a task, we should first think about what specific steps are needed to complete this task. These steps are our todo list, and at the same time, they are our future commit messages. With this todo list, each of our code changes has a purpose, keeping us focused while coding and preventing us from deviating from the task.

More importantly, this method can significantly improve our efficiency. When we complete a step, the corresponding commit message is already prepared, and we can use it directly, reducing the time spent on thinking about how to describe the change. At the same time, because these commit messages are completed when we have a comprehensive understanding of the task, they are usually of higher quality and more informative.

Suppose you need to implement a new user registration feature. You might plan your task steps like this:

Refactor the existing form component to make it more generic and reusable
Create a user registration form
Implement API integration for user registration
Add unit tests for the user registration feature
Update documentation for the user registration feature

The commit messages corresponding to these task steps might be as follows:

refactor: enhance existing form component for reusability
feat: create user registration form
feat: implement user registration API integration
test: add unit tests for user registration
docs: update documentation for user registration feature

In this way, you have clear task steps and corresponding concise commit messages before you start coding. These commit messages are actually your todo list, guiding you through the entire process of implementing the feature.

As you complete each step, you can use the corresponding commit message to commit your code. This not only helps you better organize and execute tasks, but also ensures that each commit focuses on a specific step, making the entire development process clearer and more manageable. If you need to slightly adjust the commit message during actual coding, you can make minor modifications to more accurately describe the actual changes.

Conventional commits become a natural choice

When we develop the right development mindset, using conventional Commits becomes natural. At this stage, you'll find that choosing the appropriate type prefix (such as feat, fix, refactor, etc.) becomes effortless because your commit messages already clearly reflect your task steps.

If you want to learn more about how to use conventional commits, there are many excellent articles available online. But remember, these standards can only truly be effective when built on the foundation of the right development mindset.

Conclusion

Writing good commit messages is not just about following a certain format. It requires us to maintain clear thinking during the development process, clarify the purpose of each change, and consider how to describe our work before we start coding.

Conventional commits is indeed a useful tool, but it can only exert its maximum effect when combined with the right development mindset. By practicing the two principles of "do one thing at a time" and "think about commit messages in advance", we can not only improve the quality of commit messages but also enhance overall development efficiency and code quality.

I hope this article helps you rethink your development process and encourages you to try these methods. Remember, good development habits take time to cultivate, but once formed, they will greatly improve your work efficiency and code quality.

Try Logto Cloud for free

When should I use JWTs?

Palomino — Wed, 04 Sep 2024 00:31:43 +0000

A comprehensive guide on the pros and cons of using JWTs for authentication, with emphasis on auth provider services like Logto.

Ah, JSON Web Tokens (JWTs) - the topic that seems to spark a heated debate in the developer community every few months like clockwork! These little tokens have become quite the popular choice for authentication in modern web apps. But here's the thing: while developers love to argue about their pros and cons, the landscape of authentication is constantly evolving. So, let's cut through the noise and take a balanced look at JWTs. We'll explore when they shine, where they might fall short, and help you figure out if they're the right fit for your project.

Understanding JWTs

JWTs are compact, self-contained tokens used to securely transmit information between parties as a JSON object. They're commonly used for authentication and information exchange in web development.

Key features of JWTs

Stateless: They don't require server-side storage
Portable: Can be used across different domains
Secure: When implemented correctly, they provide robust security

The JWT debate

The controversy surrounding JWTs centers on several key points:

Scalability vs. complexity

Pro: JWTs excel in large-scale, distributed environments.

Con: They can introduce unnecessary complexity for smaller applications.

JWTs are particularly well-suited for systems that need to handle authentication across multiple servers or services. Their stateless nature means that each server can independently verify the token without needing to consult a centralized session store. This makes JWTs an excellent choice for microservices architectures, cloud-based systems, and applications that require horizontal scaling.

Security considerations

Pro: JWTs can be securely implemented, especially with auth provider services.

Con: Incorrect implementation can lead to vulnerabilities if not using a trusted service.

When implemented correctly, JWTs offer robust security features. They can be digitally signed to ensure integrity and optionally encrypted to protect sensitive information. However, it's crucial to recognize that a flawed implementation can introduce serious vulnerabilities. Common pitfalls include using weak signing algorithms, improper key management, or failing to validate tokens properly.

Implementation challenges

Pro: Auth provider services offer simplified, secure JWT implementation.
Con: Secure implementation from scratch can be complex and time-consuming.

Leveraging auth provider services can significantly reduce the complexity of implementing JWTs. These services handle intricate aspects such as token signing, validation, and cryptographic key management. They often provide well-documented SDKs and APIs, making it easier for developers to integrate secure authentication into their applications. On the flip side, attempting to implement a JWT system from scratch requires a deep understanding of cryptographic principles, secure coding practices, and potential attack vectors, which can be a daunting and time-consuming task for many development teams.

Auth provider services like Logto have significantly simplified the implementation of JWTs in several ways:

Simplified setup: They handle the complexities of JWT implementation, making it accessible even for smaller projects.
Enhanced security: These services implement industry-standard security measures, reducing the risk of vulnerabilities.
Scalability: They offer solutions that can grow with your application's needs.
Maintenance: Regular updates and security patches are handled by the service provider.

By using these services, developers can focus on building their core application features while leaving the intricacies of JWT implementation to the experts.

When to use JWTs

JWTs can be particularly beneficial in the following scenarios:

Microservices architecture: For stateless authentication across multiple services.
Single sign-on (SSO) systems: Enabling access to multiple applications with one authentication.
Mobile applications: Efficiently maintaining user sessions across API calls.
High-traffic applications: Reducing database load in high-volume environments.
Cross-origin resource sharing (CORS): Simplifying authentication across multiple domains.
Serverless architectures: Providing stateless authentication where server-side sessions are challenging.

Alternatives to consider

For simpler authentication needs, consider these alternatives:

Traditional session-based authentication: Often sufficient for smaller applications.
Token-based authentication with server-side storage: Combines token flexibility with server-side security.
OAuth 2.0 with opaque tokens: Suitable for delegated authorization scenarios.
API keys: For simple machine-to-machine authentication.

Making the decision

While JWTs offer powerful capabilities, there are situations where they may not be necessary or even advisable:

Simple, low-traffic applications: For small projects with minimal authentication needs, traditional session-based authentication might be simpler and more than sufficient.
Applications with no cross-domain requirements: If your application doesn't need to share authentication across multiple domains or services, JWTs may add unnecessary complexity.
Projects with limited development resources: Implementing JWTs securely from scratch can be resource-intensive. If you lack the expertise or time, simpler alternatives might be more appropriate.
Applications with strict security requirements: In some cases, server-side sessions might be preferred for their ability to be immediately invalidated, which isn't natively possible with JWTs.
Scenarios where token size is a concern: JWTs can be larger than other token types, which might be an issue in bandwidth-constrained environments.

However, it's important to note that with the advent of mature authentication tools and services, implementing JWTs has become much more accessible. Services like Logto provide out-of-the-box JWT support with industry-standard security measures, making it feasible for projects of any size to leverage the benefits of JWTs without the associated complexities.

By using such tools, even smaller projects or those with limited resources can implement robust, scalable authentication systems that can grow with their needs. This approach allows you to focus on your core application logic while benefiting from the flexibility and potential scalability that JWTs offer.

Try Logto Cloud for free

Bring your own sign-in UI to Logto Cloud

Palomino — Tue, 03 Sep 2024 23:39:40 +0000

This tutorial will guide you through the process of creating and deploying your own custom sign-in UI to Logto Cloud.

Background

Logto provides an out-of-box sign-in experience UI that covers all Logto features, including sign-in, registration, password recovery, single sign-on (SSO), and more. Users can also customize the look and feel of the sign-in experience UI using our "Custom CSS" feature.

However, some users still want to deeply customize their sign-in experience (both UI and auth flows) to match their branding and specific business requirements. We've heard you! And we're excited to announce that the "Bring your own UI" feature is now available in Logto Cloud.

In this tutorial, we'll guide you through the steps to create and deploy your own custom sign-in UI to Logto Cloud.

Prerequisites

Before you start, ensure you have the following:

A Logto Cloud account with a subscription plan
An application integrated with Logto (Quick-starts)
Logto tunnel CLI installed
Basic knowledge of HTML, CSS, and JavaScript

For simplicity, we will use the classic "username & password" sign-in method in the following steps. Remember to change your sign-in method in Logto Console.

Create your custom sign-in UI

The minimum requirement for a sign-in UI is to have an index.html file, with a sign-in form that includes at least a username input, a password input, and a submit button. I used ChatGPT to generate a sample HTML, and here I come with this pinky lovely sign-in page.

I have omitted the CSS styles for simplicity, and here is how simple the HTML looks like:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Fun Sign-in Page</title>
  </head>
  <body>
    <div>
      <h1>Welcome Back</h1>
      <form id="signInForm">
        <div>
          <label for="username">Username</label>
          <input type="text" name="username" required />
        </div>
        <div>
          <label for="password">Password</label>
          <input type="password" name="password" required />
        </div>
        <button type="submit">Sign in</button>
      </form>
    </div>
  </body>
</html>

You can also start with a boilerplate from your favorite front-end framework, such as Create React App, Next.js, or Vue CLI.

Since Logto is open source, another recommendation is to clone the Logto Experience project, and modify the code to fit your needs. This is the full feature Logto built-in sign-in experience UI, written in React and TypeScript.

Setup Logto tunnel CLI

Logto tunnel CLI is a tool that not only servers your HTML pages, but also allows you to interact with Logto's Experience API from your HTML pages in local dev environment.
Assuming your index.html page is located in /path/to/your/custom-ui, and your Logto tenant ID is foobar, you can run the command this way:

npx @logto/tunnel --path /path/to/your/custom-ui --endpoint https://foobar.logto.app/ -p 9000

Or, if you are using a UI framework that has a built-in development server, and your page is served at http://localhost:4000, you can run the command like this:

npx @logto/tunnel --uri http://localhost:4000 --endpoint https://foobar.logto.app/ -p 9000

After running the command, the tunnel service will be started on your local machine http://localhost:9000/.

Trigger sign-in from your application

Go to the application you created earlier, and change the Logto endpoint from https://foobar.logto.app/ to http://localhost:9000/ in your Logto SDK config.

Let's take our React sample project as an example:

import { LogtoProvider, LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // endpoint: 'https://foobar.logto.app/', // original Logto Cloud endpoint
  endpoint: 'http://localhost:9000/', // tunnel service address
  appId: '<your-application-id>',
};

const App = () => (
  <LogtoProvider config={config}>
    <YourAppContent />
  </LogtoProvider>
);

Click the "Sign in" button in your application. Instead of seeing the built-in Logto sign-in UI, you should now be redirected to your custom sign-in page.

Interact with Logto Experience API

In this step, we will interact with Logto Experience API in your custom UI. First, let's create a script.js file and add the reference in your index.html.

<html>
  <!-- Omitted code ... -->
  <body>
    <!-- Omitted code ... -->
    <script src="script.js"></script>
  </body>
</html>

Put the following code in your script.js file.

window.onload = function () {
  const form = document.getElementById('loginForm');
  form.addEventListener('submit', async function (event) {
    event.preventDefault();
    const formData = new FormData(event.target);

    try {
      await fetch('/api/experience', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ interactionEvent: 'SignIn' }),
      });

      const verificationResponse = await fetch('/api/experience/verification/password', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          identifier: { type: 'username', value: formData.get('username') },
          password: formData.get('password'),
        }),
      });

      const { verificationId } = await verificationResponse.json();

      await fetch('/api/experience/identification', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ verificationId }),
      });

      const submitReponse = await fetch('/api/experience/submit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
      });

      const { redirectTo } = await submitReponse.json();
      window.location.replace(redirectTo);

    } catch (error) {
      console.error('Oops!', error);
    }
  });
};

This script will complete the username and password sign-in flow with the help of these APIs:

PUT /api/experience - Start the sign-in interaction
POST /api/experience/verification/password - Verify the username and password
POST /api/experience/identification - Identify user for the current interaction
POST /api/experience/submit - Submit the sign-in interaction Refer to Logto Experience API docs for more details.

Test your custom sign-in page

Go to your application and click the "Sign in" button.
You should be redirected to your custom sign-in page at http://localhost:9000/.
Enter username and password, and click the "Submit" button.
If everything is set up correctly, you should be redirected back to your application, with authenticated user information.

Deploy your custom sign-in UI to Logto Cloud

Once you have finished developing and testing your custom sign-in UI locally, you can deploy it to Logto Cloud. Simply create a zip file of your custom UI folder and upload it to the "Custom UI" section in your Logto Console.

After uploading, save the changes, and your custom sign-in UI will go live in your Logto Cloud tenant, replacing the built-in Logto sign-in experience.

Finally, go back to your application and change the endpoint URI back to your Logto cloud endpoint: https://foobar.logto.app/. This time, you can stop the Logto tunnel service, and your application should now work directly with the custom UI hosted online.

Conclusion

In this tutorial, we've walked you through the process of implementing and deploying your own custom sign-in UI to Logto Cloud.

With this feature, you can now deeply customize your sign-in UI and auth flows to match your branding and specific business requirements.

Happy coding! 🚀

Try Logto Cloud for free

Color palette in branding: How Logto generate a custom color scheme for your brand

Palomino — Wed, 28 Aug 2024 01:05:15 +0000

How audiences perceive a brand is strongly influenced by color psychology. By using a carefully crafted color palette, brand recognition can be enhanced, leaving a lasting impression. To achieve this, we've developed a system that generates harmonious color schemes from a single base color, utilizing the HSL color model.

Color psychology plays a significant role in how audiences perceive a brand. A well-crafted color palette can enhance brand recognition and leave a lasting impression. To achieve this, we've developed a system that leverages the HSL color model to generate harmonious color themes from a single base color. In this post, we'll uncover the secrets behind our color generation process.

What is the HSL color model?

The HSL (Hue, Saturation, Lightness) color model is a widely used representation in digital design, particularly because of its intuitive approach to color manipulation. HSL separates the chromatic aspects of color into three distinct components:

Hue:
Hue refers to the type of color we see and is represented as a degree on a 360° circle. Each angle corresponds to a specific color on the color wheel—0° is red, 120° is green, 240° is blue, and so on. By adjusting the hue value, you can shift from one color to another, making it a powerful tool for generating complementary or analogous color schemes.
Saturation:
Saturation determines the intensity or purity of the color. It ranges from 0% to 100%, where 0% represents a completely desaturated color, essentially a shade of gray, and 100% represents the full, vibrant color. Adjusting the saturation allows designers to create both vivid and muted versions of the same hue, which is particularly useful for creating color hierarchies or emphasizing certain elements.
Lightness:
Lightness controls the brightness of the color, ranging from 0% (black) to 100% (white). At 50% lightness, the color is at its purest; as you move towards 0% or 100%, the color becomes darker or lighter, respectively. This is particularly useful in creating different shades and tints of a base color, which can be used to define visual depth and contrast within a design.

Why it is important to use the HSL color model?

In the context of Logto, using the HSL model allows for flexible and dynamic color theme generation. When a customer inputs their branding color, HSL makes it easier to calculate related color families—variations in lightness and saturation of the base hue. This capability ensures that the generated theme remains consistent and harmonious, reinforcing the brand's identity while ensuring an optimal user experience. The HSL model's intuitive nature also allows for more granular control over color adjustments, making it a preferred choice for designers and developers alike.

The color palette in Logto

Our color palette model is designed based on the HSL color space. Starting with a primary color and generate color families by adjusting the hue, saturation, and lightness values. This approach ensures that all colors in the palette are visually compatible and create a harmonious brand experience.

Here's a example of the default color palette model we are using in the sign-in experience product:
In the frontend code base, the essential color families are defined as CSS variables. For example, the primary color family is defined as follows:

--color-brand-30: #3C00C2; // hsla(253, 88%, 48%, 1);
--color-brand-40: #5d34f2; // hsla(253, 88%, 58%, 1);
--color-brand-50: #7C5CFF; // hsla(253, 88%, 68%, 1);

By referencing these variables in the CSS stylesheets, we can easily maintain a consistent visual style across the entire platform.

--color-brand-primary: var(--color-brand-40);
--color-brand-hover: var(--color-brand-50);
--color-brand-active: var(--color-brand-30);

Custom branding color palette generation

As mentioned earlier, developers may bring their own branding color to generate a custom branding color palette. To achieve this, we provide a simple color calculation unit that takes the base color and generates the corresponding color families.

Under the hood, we use color.js to manage the color manipulation process. The color generation function takes the base color, calculates the corresponding HSL values, and generates the color families HEX values accordingly.

Generate the base color element:

const baseColor = new Color(primaryColor);

Define the HSL based color calculation function:

export const absoluteLighten = (baseColor: color, delta: number) => {
  const hslArray = baseColor.hsl().round().array();

  return color([hslArray[0] ?? 0, hslArray[1] ?? 0, (hslArray[2] ?? 0) + delta], 'hsl');
};

export const absoluteDarken = (baseColor: color, delta: number) => {
  const hslArray = baseColor.hsl().round().array();

  return color([hslArray[0] ?? 0, hslArray[1] ?? 0, (hslArray[2] ?? 0) - delta], 'hsl');
};

Generate the color families:

const colorPalette = {

  ['--color-brand-hover']: absoluteLighten(baseColor, 10).hex(),
  ['--color-brand-active']: absoluteDarken(baseColor, 10).hex(),
};

Easy, right? Repeating the above steps we can generate a custom color palette for any branding color. This approach ensures that the generated color palette remains consistent with the brand's identity while providing a visually appealing experience for users.

Try Logto Cloud for free

Create a remark plugin to extract MDX reading time

Palomino — Wed, 28 Aug 2024 00:09:20 +0000

A guide to create a remark plugin to make the reading time data available when importing MDX files as ES modules.

Remark is a powerful markdown processor that can be used to create custom plugins to transform markdown content. When parsing markdown files with remark, the content is transformed into an abstract syntax tree (AST) that can be manipulated using plugins.

For a better user experience, it's common to display the estimated reading time of an article. In this guide, we'll create a remark plugin to extract the reading time data from an MDX file and make it available when importing the MDX file as an ES module.

Get started

Let's start by creating an MDX file:

# Hello, world!

This is an example MDX file.

Assuming we are using Vite as the bundler, with the official @mdx-js/rollup plugin to transform MDX files, thus we can import the MDX file as an ES module. The Vite configuration should look like this:

import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    {
      // The `enforce: 'pre'` is required to make the MDX plugin work
      enforce: 'pre',
      ...mdx({
        // ...configurations
      }),
    },
  ],
});

If we import the MDX file as an ES module, the content will be an object with the default property containing the compiled JSX. For example:

const mdx = await import('./example.mdx');
console.log(mdx);

Will yield:

{
  // ...other properties if you have plugins to transform the MDX content
  default: [Function: MDXContent],

}

Once we have the output like this, we can are ready to create the remark plugin.

Create the remark plugin

Let's check out what we need to do to achieve the goal:

Extract MDX content to text for reading time calculation.
Calculate the reading time.
Attach the reading time data to the MDX content, make it available when importing the MDX file as an ES module.

Luckily, there are already libraries to help us with the reading time calculation and basic AST operations:

reading-time to calculate the reading time.
mdast-util-to-string to convert the MDX AST to text.
estree-util-value-to-estree to convert the reading time data to an ESTree node.

If you are a TypeScript user, you may also need to install these packages for type definitions:

@types/mdast for MDX root node type definitions.
unified for plugin type definitions.

As long as we have the packages installed, we can start creating the plugin:

import { type Root } from 'mdast';
import { toString } from 'mdast-util-to-string';
import getReadingTime from 'reading-time';
import { type Plugin } from 'unified';

// The first argument is the configuration, which is not needed in this case. You can update the
// type if you need to have a configuration.
export const remarkMdxReadingTime: Plugin<void[], Root> = function () {
  return (tree) => {
    const text = toString(tree);
    const readingTime = getReadingTime(text);

    // TODO: Attach the reading time data to the MDX content
  };
};

As we can see, the plugin simply extracts the MDX content to text and calculates the reading time. Now we need to attach the reading time data to the MDX content, and it looks not that straightforward. But if we take a look at the other awesome libraries like remark-mdx-frontmatter, we can find a way to do it:

import { valueToEstree } from 'estree-util-value-to-estree';
import { type Root } from 'mdast';
import { toString } from 'mdast-util-to-string';
import getReadingTime from 'reading-time';
import { type Plugin } from 'unified';

export const remarkMdxReadingTime: Plugin<void[], Root> = function () {
  return (tree) => {
    const text = toString(tree);
    const readingTime = getReadingTime(text);

    tree.children.unshift({
      type: 'mdxjsEsm',
      value: '',
      data: {
        estree: {
          type: 'Program',
          sourceType: 'module',
          body: [
            {
              type: 'ExportNamedDeclaration',
              specifiers: [],
              declaration: {
                type: 'VariableDeclaration',
                kind: 'const',
                declarations: [
                  {
                    type: 'VariableDeclarator',
                    id: { type: 'Identifier', name: 'readingTime' },
                    init: valueToEstree(readingTime, { preserveReferences: true }),
                  },
                ],
              },
            },
          ],
        },
      },
    });
  };
};

Note the type: 'mdxjsEsm' in the code above. This is a node type that is used to serialize MDX ESM. The code above attaches the reading time data using the name readingTime to the MDX content, which will yield the following output when importing the MDX file as an ES module:

{
  default: [Function: MDXContent],
  readingTime: { text: '1 min read', minutes: 0.1, time: 6000, words: 2 }, // The reading time data

}

If you need to change the name of the reading time data, you can update the name property of the Identifier node.

TypeScript support

To make the plugin even more developer-friendly, we can make one last touch by augmenting the MDX type definitions:

declare module '*.mdx' {
  import { type ReadTimeResults } from 'reading-time';

  export const readingTime: ReadTimeResults;
  // ...other augmentations
}

Now, when importing the MDX file, TypeScript will recognize the readingTime property:

import { readingTime } from './example.mdx';

console.log(readingTime); // { text: '1 min read', minutes: 0.1, time: 6000, words: 2 }

Conclusion

I hope this guide helps you have a better experience when working with MDX files. With this remark plugin, you can use the reading time data directly and even leverage ESM tree-shaking for better performance.

Try Logto Cloud for free

How does the browser process the URL input in the address bar?

Palomino — Tue, 20 Aug 2024 05:25:21 +0000

When we open a particular URL in the browser, how does the browser load and display the content? We show what the browser did in turn, according to the order in which the event occurs.

In addition to a few specific web browsing with custom native apps while browsing different web pages, most web pages are browsed with a browser. So when we open a particular URL in the browser, how does the browser load and display the content? We will show what the browser did in turn, according to the order in which the event occurs.

User inputs URL in browser

In our previous blog post we covered URL components including what is known as the host/domain, e.g. www.google.com blog.logto.io etc.

IP address lookup using host/domain

Browser cannot directly understand the host/domain and find the corresponding resources, but needs to know the specific IP address to locate the location of the resources required for web pages.

The browser will find the IP address corresponding to the host/domain through the domain name system (DNS).

In order to make the process of searching for IP addresses as fast as possible, the correspondence between host/domain and IP address often uses various caches, such as browser cache, operating system cache, and so on.

When cache lookup misses, we go through the regular DNS lookup process to find a host/domain's IP address. These are the steps:

When a user enters blog.logto.io in the web browser, the web browser requests the DNS service to get the IP address, the corresponding query is received by DNS resolver
DNS resolver queries DNS root server (.)
Root server returns an address corresponding to a Top Level Domain (TLD) DNS server (.io in this case) and some associated information
DNS resolver query .io TLD server
.io TLD server respond with logto.io name server address
DNS resolver requests logto.io domain name server
logto.io domain name server respond with blog.logto.io address
DNS resolver forward blog.logto.io IP address back to web browser

The web browser can then request the corresponding resources from the server and render the website for the user to view.

Establish TCP connection

After obtaining the IP address corresponding to the domain to be browsed through the DNS service, the web browser initiates and establishes a TCP connection with the server.

Get resources and render web pages

After establishing a TCP connection, the browser initiates a network request to the server, obtains the corresponding resources, and renders the web page content based on the obtained resources for the user to browse.

Try Logto Cloud for free

Everything you need to know about Base64

Palomino — Tue, 20 Aug 2024 05:17:24 +0000

Dive deep into the world of Base64 encoding. Learn its history, how it works, when to use it, and its limitations. Essential knowledge for every developer dealing with data encoding and transmission.

In the world of software development, Base64 is a concept often mentioned but not always fully understood. Whether you're a newcomer to the field or an experienced developer, a deep understanding of Base64 can help you handle data encoding and transmission with ease. Let's explore all aspects of Base64, from its definition and origins to practical applications and usage considerations.

What is Base64?

Base64 is an encoding method that represents binary data using 64 printable characters. These 64 characters include:

A-Z, a-z, 0-9 (62 letters and numbers)
+ and / (2 special characters)
= (used for padding)

In our daily development work, Base64 is ubiquitous. You may have encountered it in the following scenarios:

Embedding small images or icons in HTML
Transmitting binary data in API responses
Encoding email attachments

For example, you might have seen HTML code like this:

<img
  src="data:image/png;base64,data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
  alt="Red dot"
/>

The long string here is a small image encoded in Base64.

Why Base64?

To understand the reason for Base64's existence, we need to look back at the early history of computer development.

In the early days of computer networks, most systems could only handle printable ASCII characters. ASCII encoding uses only 7 bits of binary data, representing 128 characters. This works fine for handling English text, but problems arise when transmitting binary data (such as images or audio files).

Different systems might interpret certain control characters differently, potentially corrupting data during transmission. For example, some systems might change line breaks from LF (Line Feed) to CR (Carriage Return) + LF, which would be disastrous for binary data.

To solve this problem, people began looking for a way to convert arbitrary binary data into characters that could be safely transmitted. This is where Base64 encoding came from.

In fact, before Base64, there were Base16 (using 16 characters) and Base32 (using 32 characters) encoding methods. However, Base64 struck the best balance between encoding efficiency and practicality, making it the most widely used encoding method.

How Base64 encoding works

The core idea of Base64 is to encode 3 bytes (24 bits) of binary data into 4 printable characters.

Let's understand this process through a concrete example.

Suppose we want to encode the string "Logto":

First, we convert "Logto" to ASCII code:
- L: 76 (01001100)
- o: 111 (01101111)
- g: 103 (01100111)
- t: 116 (01110100)
- o: 111 (01101111)
We concatenate these binary numbers (total of 5 bytes, 40 bits): 0100110001101111011001110111010001101111
We divide these bits into groups of 6 bits (note that the last group only has 4 bits): 010011 | 000110 | 111101 | 100111 | 011101 | 000110 | 1111
Since the last group only has 4 bits, we need to add two 0s at the end to make it 6 bits: 010011 | 000110 | 111101 | 100111 | 011101 | 000110 | 111100
We convert each 6-bit group to decimal: 19 | 6 | 61 | 39 | 29 | 6 | 60
According to the Base64 encoding table, we convert these numbers to their corresponding characters: T | G | 9 | n | d | G | 8
Finally, because Base64 encoding always encodes 3 bytes (24 bits) of binary data into 4 printable characters, and "Logto" converts to 5 bytes in binary, the first 3 bytes are encoded as TG9n, and the last 2 bytes are encoded as dG8. Therefore, we need to add one = as a padding character at the end.

Thus, the Base64 encoding result of "Logto" is TG9ndG8=.

In Node.js, we can generate Base64 encoding like this:

const text = 'Logto';
const base64 = Buffer.from(text).toString('base64');
console.log(base64); // Output: TG9ndG8=

This example demonstrates several important features of Base64 encoding:

Every 3 bytes of input produces 4 characters of output.
When the number of input bytes is not a multiple of 3, padding characters "=" are used. In this example, we have 5 input bytes, which produces 7 Base64 characters and 1 padding character.
The number of padding characters can tell us the exact number of bytes in the original data:
- No padding: The original data is a multiple of 3 bytes
- 1 =: 2 zero bits were added to the original data before encoding
- 2 =: 4 zero bits were added to the original data before encoding

When and why to use Base64

Base64 is particularly useful in the following scenarios:

Embedding small binary data (such as small images or icons) in HTML
Transmitting binary data in protocols that can only transmit text
Transmitting data in systems with restrictions on special characters
Simple data obfuscation (Note: This is not encryption!)

The main advantages of using Base64 are:

Good cross-platform compatibility: Base64 encoded data can be correctly parsed in any system that supports ASCII
Can improve transmission efficiency in some cases: For example, when the transmitted data contains a large number of repeating binary patterns

Besides standard Base64, there are some variants worth knowing:

URL-safe Base64: Replace + with -, / with _, and remove =. This encoding can be used directly in URLs without additional encoding.

const base64 = 'TG9ndG8=';
const urlSafe = base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
console.log(urlSafe);

Limitations and considerations of Base64

Although Base64 is useful, it also has some limitations:

Data inflation: Base64 encoding increases data volume by about 33%. For large amounts of data, this can lead to significant storage and bandwidth overhead.
Performance impact: The encoding and decoding process requires CPU time. For large amounts of data or high-frequency operations, this can become a performance bottleneck.
Security misconceptions: Many people mistakenly believe that Base64 is a form of encryption. In fact, Base64 is just encoding and can be easily decoded. Don't use it to protect sensitive information!
Readability: Base64 encoded data is not human-readable. This can make debugging difficult.

When using Base64 in large applications, consider the following optimization strategies:

Only Base64 encode necessary data
Consider using specialized Base64 encoding/decoding libraries, which are often more efficient than general-purpose libraries
Perform Base64 encoding/decoding on the client side to reduce server load

Conclusion

Base64 is a simple yet powerful tool that can solve many problems when used in the right scenarios. Understanding its working principle, applicable scenarios, and limitations can help you make smarter decisions in software development. I hope this article has helped you gain a comprehensive understanding of Base64, enabling you to handle related issues with ease.

Remember, like all technical tools, the key is to use Base64 at the right time and in the right place. Wishing you all the best on your programming journey!

Try Logto Cloud for free

From Parcel to Vite: A short story of a 100K LOC migration

Palomino — Tue, 06 Aug 2024 01:03:46 +0000

We've migrated our three frontend projects from Parcel to Vite, and the process was... smooth.

The backstory

We have three main frontend projects at Logto: the sign-in experience, the Console, and the live preview. These projects are all in TypeScript, React, and SASS modules; in total, they have around 100K lines of code.

We loved Parcel for its simplicity and zero-config setup. I can still remember the day when I was shocked by how easy it was to set up a new project with Parcel. You can just run parcel index.html and boom, all necessary dependencies are installed and the project is running. If you are an "experienced" developer, you may feel the same way comparing it to the old days of setting up with Gulp and Webpack. Parcel is like a magic wand.
The simplicity of Parcel was the main reason we stuck with it for so long, even though it could be moody sometimes. For example:

Parcel sometimes failed to bundle the project because it couldn't find some chunk files that were actually there.
It needed some hacky configurations to make it work with our monorepo setup.
It doesn't support MDX 3 natively, so we had to create a custom transformer for it.
It doesn't support manual chunks (as of the time of writing, the manual chunks feature is still in the experimental stage), which is okay for most circumstances, but sometimes you need it.

So why did we decide to migrate to something else?

We were stuck with Parcel 2.9.3, which was released in June 2023. Every time a new version was released after that, we tried to upgrade, but it always failed with build errors.
The latest version of Parcel was 2.12.0, released in February 2024. Although it has nearly daily commits, no new release has been made since then.

Someone even opened a discussion to ask if Parcel is dead. The official answer is no, Parcel is still alive, but it's in a we-are-working-on-a-large-refactor-and-no-time-for-minor-releases state. To us, it's like a "duck death": The latest version we can use is from more than a year ago, and we don't know when the next version will be released. It looks like it's dead, it acts like it's dead, so it's dead to us.
Trust me, we tried.

Why Vite?

We knew Vite from Vitest. Several months ago, we were tired of Jest's ESM support (in testing) and wanted to try something new. Vitest won our hearts with the native ESM support and the Jest compatibility. It has an amazing developer experience, and it's powered by Vite.

The status quo

You may have different settings in your project, but usually you will find plugin replacements as the Vite ecosystem is blooming. Here are our setups at the moment of migration:

Monorepo: We use PNPM (v9) workspaces to manage our monorepo.
Module: We use ESM modules for all our projects.
TypeScript: We use TypeScript (v5.5.3) for all our projects with path aliases.
React: We use React (v18.3.1) for all our frontend projects.
Styling: We use SASS modules for styling.
SVG: We use SVGs as React components.
MDX: We have MDX with GitHub Flavored Markdown and Mermaid support.
Lazy loading: We need to lazy load some of our pages and components.
Compression: We produce compressed assets (gzip and brotli) for our production builds.

The migration

We started the migration by creating a new Vite project and playing around with it to see how it works. The process was smooth and the real migration only took a few days.

Out-of-the-box support

Vite has out-of-the-box support for monorepo, ESM, TypeScript, React, and SASS. We only needed to install the necessary plugins and configurations to make it work.

Path alias

Vite has built-in support for path aliases, for example, in our tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

We only needed to add the same resolution in our vite.config.ts:

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: [{ find: /^@\//, replacement: '/src/' }],
  },
});

Note the replacement path should be an absolute path, while it is relative to the project root. Alternatively, you can use the vite-tsconfig-paths plugin to read the path aliases from the tsconfig.json.

React Fast Refresh and HMR

Although Vite has built-in support for HMR, it is required to install a plugin to enable React Fast Refresh. We used the @vitejs/plugin-react plugin which is provided by the Vite team and has great support for React features like Fast Refresh:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});

SVG as React component

We use the vite-plugin-svgr plugin to convert SVGs to React components. It's as simple as adding the plugin to the Vite config:

import { defineConfig } from 'vite';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  plugins: [svgr()],
});

However, we didn't specify on which condition the SVGs should be converted to React components, so all the imports were converted. The plugin offers a better default configuration: only convert the SVGs that are imported with the .svg?react extension. We updated our imports accordingly.

SASS modules

Although Vite has built-in support for SASS modules, there's one thing we need to care about: how the class names are formatted. It may be troublesome for users and our integration tests if the class names are not formatted consistently. The one-line configuration in the vite.config.ts can solve the problem:

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    modules: {
      generateScopedName: '[name]__[local]--[hash:base64:5]', // Replace with your own format
    },
  },
});

Bt the way, Parcel and Vite have different flavors of importing SASS files:

- import * as styles from './index.module.scss';
+ import styles from './index.module.scss';

The * as syntax, however, works in Vite, but it will cause the loss of modularized class names when you use dynamic keys to access the styles object. For example:

const className = 'button';
// This will not work as expecteds
return <button className={styles[className]}>Click me</button>;

MDX support

Since Vite leverages Rollup under the hood, we can use the official @mdx-js/rollup plugin to support MDX as well as its plugins. The configuration looks like this:

import { defineConfig } from 'vite';
import mdx from '@mdx-js/rollup';
import rehypeMdxCodeProps from 'rehype-mdx-code-props';
import remarkGfm from 'remark-gfm';

export default defineConfig({
  plugins: [
    {
      // The `enforce: 'pre'` is required to make the MDX plugin work
      enforce: 'pre',
      ...mdx({
        providerImportSource: '@mdx-js/react',
        remarkPlugins: [remarkGfm],
        rehypePlugins: [[rehypeMdxCodeProps, { tagName: 'code' }]],
      }),
    },
  ],
});

The remarkGfm plugin is used to support GitHub Flavored Markdown, and the rehypeMdxCodeProps plugin is used to pass the props to the code blocks in the MDX files like what Docusaurus does.

Mermiad support within MDX

We would like to use Mermaid diagrams in our MDX files as other programming languages. The usage should be as simple as other code blocks:
Should be rendered as:
Since our app supports light and dark themes, we coded a little bit to make the Mermaid diagrams work with the dark theme. A React component is created:

import { useEffect } from 'react';
import useTheme from '@/hooks/use-theme';

// Maybe defined elsewhere
enum Theme {
  Dark = 'dark',
  Light = 'light',
}

type Props = {
  readonly children: string;
};

const themeToMermaidTheme = Object.freeze({


} satisfies Record<Theme, string>);

export default function Mermaid({ children }: Props) {
  const theme = useTheme();

  useEffect(() => {
    (async () => {
      const { default: mermaid } = await import('mermaid');

      mermaid.initialize({
        startOnLoad: false,
        theme: themeToMermaidTheme[theme],
        securityLevel: 'loose',
      });
      await mermaid.run();
    })();
  }, [theme]);

  return <div className="mermaid">{children}</div>;
}

useTheme is a custom hook to get the current theme from the context. The mermaid library is imported asynchronously to reduce the loading size for the initial page load.

For the code block in the MDX file, we have a unified component to do the job:

import CodeEditor from '@/components/CodeEditor';
import Mermaid from '@/components/Mermaid';

type Props = {
  readonly children: string;
  readonly className?: string;
};

export default function Code({ children, className }: Props) {
  const [, language] = /language-(\w+)/.exec(String(className ?? '')) ?? [];

  if (language === 'mermaid') {
    return <Mermaid>{String(children).trimEnd()}</Mermaid>;
  }

  // Other code blocks go here
  return <CodeEditor>{String(children).trimEnd()}</CodeEditor>;
}

Finally we define the MDX provider as follows:

import { MDXProvider } from '@mdx-js/react';
import { ReactNode } from 'react';

type Props = {
  readonly children: ReactNode;
};

export default function MdxProvider({ children }: Props) {
  return (
    <MDXProvider
      components={{
        code: Code,
        // Explicitly set a `Code` component since `<code />` cannot be swapped out with a
        // custom component now.
        // See: https://github.com/orgs/mdx-js/discussions/2231#discussioncomment-4729474
        Code,
        // ...other components
      }}
    >
      {children}
    </MDXProvider>
  );
}

Lazy loading

This isn't a Vite-specific thing, it's still worth mentioning since we updated our pages to use lazy loading during the migration, and nothing broke afterward.

React has a built-in React.lazy function to lazy load components. However, it may cause some issues when you are iterating fast. We crafted a tiny library called react-safe-lazy to solve the issues. It's a drop-in replacement for React.lazy and a detailed explanation can be found in this blog post.

Compression

There's a neat plugin called vite-plugin-compression to produce compressed assets. It supports both gzip and brotli compression. The configuration is simple:

import { defineConfig } from 'vite';
import viteCompression from 'vite-plugin-compression';

export default defineConfig({
  plugins: [
    // Gzip by default
    viteCompression(),
    // Brotli
    viteCompression({ algorithm: 'brotliCompress' }),
  ],
});

Manual chunks

One great feature of Vite (or the underlying Rollup) is the manual chunks. While React.lazy is used for lazy loading components, we can have more control over the chunks by specifying the manual chunks to decide which components or modules should be bundled together.

For example, we can first use vite-bundle-visualizer to analyze the bundle size and dependencies. Then we can write a proper function to split the chunks:

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      manualChunks(id, { getModuleInfo }) {
        // Dynamically check if the module has React-related dependencies
        const hasReactDependency = (id: string): boolean => {
          return (
            getModuleInfo(id)?.importedIds.some(
              (importedId) => importedId.includes('react') || importedId.includes('react-dom')
            ) ?? false
          );
        };

        // Caution: React-related packages should be bundled together otherwise it may cause runtime errors
        if (id.includes('/node_modules/') && hasReactDependency(id)) {
          return 'react';
        }

        // Add your large packages to the list
        for (const largePackage of ['mermaid', 'elkjs']) {
          if (id.includes(`/node_modules/${largePackage}/`)) {
            return largePackage;
          }
        }

        // All other packages in the `node_modules` folder will be bundled together
        if (id.includes('/node_modules/')) {
          return 'vendors';
        }

        // Use the default behavior for other modules
      },
    },
  },
});

Dev server

Unlike the production build, Vite will NOT bundle your source code in the dev mode (including linked dependencies in the same monorepo) and treat every module as a file. For us, the browser will load hundreds of modules for the first time, which looks crazy but it's actually fine in most cases. You can see the discussion here.

If it's a thing for you, an alternative-but-not-perfect solution is to list the linked dependencies in the optimizeDeps option of the vite.config.ts:

import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    include: ['@logto/phrases', '@logto/schemas'],
  },
});

This will "pre-bundle" the linked dependencies and make the dev server faster. The pitfall is that HMR may not work as expected for the linked dependencies.

Additionally, we use a proxy which serves the static files in production and proxies the requests to the Vitest server in development. We have some specific ports configured to avoid conflicts, and it's also easy to set up in the vite.config.ts:

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 3000,
    hmr: {
      port: 3001,
    },
  },
});

Environment variables

Unlike Parcel, Vite uses a modern approach to handle environment variables by using import.meta.env. It will automatically load the .env files and replace the variables in the code. However, it requires all the environment variables to be prefixed with VITE_ (configurable).

While we were using Parcel, it simply replaced the process.env variables without checking the prefix. So we have come up with a workaround using the define field to make the migration easier:

import { defineConfig } from 'vite';

export default defineConfig({
  define: {
    'import.meta.env.API_URL': JSON.stringify(process.env.API_URL),
  },
});

This allows us to gradually add the prefix to the environment variables and remove the define field.

Conslusion

That's it! We've successfully migrated our three frontend projects from Parcel to Vite, and hope this short story can help you with your migration. Here's what the configuration looks like in the end:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import svgr from 'vite-plugin-svgr';
import mdx from '@mdx-js/rollup';
import rehypeMdxCodeProps from 'rehype-mdx-code-props';
import remarkGfm from 'remark-gfm';
import viteCompression from 'vite-plugin-compression';

export default defineConfig({
  resolve: {
    alias: [{ find: /^@\//, replacement: '/src/' }],
  },
  server: {
    port: 3000,
    hmr: {
      port: 3001,
    },
  },
  plugins: [
    react(),
    svgr(),
    {
      enforce: 'pre',
      ...mdx({
        providerImportSource: '@mdx-js/react',
        remarkPlugins: [remarkGfm],
        rehypePlugins: [[rehypeMdxCodeProps, { tagName: 'code' }]],
      }),
    },
    viteCompression(),
    viteCompression({ algorithm: 'brotliCompress' }),
  ],
  css: {
    modules: {
      generateScopedName: '[name]__[local]--[hash:base64:5]',
    },
  },
  build: {
    rollupOptions: {
      manualChunks(id, { getModuleInfo }) {
        // Manual chunks logic
      },
    },
  },
});

Try Logto Cloud for free

Is magic link sign-in dying? A closer look at its declining popularity

Palomino — Mon, 05 Aug 2024 23:40:07 +0000

Magic link sign-in is a convenient and secure way to authenticate users. However, its popularity has been declining in recent years. Let's explore the reasons behind this trend and discuss the future of magic link sign-in.

Background

Magic link sign-in has long been hailed as a secure and user-friendly way to authenticate users without passwords. By sending a unique link to the user's email address, magic link sign-in eliminates the need for users to remember complex passwords and provides an additional layer of security.

However, in recent years, the popularity of magic link sign-in has been on the decline. Many products that once offered magic link sign-in as an authentication option have switched to other methods, such as social sign-in or biometric authentication (fingerprint or face recognition), and one-time passwords (OTP).

Couple days ago, I saw someone tweeted that "Magic links are the worst log-in experience ever." And many people agreed and shared their own frustrated experiences with magic link sign-in.

So I began to wonder: why is magic link sign-in falling out of favor?

What is magic link sign-in?

For those unfamiliar with magic link, here's a brief overview of how it works:

The user enters their email address on the sign-in page.
The server generates a unique token and sends it to the user's email address.
The user clicks on the link in the email, which contains the token.
A browser window opens, and the user is automatically logged in.
For mobile app users, there will be a button on the mobile browser to help navigate them back to the mobile app.

Why people like magic link?

Magic link sign-in offers several advantages over traditional password-based authentication methods:

Easy to use: No need to remember complex passwords.
Secure: Reduces the risk of password-related hacks like phishing or brute-force attacks.
Simple: Good for people who struggling with technology and password management.

It used to be a popular choice for companies looking to provide a seamless and secure authentication experience for their users. But why are there complaints about it now?

The hassle of switching apps

One big reason people don't like magic link any more is that it makes you switch between apps. Imagine you're on a mobile app and you want to sign in. After inputting your email, you will have to switch between the app, your mail app, and the browser, and finally if everything goes well then thank god you're back to the app.

This can be annoying and time-consuming, especially if you're in a hurry or have a slow internet connection. Not to mention sometimes the email just doesn't arrive, or it goes to the spam folder. Those extra steps can easily frustrate users and make them less likely to choose this sign-in method or even use the app.

The rise of other passwordless sign-in methods

Another reason for the decline in magic link sign-in popularity is the rise of other passwordless authentication methods. For example:

Biometric authentication has become increasingly popular due to its convenience and security.
Social sign-in that allows users to sign in using their existing social media accounts, is another popular alternative to traditional password-based authentication.
OTP, which sends a one-time code to the user's phone or email, is also a widely used method, especially when mobile phones can autofill the OTP code for you now.

Password managers and autofill

Password managers, such as 1password, web browsers, etc., have also played a role in the decline of magic link sign-in.

With these password managers, users can securely store and autofill their passwords across different websites and apps, eliminating the need to remember or manually enter passwords. Especially when combined with biometric authentication, the overall user experience is more and more seamless.

The verdict: Is magic link sign-in dying?

While magic link sign-in is still used by many companies, it's definitely facing tough competition and may struggle to stay relevant in the fast-changing world of online security. Do you still remember last time you used magic link to sign in? I honestly don't. So for me and many others, it seems it's indeed dying.

What is your take on this? What is your favorite sign-in method and why? Please feel free to share your thoughts with us.

Try Logto Cloud for free