Forem: propelauthblog

Building internal AI tools with Streamlit

propelauthblog — Wed, 02 Oct 2024 17:26:18 +0000

Most companies have a ton of valuable data internally. This could be analytics data on your customers interactions with your product. This could be an audit log of actions taken within the product (which is another way to see when different features are enabled).

Even if you are a small startup, you likely have valuable data in the form of support tickets — which can show you the areas of the product that need the most attention. You also likely have feature requests scattered throughout those support tickets.

Pre-LLMs, trying to extract insights from any data required specialized knowledge. You often needed to train your own model, which meant feature engineering & NLP, choosing a model, and most onerous of all… gathering your own training data.

Nowadays, you can just write a prompt like

Categorize the following ticket using these categories: Uptime, Security, Bug, Feature Request, Other

{put ticket here}

And boom, you have a classifier — and it’s probably decent without much tuning (although you absolutely should modify it).

In this post, we’ll look at how you can use Streamlit to build an internal tool that allows anyone at the company to experiment with using LLMs on top of any dataset you give access to.

What we’re building today

Users should be able to:

Log in, so we know who they are and what data they have access to
Write a prompt. In this case, it’s for a ticket classification system.
Test the prompt on some sample data and see the output (including errors).
Save the prompt for others to use.

Before we jump into the code, let’s first look at what Streamlit is.

A very quick intro to Streamlit

Streamlit is a fantastic tool for quickly building data applications. You get to write code like:

import streamlit as st

prompt = st.text_area(
    "Prompt to test (use {text} to indicate where the text should be inserted):",
    "This is an example prompt:\\n\\n{text}",
)
prompt_with_data = f"{prompt}".format(
    text="`Example data to be placed into prompt`"
)
st.write(prompt_with_data)

and Streamlit automatically creates an interactive frontend:

If a user were to update that prompt text_area, the rest of the Python code will re-run:

This is incredibly powerful for building tools like interactive dashboards. There’s a number of other components that you can use, like rendering a pandas dataframe as a table or a button to trigger actions off of.

There’s also a set of utilities for loading data from external sources, managing secrets, and caching data. The combination of all of these makes for a very powerful tool for interacting with your data.

Step 1: Loading and visualizing our data

What good is a data application without data? To get a sense for what we can do, let’s start by hard coding some data:

import streamlit as st

def load_data_sample():
    return pd.DataFrame(
        {
            "Ticket": [
                "I cant log into my account, it keeps sayin "invalid credentials." I know the password is correct tho.",
                # ...
            ],
        }
    )

# Load the data
data = load_data_sample()
# render it as a table
st.dataframe(data, use_container_width=True, hide_index=True)

And this will render a table with all the tickets we hard coded:

Streamlit does have built in support for a number of data sources. For example, if we wanted to connect to Postgres, we’d first tell Streamlit how to connect to our Postgres database via the .streamlit/secrets.toml file:

[connections.postgresql]
dialect = "postgresql"
host = "localhost"
port = "5432"
database = "xxx"
username = "xxx"
password = "xxx"

We’d install pip install psycopg2-binary (which is needed to connect to Postgres).

And then we can update our load_data_sample() function:

def load_data_sample():
    conn = st.connection("postgresql", type="sql")
    # Results are cached for 5 min
    return conn.query('SELECT description as Ticket FROM tickets;', ttl="5m")

Similarly, we can connect to Snowflake or even a Google sheet. It’ll always end up as a dataframe that we can easily visualize.

A brief note on caching

The query call has a built-in caching mechanism in the form of a TTL. There are, however, two other options for caching: st.cache_resource and st.cache_data.

cache_resource is commonly used for caching connections - so you can use it for caching the database connection or for the OpenAI client that we’ll construct later on.

cache_data is commonly used for caching the result of expensive queries. You can annotate the load_data_sample function which will speed up subsequent requests to load it.

Step 2: Running our data through the prompt

We started by taking in a prompt from the user. Then we loaded the data. Now it’s time to execute the prompt on that data.

For us, we’re going to ask our users to make sure their prompt outputs valid JSON with the form:

{
    "urgent": false,
    "categories": ["CategoryA", "CategoryB"]
}

We can do a fairly simple transformation of our dataframe which adds 3 columns: urgent, categories , and error (in the event that something went wrong).

@st.cache_data
def classify_ticket(ticket):
    # Construct an OpenAI client
    openai_key = st.secrets["openai_key"]
    openai_client = OpenAI(api_key=openai_key)

    # Format the prompt to include the ticket
    response = openai_client.chat.completions.create(
        messages=[{"role": "user", "content": prompt.format(text=ticket)}],
        model="gpt-4o-mini",
    )
    response = response.choices[0].message.content
    if response is None:
        return {"error": "No response from OpenAI"}

try:
        response = json.loads(response)
    except json.JSONDecodeError:
        return {"error": "Invalid JSON in response"}
    if "urgent" not in response:
        return {"error": "No 'urgent' field in response"}
    if "categories" not in response:
        return {"error": "No 'categories' field in response"}
    return response

def modify_data_to_include_classification(data):
    for i, row in data.iterrows():
        text = row["Ticket"]
        response = classify_ticket(text)
        data.at[i, "Categories"] = response.get("categories")
        data.at[i, "Urgent"] = response.get("urgent")
        data.at[i, "Error"] = response.get("error")

Easy enough! The big question now is… how frequently do we want this to run? We’ve cached the most expensive part of this (both time and money-wise), which is the call to OpenAI.

But, we want to be careful to not run this every time someone makes a small change to the prompt. The easiest fix? Let’s just add a button to trigger the re-running of the prompt on the data.

Streamlit makes this really easy:

data = load_data_sample()
if st.button("Test Prompt"):
    modify_data_to_include_classification(data)
st.dataframe(data, use_container_width=True, hide_index=True)

st.button will return True when the button is clicked and will modify the Dataframe to add new columns. A user that has never clicked Test Prompt will see just the unclassified sample data for inspiration.

And that’s… most of it!

A user can open up our app, view some sample data, write a prompt, and see the results of running that prompt on the sample data. The only thing that’s a bit scary, is we haven’t added any authentication. Any user can interact with our data and we don’t know who wrote which prompts.

Step 3: Adding authentication

One quirk of Streamlit today is that authentication is difficult. The out of the box options aren’t great for a company building an internal app, where you might want sign in with Okta or Azure via SSO/SAML or you might want to make sure 2FA is required before using the application.

PropelAuth is a great fit here as PropelAuth provides full authentication UIs that you can use directly with Streamlit.

Looking to set up a really basic application with just email and password login? The code will look like this:

user = auth.get_user()
if user is None:
    st.error('Unauthorized')
    st.stop()

st.write('Logged in as ', user.email)

Looking to set up an advanced application that requires users to log in via SAML? The code snippet is the same!

For a full guide on how to get started, check out our documentation here. The gist is that we will create a file propelauth.py which will export an auth object.

At the top of our script, we just need to make sure we can load the user or stop the rest of the script from running. We can then user the user’s ID in any of queries to the data to make sure they are only seeing data they have access to.

from propelauth import auth

# Is this a valid user? If not, make sure the script stops
user = auth.get_user()
if user is None:
    st.error('Unauthorized')
    st.stop()
st.write('Logged in as ', user.email)
# ...
def load_data_sample(user_id):
    conn = st.connection("postgresql", type="sql")
    return conn.query(
        'SELECT description as Ticket FROM tickets WHERE user_id = :user_id;', 
        params={"user_id": user_id}
        ttl="0"
    )
data = load_data_sample(user.user_id)

Step 4: Saving the prompt

As an optional last step — let’s say we wanted to provide a way for users to save their prompts. We can re-use basically everything we’ve learned so far and make this really easy:

if st.button("Save Prompt"):
    conn = load_connection() # e.g. st.connection("postgresql", type="sql")
    with conn.session as session:
        session.execute(
            "INSERT INTO prompts (user_id, prompt) VALUES (:user_id, :prompt);", 
            {"user_id": user.user_id, "prompt": prompt}
        )
        session.commit()
    st.write("Saved!")

Summary

In this guide, we’ve explored how to build powerful internal AI tools using Streamlit. We’ve covered loading and visualizing data, running prompts on that data, adding authentication with PropelAuth, and even saving user-generated prompts. By leveraging these techniques, you can create robust, secure, and interactive data applications that harness the power of AI for your organization’s specific needs.

FastAPI Auth with Dependency Injection

propelauthblog — Mon, 23 Sep 2024 15:41:13 +0000

FastAPI is a modern web framework for building APIs in Python. It’s one of my personal favorite web frameworks as it has built-in support for OpenAPI specs (meaning you can write your backend code and generate everything from it) and it supports dependency injection.

In this post, we’ll briefly look at how FastAPI’s Depends works. We’ll then see why it applies so well to authentication and authorization. We’ll also contrast it with middleware, which is another common option for auth. Finally, we’ll look at some more advanced patterns for authorization in FastAPI.

What is Dependency Injection?

One of FastAPI’s more powerful features is its first class support for dependency injection. We have a longer guide here, but let’s look at a quick example of how it can be used.

Let’s say we are building a paginated API. Each API call may include a page_number and a page_size. Now, we could just create an API and take these parameters in directly:

@app.get("/things/")
async def fetch_things(page_number: int = 0, page_size: int = 100):
    return db.fetch_things(page_number, page_size)

But, we probably want to add some validation logic so no one asks for page_number -1 or page_size 10,000,000.

@app.get("/things/")
async def fetch_things(page_number: int = 0, page_size: int = 100):
    if page_number < 0:
        raise HTTPException(status_code=400, detail="Invalid page number")
    elif page_size <= 0:
        raise HTTPException(status_code=400, detail="Invalid page size")
    elif page_size > 100:
        raise HTTPException(status_code=400, detail="Page size can be at most 100")
    return db.fetch_things(page_number, page_size)

And this is... fine, but if we had 10 APIs or 100 APIs that all needed the same paging params, it’d get a bit tedious. This is where dependency injection comes in - we can move all this logic into a function and inject that function into our API:

async def paging_params_dep(page_number: int = 0, page_size: int = 100):
    if page_number < 0:
        raise HTTPException(status_code=400, detail="Invalid page number")
    elif page_size <= 0:
        raise HTTPException(status_code=400, detail="Invalid page size")
    elif page_size > 100:
        raise HTTPException(status_code=400, detail="Page size can be at most 100")
    return PagingParams(page_number, page_size)

@app.get("/things/")
async def fetch_things(paging_params: PagingParams = Depends(paging_params_dep)):
    return db.fetch_things(paging_params)

@app.get("/other_things/")
async def fetch_other_things(paging_params: PagingParams = Depends(paging_params_dep)):
    return db.fetch_other_things(paging_params)

This has some nice benefits:

Each route that takes in PagingParams is automatically validated and has default values.
It’s less verbose and error-prone than having the first line of each route be validate_paging_params(page_number, page_size)
This still works with FastAPI’s OpenAPI support - those parameters will show up in your OpenAPI specs.

What does this have to do with authentication?

It turns out, this is also a great way to model auth! Imagine you had a function like:

async def validate_token(token: str):
    try:
        # This could be JWT validation, looking up a session token in the DB, etc.
        return await get_user_for_token(token)
    except:
        return None

To hook this up to an API route, all we’d need to do is wrap it in a dependency:

async def require_valid_token_dep(req: Request):
    # This could also be a cookie, x-api-key header, etc.
    token = req.headers["Authorization"]
    user = await validate_token(token)
    if user == None:
        raise HTTPException(status_code=401, detail="Unauthorized")
    return user

And then all of our protected routes can add this dependency:

@app.get("/protected")
async def do_secret_things(user: User = Depends(require_valid_token_dep)):
    # do something with the user

If the user provides a valid token, this route will run and user is set. Otherwise, a 401 will be returned.

Note: OpenAPI/Swagger does have first-class support for specifying auth tokens, but you have to use one of the dedicated classes for it. Instead of req.headers["Authorization"], you can use HTTPBearer(auto_error=False) from fastapi.security which returns an HTTPAuthorizationCredentials.

Middleware vs Depends for Auth

FastAPI, like most frameworks, has a concept of middleware. Your middleware can contain code that will run before and after a request. It can modify the request before the request gets to your route and it can modify the response before it’s returned to the user.

In many other frameworks, middleware is a really common place for authentication checks to take place. However, that’s often because the middleware is also tasked with “injecting” the user into the route. For example, a common pattern in Express is to do something like:

app.get("/protected", authMiddleware, (req, res) => {
    // req.user is set by the middleware
    // as there's no good way to pass in extra information into this route,
    // outside of the request
});

Since FastAPI has a built-in concept of injection, you may not need to use middleware at all. I’d consider using middleware if you need to periodically “refresh” your auth tokens (to keep them alive) and set the response as a cookie.

In this case, you’ll want to use request.state to pass information from the middleware to the routes (and you can use a dependency to validate the request.state if you’d like).

Otherwise, I’d stick with using Depends as the user will be injected directly into your routes without needing to go through request.state.

Authorization - Multi-tenancy, Roles & Permissions

If we apply everything we learned so far, adding in multi-tenancy, roles or permissions can be pretty straightforward. Let’s say we have a unique subdomain for each of our customers, we can make a dependency for this subdomain:

async def tenant_by_subdomain_dep(request: Request) -> Optional[str]:
    # first we get the subdomain from the host header
    host = request.headers.get("host", "")
    parts = host.split(".")
    if len(parts) <= 2:
        raise HTTPException(status_code=404, detail="Not found")
    subdomain = parts[0]

    # then we lookup the tenant by subdomain
    tenant = await lookup_tenant_for_subdomain(subdomain)
    if tenant == None:
        raise HTTPException(status_code=404, detail="Not found")
    return tenant

We can combine this idea with our previous ideas and make a new “multi-tenant” dependency:

async def get_user_and_tenant_for_token(
    user: User = Depends(require_valid_token_dep),
    tenant: Tenant = Depends(tenant_by_subdomain_dep),
) -> UserAndTenant:
    is_user_in_tenant = await check_user_is_in_tenant(tenant, user)
    if is_user_in_tenant:
        return UserAndTenant(user, tenant)
    raise HTTPException(status_code=403, detail="Forbidden")

We can then inject this dependency into our routes:

@app.get("/protected")
async def do_secret_things(user_and_tenant: UserAndTenant = Depends(get_user_and_tenant_for_token)):
    # do something with the user and tenant

And this ends up doing a few major things:

Checking that the user has a valid token
Checking that the user is making a request to a valid subdomain
Checking that the user should have access to that subdomain

If any of those invariants aren’t met - an error is returned and our route will never run. We can extend this to include other things like roles & permissions (RBAC) or making sure the user has a certain property set (active paid subscription vs no active subscription).

PropelAuth <3 FastAPI

At PropelAuth, we’re big fans of FastAPI. We have a FastAPI library that will enable you to set up authentication and authorization quickly - including SSO, Enterprise SSO / SAML, SCIM Provisioning, and more.

And it all works with dependencies like the ones you’ve seen above, e.g.:

@app.get("/")
async def root(current_user: User = Depends(auth.require_user)):
    return {"message": f"Hello {current_user.user_id}"}

You can find out more here.

Summary

FastAPI's dependency injection provides a powerful way to handle authentication and authorization in web applications.
The Depends feature allows for clean, reusable code for validating tokens, checking user permissions, and handling multi-tenancy.
Compared to middleware, using dependencies for auth offers more flexibility and direct integration with route functions.
Complex authorization scenarios like multi-tenancy and role-based access control can be efficiently implemented using nested dependencies.
PropelAuth offers a FastAPI library that simplifies the implementation of advanced authentication and authorization features.

Libraries for writing raw SQL safely

propelauthblog — Fri, 13 Sep 2024 16:29:15 +0000

One of my responsibilities at PropelAuth is writing example apps / guides in various languages / frameworks. It’s truly one of the most fun parts of my job. I get to play around with different stacks, new and old, and figure out the best ways to support our customers.

Because of that, I end up creating a lot of projects from scratch. Whenever I start a new project, there’s a few important choices I have to make — and one decision that I tend to spend a lot of time on is:

What DB library should I use?

To me, the libraries that I gravitate towards are the ones that have as few layers of abstraction between the code I’m writing and the SQL query itself.

One reason for this is just practicality — since I switch languages often, I don’t have as much time to get fluent in any particular ORM. I’ve also had jobs in the past that had heavy data science components to them, so SQL is something I am very comfortable with.

But I’m also a developer that tends to dislike “magic” — so I avoid libraries where I can’t easily tell what the generated SQL will look like, or libraries where I feel like I’m spending all my time googling “how to do join in X” followed by “how to do join in X with two conditions”.

In this post, I wanted to highlight a few libraries that I frequently reach for, as well as ones that I’m excited to try out, that all try and minimize the difference between the code I write and the SQL that is executed.

My personal favorite: SQLx

One of my favorite Rust crates is SQLx.

In their own words:

SQLx supports compile-time checked queries. It does not, however, do this by providing a Rust API or DSL (domain-specific language) for building queries. Instead, it provides macros that take regular SQL as input and ensure that it is valid for your database. The way this works is that SQLx connects to your development DB at compile time to have the database itself verify (and return some info on) your SQL queries.

Put differently, SQLx let’s you write a query like this:



let row = sqlx::query!(r#"
    SELECT enail
    FROM user
    WHERE user_id = ?
"#, user_id)
  .fetch_one(&pool)
  .await?;

which might seem standard, but when you compile your code, you’ll get an error like this:



error returned from database: column "enail" of relation "user" does not exist

This same compile-time checking also applies to complex queries:



SELECT job_id, job_data 
FROM job_queue
WHERE job_status = 'Queued' AND run_at >= NOW()
ORDER BY run_at ASC
FOR UPDATE SKIP LOCKE -- oops
LIMIT 1



error returned from database: syntax error at or near "LOCKE"

Since the query is checked against the database, this will also work with any extensions you have installed.

Why is this cool?

The incredible thing about this is we are literally just writing SQL. But unlike a crate like postgres, which also allows you to write raw SQL, SQLx prevents us from making silly mistakes.

This does come at a small cost — we now have a compile-time dependency on a database, but SQLx addresses this with an “offline mode.” When your DB is available, you can generate a file with all the validated queries, and then in your build, SQLx will check this file instead of the database.

In my quest to minimize the difference between the code I write and and the SQL that’s executed, with SQLx there is both no difference AND I didn’t have to sacrifice safety to get it.

Generate TS interfaces for your SQL with PgTyped

As it often goes in the JavaScript/TypeScript ecosystem, there’s a lot of options here.

There are options like Kysely which generate TS types from your database and then provide both a query builder and a way to write raw SQL. There’s Drizzle, which is a query builder, but it’s stated goal is reducing the delta between the TS code you write and generated SQL. There’s even a SQLx port that I have not yet had a chance to try.

But the library that best matches what I am looking for here is PgTyped. With PgTyped, you define your queries in separate files like so:



/* @name FindEmailById */
SELECT email FROM user WHERE user_id = :userId;

You then run a command npx pgtyped -c config.json which generates a function with proper types based on your schema:



export interface IFindEmailByIdParams {
    userId?: string | null;
}



export interface IFindEmailByIdResult {
    email: string
}export const findEmailById = new PreparedQuery< // ...

You can call that function to get the results from the DB. Importantly, if your query is wrong (let’s say it references a column that doesn’t exist), you get an error like this:



Error in query. Details: {
  errorCode: 'errorMissingColumn',
  hint: 'Perhaps you meant to reference the column "user.email".',
  message: 'column "enail" does not exist',
  position: '7'
}

This means you not only get to write raw SQL safely — your application code gets a nice TS abstraction to call (or mock in tests).

The biggest downside to PgTyped is this Github issue — the nullability of types isn’t respected, which can be pretty frustrating as it means you might reasonably pass in null for a required field. Another downside is its specific to Postgres… more on that later in the “portability” section.

Prisma recently released TypedSQL — a “a new way to write raw SQL queries in a type-safe way.” They mention that part of the inspiration was both SQLx and PgTyped, so I am excited to try it out!

Something for the Python world: PugSQL

A library I enjoy when I switch to Python is PugSQL (Python). Similar to PgTyped, you create separate SQL files for your queries like this:



-- :name find_email :one
select email from users where user_id = :user_id

which will create a function that you can call:



email = queries.find_email(user_id=42)

The downside (relative to the previous libraries) is these queries aren’t automatically checked for issues. That being said, some tests can surface most (all?) the issues with the query itself — you just need to write them.

If you are feeling fancy, it’s possible to add your own automation which will check the queries. There are ways to verify a query against a DB without running the query — it’s just some additional work. Each query being in its own file makes it a bit easier to automate since you don’t need to go parse out the queries in the first place.

Mark up your interfaces with JDBI

Whenever I talk about how much I liked Dropwizard, I usually get met with blank stares. It’s a bit of a deeper cut in the Java world relative to Spring (either that or normal people don’t discuss Dropwizard at parties).

One of the reasons I liked Dropwizard so much was just because it came with JDBI. That library allowed you to annotate the functions on an interface with SQL queries and it would generate the implementation for you.



public interface UserDAO {
  @SqlQuery("select email from user where user_id = :user_id")
  String fetchEmail(@Bind("user_id") String userId);
}



final UserDAO userDao = database.onDemand(UserDAO.class);

Again though, this would require additional testing to find issues in the queries.

I should also mention that Spring Data JPA does also have the same concept with it’s @Query annotation. It’s been a very long time, but back when I was comparing JDBI and Spring Data JPA - I always felt like Spring was trying to get me to use it’s more magical “function name to sql query” methods. Upon re-reading the docs recently though, I was wrong, and it does mention that you can fallback to @Query pretty frequently.

Other considerations

“Use it sparingly”

If you followed some of the links in this post, you’ll find that some of these libraries don’t advocate for this approach as the primary way to query the database.

TypedSQL describes it as an escape hatch for when querying via their ORM isn’t sufficient. Same for Spring Data JPA which describes it as “fine for a small number of queries”.

This isn’t an unfounded claim — if you go down the path of writing raw SQL for every query, it can be pretty verbose. There are absolutely times where I am making a simple, boring table that’s basically just a key-value store, and the exercise in writing INSERT INTO boring_table VALUES (...) and SELECT * FROM boring_table WHERE ... etc is just a typing exercise.

A library that provides the best of both worlds seems great! The devil is really in the details, as it depends on what you consider to be complex enough to warrant writing raw SQL and how frequently those queries come up.

Portability

One issue with the raw SQL approach is it’s less portable. If you are using an ORM, that ORM often will be compatible with more than just the database you are currently working with.

This can mean small things like running sqlite locally and a different DB in production — or big things like making it easier to migrate your database to something else.

Again, your mileage may vary here — it’s really dependent on how much you care about this.

Use a query builder instead

Going back to the java ecosystem, a popular library is jOOQ. With jOOQ, you aren’t writing raw SQL, but it’s very close:

To me, this is great! My stated goal was just keeping the delta between my code and the generated SQL as little as possible, so query builders like jOOQ or Drizzle do a good job of keeping that delta small.

Not all query builders are made equal here, as I tend to dislike ones like Knex which have a larger delta.

Summary

Raw SQL libraries like SQLx, PgTyped, and JDBI allow writing SQL directly while providing safety and type checking.
These libraries aim to minimize the gap between code and executed SQL, with some offering benefits like compile-time checking and generated type interfaces.
Alternatives include query builders like jOOQ and Drizzle, where you are directly writing SQL, but the gap is still small.
Considerations when choosing a DB library include portability, verbosity, and the need for complex queries versus simple CRUD operations.

OAuth2 in Simple Terms

propelauthblog — Mon, 09 Sep 2024 23:22:19 +0000

If you’ve ever searched for OAuth (or OAuth2 or OpenID connect/OIDC), you’ve probably been greeted with a picture that looks like this:

(source)

along with some descriptions of resource servers, the difference between authentication and authorization, consent screens, token endpoints, and more.

And while that can be helpful, it’s usually more helpful if you already know what OAuth is for and a bit of how it works.

In this post, I want to start simpler, explain more of the why behind OAuth, and then afterwards we’ll dig into the weeds.

Walking through a simplified OAuth2 example

What is the problem we are trying to solve?

Succinctly describing OAuth can be challenging because it comes in a lot of different flavors that are for different use cases. Let’s start with one of the simplest use cases:

We are building a web application. We want users to be able to log in using their existing Google accounts. We also need to get the user’s email address as part of that login process.

Importantly, there are three parties here:

Us - we are building a web application
joe@example.com - the user, they are trying to log in to our web application
Google - the source of truth about Joe’s account

A wrong approach on the right track: Ask for the user’s Google password

First idea that comes to mind: let’s just ask the user for their Google email address and password. We can try and log in as them, and if it’s successful, we’ll know they are who they say they are!

Ignoring the obvious issue that no one should ever give out their Google password, this approach doesn’t work for a bunch of other reasons like:

Does the user give you their 2FA secret as well?
What happens when Google flags the login as coming from a new device?

We can’t use their password, but the underlying idea here is reasonable:

We need something unique to the user, that we can send to Google and have them respond with “Yes, this is joe@example.com”

A better approach: One time codes

The password was obviously a little sensitive, we shouldn’t ask the user for that. What if they instead could go to Google and ask for a short-lived code (e.g. aGV5IHRoZXJl)?

The user then comes to us and says “Hey, my code is aGV5IHRoZXJl, ask Google who I am”

We ask Google “Is aGV5IHRoZXJl a valid code, and if so, who’s it for?”

Google responds with: “Yes, that’s joe@example.com”

We did it! The user was able to prove to us that they own the joe@example.com account that Google manages. We can create an account for Joe using that email address, log them in, and move on.

Google does need to be a little careful - they wouldn’t want aGV5IHRoZXJl to be usable multiple times and ideally it has a very narrow window to be used in the first place.

This approach seems reasonable, the next questions are… how does Joe get a code? And how does Joe share the code with us?

Getting a code from Google

If you’ve ever been on a screen like this:

this is actually the first step in getting the code.

The way that it works is Google sets up a URL like https://identity.google.com/get-me-a-code (not the real URL).

When we want to log a user in, we’ll redirect the user from our application to that URL.

The user then logs in to Google (if they weren’t already) and Google will create a code for that account.

Since we want this to be simple, ideally, the user doesn’t need to know about the code at all. Google can just send the user back to us, by redirecting them to: https://ourapp.com/handle-the-code?code=aGV5IHRoZXJl

We read the query parameter code and send it to Google to determine if it’s valid and who it’s for (more on this later).

Putting it all together

The whole flow, end-to-end, looks like this:

Joe comes to our site and clicks “Log in with Google” which kicks off the OAuth2 flow
We redirect Joe to https://identity.google.com/get-me-a-code (still not the real URL)
Joe logs in to Google
Google generates a code aGV5IHRoZXJl
Google redirects Joe back to our application with the code: https://ourapp.com/handle-the-code?code=aGV5IHRoZXJl
We read the code from the URL and ask Google who it’s for
Google responds: joe@example.com

And that’s all - as long as we trust Google, we know this user is joe@example.com

Understanding a more complete OAuth2 example

To make this more understandable, I skipped a few important steps in the OAuth 2.0 process. Let’s go back now and fill in some extra details.

Some of the things I skipped

How does Google know where to redirect the user back to?

Good question 🙂 The answer is we provide a query parameter that tells Google where to redirect the user back to:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://ourapp.com/handle-the-code

Why can’t someone put any redirect_uri in?

Since Google is just using query parameters, someone can come along and do this:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://uhoh.com

This can lead to a vulnerability called an open-redirect vulnerability, where a user thinks they are going to https://ourapp.com but actually end up on https://uhoh.com.

To prevent this, Google (and any OAuth provider) must require that you register your redirect URLs with them ahead of time.

Anyone attempting to redirect to https://uhoh.com would error as it’s an unknown URL and therefore invalid.

How does Google know who we are?

You might be wondering - how can Google validate our redirect URI? When we redirected the user to https://identity.google.com/get-me-a-code we didn’t include any information on who we are.

To solve this, when we first set up Sign in with Google, we have to register with them. We’re given a Client ID & Client Secret, which you can think of like a username and password. When we redirect our user to Google, we include the client ID in it:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://ourapp.com/handle-the-code
    &client_id={CLIENT_ID}

This is how Google identifies us. Later on, when we verify the code with Google, we include both the client ID & client secret.

Can’t a malicious user make me log in to their account using one of their codes?

This is a really important point. Imagine we’re making a web application to help businesses manage and pay their bills in one central location. A malicious user comes along and sends us this link:

https://ourapp.com/handle-the-code?
    code={A_CODE_THE_ATTACKER_GENERATED_FOR_THEIR_ACCOUNT}

We click this link and are immediately logged in to the attackers account. Hopefully you notice before you pay any of the bills - but it’s understandable to miss it, especially for big companies.

To prevent this issue, we add one more variable to the initial request, called state . The state should be a random value that you generate. It should both be unique for each request and unguessable:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://ourapp.com/handle-the-code
    &client_id={CLIENT_ID}
    &state=SOMETHING_MORE_RANDOM_THAN_THIS

Before redirecting the user, we save that state value somewhere in our application (e.g. a cookie, localStorage, etc.). When the user comes back to our redirect URL, Google will include the state:

https://ourapp.com/handle-the-code?
    code=aRandomCode
    &state=SOMETHING_MORE_RANDOM_THAN_THIS

If the state matches the value we saved, we can be confident that we initiated the flow. Otherwise, we should reject the request.

Note: Sometimes people will persist information in the state, like this:

const state = base64encode({ returnToPath: "/app", random: genRandom() })

This is totally fine as long as it’s still has a random/unguessable component to it.

The biggest thing I skipped: Scopes

So far, we’ve looked at OAuth2 for one very specific reason: to get access to the email address of their Google account. However, OAuth2 was designed with more than just that in mind.

What if, in addition to getting the user’s email address, we also wanted to read health data from the user’s Google Fit account?

To do this, we can pass in a “scope” to Google, signifying the access we are requesting:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://ourapp.com/handle-the-code
    &client_id={CLIENT_ID}
    &state=SOMETHING_MORE_RANDOM_THAN_THIS
    &scope=letMeReadFitData letMeReadEmail

Because many scopes are sensitive, the user will be asked if they consent to the scopes that you requested:

That page, unsurprisingly, is called a consent screen. Those scopes above were obviously fake, but here’s a list of scopes that Google supports.

How can we access the Google Fit data? Doesn’t Google respond to our “code” with an email address?

This was an area where I intentionally oversimplified things.

Google doesn’t respond to the our “code” with an email address. It actually responds with an access token. We can use this access token to make requests to Google on behalf of our user, based on what they consented to.

If the user consented to us having access to their email address, we can use the access token to fetch their email address.

If the user consented to us having their Google Fit data, we can use the access token to fetch their Google Fit data.

Putting it all together (again)

Ok, let’s bring it all together with one final walkthrough. As a reminder, our use case is:

We are building a web application. We want users to be able to log in using their existing Google accounts. We also need to get the user’s email address as part of that login process.

Before we start, we register with Google and tell Google to expect that we will redirect the user back to https://ourapp.com/handle-the-code

Google provides us with a Client ID and Client Secret.

When our user is ready to log in, we generate a random variable called state and save it as a cookie:

state=XfDv59k5JZz00Tz0zGtb8TOzUqDTbFqZ

Then, we kick off the OAuth flow by redirecting the user to the authorization URL:

https://identity.google.com/get-me-a-code?
    redirect_uri=https://ourapp.com/handle-the-code
    &client_id={CLIENT_ID}
    &state=XfDv59k5JZz00Tz0zGtb8TOzUqDTbFqZ
    &scope=https://www.googleapis.com/auth/userinfo.email

The user is sent to Google and asked to log in / select an account.

The user is then asked to consent to the scopes we selected - in this case, they’ll be asked if they are comfortable sharing their email address with us.

Assuming the user says yes, Google will redirect the user back to our application with a code and the state variable we passed in earlier:

https://ourapp.com/handle-the-code?
    code=aRandomCode
    &state=XfDv59k5JZz00Tz0zGtb8TOzUqDTbFqZ

We load our state cookie and verify that the query parameter and cookie match.

We then make a request to Google’s token endpoint to exchange the code for an access token:

POST https://identity.google.com/token

// This is standard "basic" authentication with 
// client ID / client secret as username /password
Headers:
- Authorization: Basic {base64encoded(client_id:client_secret)}

URL Encoded Body: 
- grant_type=authorization_code
- code=aRandomCode
- redirect_uri=https://ourapp.com/handle-the-code

Google returns an access token and that access token will have the ability to do whatever the user consented to.

In our case, this is as simple as making a request to

GET https://www.googleapis.com/oauth2/v3/userinfo

Headers:
- Authorization: Bearer {access token}

and getting the user’s email address and if it’s been confirmed.

That seemed like a lot?

OAuth can feel pretty heavy, especially for the login case, where we did all that just to get the user’s email.

This is made a bit worse by the fact that we’re only covering one grant type. There are other OAuth flows for the unique requirements of smart tvs and extensions like PKCE for mobile applications or cases where you can’t securely store the client secret. There are also extensions for OIDC that providers may or may not support.

Luckily, there are a lot of great OAuth client libraries that can hide most of the details from you.

Adding back the jargon

To me, technical jargon usually makes the barrier to understanding a new concept higher, so I try and avoid it.

That being said, for better or worse, you might need to know the jargon at some point, so let’s connect the concepts we just learned to the jargon.

What we just looked at was a version of OAuth2 with the Authorization Code grant. This is a really common grant type for web applications.

When we redirected the user to https://identity.google.com/get-me-a-code, that was the authorization request (and that URL can be referred to as the authorization URL).

When Joe was redirected back to our application, https://ourapp.com/handle-the-code is called the redirect URL but it can also be called a callback URL.

When we made the request to exchange the code for a token, the URL we hit is the token URL (e.g. https://identity.google.com/token)

Summary

OAuth2 might seem complex at first glance, but at its core, it's about securely accessing user data without handling passwords.

We've walked through a simplified flow: redirecting users to log in with a provider like Google, getting a temporary code, and exchanging that for an access token to fetch user data.

While there's certainly more to OAuth2, including different grant types for various scenarios, understanding these basics gives you a solid foundation.

And remember, many libraries can handle the nitty-gritty details, making OAuth2 integration much more manageable in practice.

Perfectly Contrasting Text on a Gradient Background

propelauthblog — Wed, 21 Feb 2024 00:15:58 +0000

Gradient backgrounds are one of the more popular current web design trends, and I must admit they can look very pretty. What doesn’t look so nice is poorly contrasted text rendered directly on top of one.

This is trickier to avoid than you’d think, especially when you want to render text elements using a specific shade (think links with your primary brand color). Sure, you can look at a piece of text and say “Gee, this needs to be darker to be visible on that background”, but resizing the page or viewing it on mobile may position said text in a completely different area where it’s poorly contrasted.

The text at the top is perfectly legible, but it gets harder and harder to read as we move down on the Y axis. There are some colors that will contrast well against all shades of this gradient (i.e. black), but being sandboxed like this is often not an option when it comes to elegant product design.

Contrast can be unintuitive

I ran into this issue while tackling some pretty niche design challenges, but the solutions I came up with are widely applicable. One of PropelAuth’s main product offerings are login/signup/etc. pages that you theme and we host. All you really need to do is set a primary brand color, pick a light or dark background, and you’re off to the races. We’ll then style your login pages using that color for certain elements like buttons and links.

Unfortunately, it’s not as simple as setting color: $primary in a Sass file and calling it a day. Just because a certain color provides sufficient contrast between a button and a background, it doesn’t necessarily mean that it will do the same for text.

Believe it or not, that text is the exact same color as the button. Of course, if you have complete control over your website, you can just pick a darker or lighter text color to increase contrast. That isn’t an option when you’re dynamically theming a website using someone else’s color scheme, or when rendering text directly against gradient background, so we need to get a little creative here.

Getting good-enough contrast

The simplest possible solution is to lighten or darken your text color until it reaches the WCAG 2.0 recommended contrast threshold of 4.5/1. Contrast ratio is easy to calculate on the fly; you compare the relative luminance values of two colors by dividing the larger against the smaller, and you’ve got the resultant contrast value (which will be somewhere between 21 and 1). If you don’t want to write the luminance & contrast code yourself, you can do what I did and use the tinycolor2 library instead.

import tinycolor from "tinycolor2";

const makeColorReadable = (color: string, background: string): string => {
    const c = tinycolor(color);
    const bg = tinycolor(background);
    const isBackgroundDarker =
        bg.getLuminance() < c.getLuminance();

    while (
        // tinycolor.readability() returns the contrast ratio of two colors
        tinycolor.readability(bg, c) < 4.5 &&
        c.getLuminance() >= 0 &&
        c.getLuminance() <= 1
    ) {
        if (isBackgroundDarker) {
            c.lighten(1);
        } else {
            c.darken(1);
        }
    }

    return c.toHexString();
};

By applying this code to the pale purple primary color of the button from our earlier example, we can darken the shade into something that contrasts perfectly with the background while still matching the brand theme.

As discussed at the beginning of this post, this is only viable for a solid background, but the same logic applies to a simple solution for a gradient background. To get decent contrast on a gradient background without straying too far from your primary color, simply average the gradient background out and use this new, single color to perform your contrast calculations. Again, tinycolor2 comes in very handy here:

const averageGradientColor = tinycolor
        .mix(gradientColor1, gradientColor2, 50)
        .toHexString();
const newTextColor = makeColorReadable(primaryColor, averageGradientColor);

The results are pretty good, but not perfect. The text color is optimized for the center of the gradient, so there’s a bit of a Goldilocks thing going on:

Go a step further for pixel-perfect contrast

If we want truly perfect contrast for the text, agnostic of where it is on the page, we need to extend that dynamic contrast logic a bit. Rather than only calculating a single contrasting color, we can calculate one for each color that composed the background gradient. For our classic pink and purple example, that contrasting gradient would look like this:

From here, all we need to do is layer the contrast gradient on top of the original one and then use a text clipping mask and transparent text to effectively color the text with that gradient:

Voila! Perfectly contrasted text, no matter where we are on the page. The only vaguely tricky part of this technique is using multiple overlapping backgrounds, but a little position: absolute magic solves this nicely.

.pink-background {
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    background-position: center;
    background-size: cover;
    background-image: linear-gradient(180deg, white, pink);
}

.contrast-background {
    height: 100%;
    width: 100%;
    background-position: center;

    /* color1 & color2 are the contrasting colors */
    /* calculated against white and pink */
    background-image: linear-gradient(180deg, $color1, $color2);
    background-size: cover;
    background-clip: text;
}

.contrast-text {
    color: transparent;
}

<div>
    <div class="pink-background" />
    <div class="contrast-background">
        <p class="contrast-text">
            This text will be perfectly contrasted!
        </p>
    </div>
</div>

Summary

Achieving perfect contrast between text and a gradient background in web design is tough. However, by dynamically adjusting text color based on the WCAG 2.0 recommended contrast threshold, and using libraries like tinycolor2, it is possible to ensure legibility. For gradient backgrounds, the average color of the gradient can be used for contrast calculations. For pixel-perfect contrast, a contrasting gradient can be calculated and layered on top of the original one, with the text color effectively being the gradient.

Streamlit Authentication

propelauthblog — Fri, 19 Jan 2024 21:23:34 +0000

Streamlit is a powerful tool for creating “data apps.” The easiest way to understand it is with this picture (from Streamlit’s marketing site):

You write python code ⇒ You get an interactive web application.

It integrates easily with libraries you already know, like pandas and numpy. And the interactivity is way too easy, like this application where the age variable updates as the user changes the slider:

import streamlit as st

age = st.slider('How old are you?', 0, 130, 25)
st.write("I'm ", age, 'years old')

There’s no useEffect or worrying about re-renders or anything like that.

One small quirk… Authentication is difficult

Streamlit does have a few quirks, however, and one of them is that the out-of-the-box authentication options are limited.

We wanted an approach to authentication that was as simple as Streamlit is, but still powerful enough to include features like 2FA (including enrolling) and organizations (for your B2B apps). Ultimately, on the Streamlit side, it looks like this:

import streamlit as st

from propelauth import auth

user = auth.get_user()
if user is None:
    st.error('Unauthorized')
    st.stop()

with st.sidebar:
    st.link_button('Account', auth.get_account_url(), use_container_width=True)

st.text("Logged in as " + user.email + " with user ID " + user.user_id)

If the user isn’t logged in, nothing else runs. If they are logged in, you’ll get an object with their information.

So… how does this work? And what is the account page button on the sidebar?

To make this work, we rely on two PropelAuth features:

PropelAuth’s hosted pages. These are a set of UIs that we host for you on your domain. This includes everything you need for authentication (signup, login, forgot password, etc) but also extra UIs like an account page so your users can enroll in 2FA or update their information.
PropelAuth’s authentication proxy. This is a lightweight service which sits on top of Streamlit which will handle auth. If the user isn’t logged in, it’ll send them over to the login page. If they are logged in, it’ll pass their information securely to Streamlit.

Setting it up

The only thing you’ll need is a PropelAuth account. We’ll first look at how to set this up locally.

PropelAuth Test Environment Setup

The only unique thing to Streamlit is you’ll need the following configuration on the Frontend Integration page of the dashboard:

You can choose whichever port, but you must use /api/auth/callback for login and /api/auth/logout for logout. You will still be redirected back to your main page, but those will handle logging the user in/out.

You can then modify any of the other settings, like which login methods you want to support or if you allow signups or if you will be manually onboarding users.

Protecting Streamlit - Initialization

In your Streamlit project, install the propelauth-py library:

pip install propelauth_py

Then create a new file called propelauth.py and copy the following code in. This is a helper class which checks to see if the user is logged in or not.

from propelauth_py import init_base_auth, UnauthorizedException
from streamlit.web.server.websocket_headers import _get_websocket_headers

class Auth:
    def __init__(self, auth_url, integration_api_key):
        self.auth = init_base_auth(auth_url, integration_api_key)
        self.auth_url = auth_url

    def get_user(self):
        access_token = get_access_token()

        if not access_token:
            return None

        try:
            return self.auth.validate_access_token_and_get_user("Bearer " + access_token)
        except UnauthorizedException as err:
            print("Error validating access token", err)
            return None

    def get_account_url(self):
        return self.auth_url + "/account"

def get_access_token():
    headers = _get_websocket_headers()
    if headers is None:
        return None

    cookies = headers.get("Cookie") or headers.get("cookie") or ""
    for cookie in cookies.split(";"):
        split_cookie = cookie.split("=")
        if len(split_cookie) == 2 and split_cookie[0].strip() == "__pa_at":
            return split_cookie[1].strip()

    return None

At the bottom or in a separate file, add the following:

# Configuration, please edit
auth = Auth(
    "YOUR_AUTH_URL",
    "YOUR_API_KEY"
)

You can find these in the Backend Integration settings of your PropelAuth dashboard. You likely want to load them as environment variables instead of hardcoding them.

Protecting Streamlit - Usage

In your application, you can now use that snippet of code we had above:

import streamlit as st

from propelauth import auth

user = auth.get_user()
if user is None:
    st.error('Unauthorized')
    st.stop()

with st.sidebar:
    st.link_button('Account', auth.get_account_url(), use_container_width=True)

st.text("Logged in as " + user.email + " with user ID " + user.user_id)

If you go to test your app, you should see that you are never logged in and will get an Unauthorized error. We’ll fix that now.

Adding the Authentication Proxy

Next, we’re going to set up the proxy. Create a new directory called proxy and then install the proxy:

npm i @propelauth/auth-proxy

Then, create a file called proxy.mjs and add the following contents:

import { initializeAuthProxy } from '@propelauth/auth-proxy'

// Replace with your configuration
await initializeAuthProxy({
    authUrl: "YOUR_AUTH_URL",
    integrationApiKey: "YOUR_API_KEY",
    proxyPort: 8000,
    urlWhereYourProxyIsRunning: '<http://localhost:8000>',
    targetHost: 'localhost',
    targetPort: 8501,
})

The authUrl and API key are the same ones we used above (from the Backend Integration page of the dashboard). In this example, we were running the proxy locally on port 8000 (as you can see from the config), and we were running Streamlit locally on port 8501.

Once you have your streamlit app running, all you have to do is run it:

node proxy.mjs

Testing

If we go directly to http://localhost:8051, we will still see an unauthorized error, as we should always go through the proxy.

When we go to http://localhost:8000, however, we’ll be redirected to a login page. After logging in, we’ll be redirected back to our Streamlit app, and we’ll see our user’s information.

If we click the account button in the sidebar, we are redirected to a dedicated page for managing our account:

Deploying to Production with Docker

To go to production, you’ll just need a way to host the authentication proxy. If you are already deploying Streamlit with Docker, you can deploy the authentication proxy with Docker as well with this Dockerfile:

FROM node:20-slim
RUN mkdir -p /home/node/app/node_modules && chown -R node:node /home/node/app
WORKDIR /home/node/app
COPY package*.json ./
USER node
RUN npm install
COPY --chown=node:node . .
EXPOSE 8000
CMD [ "node", "proxy.mjs" ]

Your users will then go to the URL where your authentication proxy is hosted, and not the URL where Streamlit is hosted.

Depending on your infrastructure setup, you can actually keep Streamlit entirely private and only accessible from the proxy, but this isn’t a requirement. Users that go directly to Streamlit will always be met with an “Unauthorized” page.

And now you should be good to go! Just make sure you don’t forget to update your configuration with your production values from PropelAuth as well.

5 Common Pitfalls with Server Components in Next13 (with examples)

propelauthblog — Thu, 06 Jul 2023 18:47:15 +0000

The App Router is a new feature in NextJS 13, and it was recently switched to being the recommended option when you create a new NextJS application. This effectively replaces the Pages Router, and NextJS has documentation on how you can incrementally switch over.

The most notable difference in the App Router is that all components, by default, are Server Components instead of Client Components.

Server Components have a few big differences from their client component equivalent, and with that comes many possible points of confusion. Let’s look at a few common problems:

1. Trying to use React Hooks in Server Components

Let’s start with a really simple example. I just want to fetch and display a cat fact. If you have used React before, this pattern of using useEffect to trigger an initial fetch is probably pretty familiar:

import {useEffect, useState} from "react";

export default function Demo() {
    const [catFact, setCatFact] = useState<string | null>(null)

    useEffect(() => {
        fetch("https://catfact.ninja/fact")
            .then(response => response.json())
            .then(catFactJson => setCatFact(catFactJson["fact"]))
    }, [])

    if (catFact) {
        return <div>{catFact}</div>
    } else {
        return <div>Loading...</div>
    }
}

We’ll place this under app/demo/page.tsx and visit localhost:3000/demo awaiting our cat fact, only to get:

a ReactServerComponentsError.

The problem is that we are not able to use hooks like useState or useEffect in server components, as they don’t allow for any interactivity.

Now notably, there are actually two ways to fix the issue:

Fix: Add “use client” to the top of the file

Adding "use client" basically enables us to fall back to the behavior you are familiar with, whether you are coming from the Pages Router or just a normal React background.

The component is rendered in the browser, fetches will happen in the browser, and you can see it in your network tab.

This should all sound exceedingly normal, other than needing to add "use client" to the top of our file.

Alternative Fix: Convert it to a server component

In some cases, the hooks we were using weren’t necessary. In this specific case, we were just fetching data once when the component mounted. We could rewrite this more succinctly as a server component:

export default async function Demo() {
    const catFactResponse = await fetch("https://catfact.ninja/fact")
    const catFactJson = await catFactResponse.json()
    return <div>{catFactJson["fact"]}</div>
}

1b - Using Event Handlers (like onClick) in Server Components

To add to the “server components don’t allow for interactivity” idea, this server component won’t work:

export default function Demo() {
    return <button onClick={() => console.log("hi")}>
        A normal button
    </button>
}

We go ahead and try to load this component, only to be met with:

“Error: Event handlers cannot be passed to Client Component props”

and

“If you need interactivity, consider converting part of this to a Client Component.”

Fix: Add “use client” for interactive components

Anything interactive (a handler for clicking a button, a hook like useEffect) can only be inside of a client component. In this case, our normal button needs “use client” up top. There isn’t a server equivalent.

2. Importing a server component directly into a client component

Let’s say we want to take our previous example where we fetch cat facts and change it so we get a new Cat Fact every time the user clicks a button. We want something like this:

We can separate out our cat fact server component and pass some value in to trigger a re-render:

type Props = {
    heartbeat: number
}

// Note: This is incorrect, don't do this
export default async function CatFact({heartbeat}: Props) {
    const catFactResponse = await fetch("https://catfact.ninja/fact")
    const catFactJson = await catFactResponse.json()
    return <div>{catFactJson["fact"]}</div>
}

"use client"

import {useState} from "react";
import CatFact from "@/components/CatFact";

export default function Demo() {
    const [heartbeat, setHeartbeat] = useState(0)

    return <div>
        <CatFact heartbeat={heartbeat}/>
        <button onClick={() => setHeartbeat(h => h + 1)}>New Fact Please!</button>
    </div>
}

Now if you go to the page, you will see a cat fact, but the button doesn’t appear to work? And the network console tells a very different story:

There’s a lot to unpack here, namely:

Why are requests being made from the client? I’m using server components, no?
Why are there so many requests being made, to the point where we are getting rate limited? (really sorry to the Cat Fact folks for the spam, I thought this was a helpful example)

There are a few problems here, but the biggest is that we cannot import server components into client components. The specific thing that’s wrong is this line of code:

import CatFact from "@/components/CatFact";

Our CatFact component is now being treated like a client component, which is why we’re seeing the fetches in the browser, and now we’ve effectively just written a really inefficient component that infinitely refetches cat facts.

Fix: Convert this to a client component

It’s natural when a new cool abstraction exists to want to use it as much as possible. That being said, it’s important to note that while server components are useful, you need to know when to use them and when you don’t need them.

In this case, we can just go back to good old regular React components and hooks:

"use client"

import {useEffect, useState} from "react";

export default function Demo() {
    const [catFact, setCatFact] = useState<string | null>(null)
    const [heartbeat, setHeartbeat] = useState(0)

    useEffect(() => {
        fetch("https://catfact.ninja/fact")
            .then(response => response.json())
            .then(catFactJson => setCatFact(catFactJson["fact"]))
    }, [heartbeat])

    if (catFact) {
        return <div>
            <div>{catFact}</div>
            <button onClick={() => setHeartbeat(h => h+1)}>New Fact Please!</button>
        </div>
    } else {
        return <div>Loading...</div>
    }
}

Alternative Fix: Convert it (carefully) to a server component

It is possible for a server component to be a child of a client component; the only thing we cannot do is import the server component into our client code.

What we need to do instead is tell Next.js that our client component will have some child; we just can’t directly reference the CatFact component.

Let’s make a new component for this, CatFactLoader:

"use client"

import React from "react";
import {useRouter} from "next/navigation";

type CatFactLoaderProps = {
    children: React.ReactNode
}

export default function CatFactLoader({children}: CatFactLoaderProps) {
    const router = useRouter()
    return <div>
        {children}
        <button onClick={() => router.refresh()}>New Fact Please!</button>
    </div>
}

Update CatFact, which will, unfortunately, cache the facts by default:

export default async function CatFact() {
    const catFactResponse = await fetch("https://catfact.ninja/fact", {
        // small note - next.js will cache the cat fact, which we can turn off
        cache: 'no-store'
    })
    const catFactJson = await catFactResponse.json()
    return <div>{catFactJson["fact"]}</div>
}

and update our Demo component with a Server component that composes the two:

import CatFactLoader from "@/components/CatFactLoader";
import CatFact from "@/components/CatFact";

export default function Demo() {
    return <CatFactLoader>
        <CatFact />
    </CatFactLoader>
}

And this works - however, it’s up to you to decide which pattern you like more.

Speaking of weird patterns, why did we need router.refresh() in the client…

3. Assuming Server Components Re-render

One of the first examples of React code that most people see is the counter example:

function MyButton() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <button onClick={handleClick}>
      Clicked {count} times
    </button>
  );
}

And this displays an important concept - when the state is updated, the button re-renders.

Server components obviously don’t have state (see 1 up above), but you can use things like cookies:

export default function CookieRenderer() {
    const name = cookies().get("name")?.value

    if (name) {
        return <div>Hello, {name}!</div>
    } else {
        return <div>Hello, there!</div>
    }
}

You may think that when a new cookie is set, this component would re-render, but it doesn’t. This is maybe more obviously true if your server component makes calls to your database:

export default async function Demo() {
    const comments = db.select()
        .from(commentsTable)
        .orderBy(desc(commentsTable.createdAt))
        .limit(10)
        .all()

    return <div>
        {comments.map(comment => <Comment comment={comment} />)}
    </div>
}

This is notably something we, at PropelAuth, dealt with a lot as we provide functions like:

export default async function Demo() {
    const user = getUserOrRedirect()
    return <div>Hello {user.firstName}</div>
}

but we want to make sure that name changes appropriately trigger re-renders and you don’t have inconsistencies between different tabs within your application.

Fix: Rely on routing changes

While there are better options in the works, router.refresh() or router.replace(router.asPath) are simple options that will trigger all server components to re-render. You do need to do some work to detect when these changes happen, however.

4. Setting cookies in a server component

While you can read cookies in server components:

export default function CookieDisplayer() {
    const cookieValue = cookies().get("test")?.value
    return <pre>{cookieValue}</pre>
}

And you can call set:

export default async function Header() {
    const abTestingGroup = cookies().get("ab-testing-group")?.value
    if (!abTestingGroup) {
        cookies().set("ab-testing-group", getRandomGroup())
    }
    if (abTestingGroup === "OPTIMISTIC") {
        return <h1>We're the best</h1>
    } else {
        return <h1>Our competitors are the worst</h1>
    }
}

This doesn’t actually work:

The error message here, “Cookies can only be modified in a Server Action or Route Handler” does describe two possible fixes, although we’ll also discuss a third (middleware).

Fix: Use Route Handlers

If you are coming from the pages router, route handlers are basically just API routes. They are served from a route.ts file, and you can set cookies in them:

export async function GET() {
    const abTestingGroup = cookies().get("ab-testing-group")?.value
    const defaultGroup = getRandomGroup()
    if (!abTestingGroup) {
        cookies().set("ab-testing-group", defaultGroup, {httpOnly: true, secure: true, sameSite: "strict"})
    }
    return NextResponse.json({"ab-testing-group": abTestingGroup || defaultGroup})
}

This obviously is a little less convenient than doing it directly in the component, but you can then read these cookies in your server components.

Alternative Fix: Use Middleware

Another option is to use middleware to set the cookie, with a few caveats:

export function middleware(request: NextRequest) {
    const abTestingGroup = request.cookies.get("ab-testing-group")?.value

    // TODO: if it's not set... how do I set this group on the request??

    const nextResponse = NextResponse.next()

    // Make sure to set the cookie on the response
    if (!abTestingGroup) {
        nextResponse.cookies.set("ab-testing-group", getRandomGroup(), {httpOnly: true, secure: true, sameSite: "strict"})
    }
    return nextResponse
}

This makes it easy to set a cookie on the response but not the request. While it might seem natural to just do:

request.cookies.set(...)

This also doesn’t work. There are a few open issues, so it may work someday, but for now, a good workaround is to pass in your own header:

export function middleware(request: NextRequest) {
    const abTestingGroup = request.cookies.get("ab-testing-group")?.value
    const defaultGroup = getRandomGroup()

    const headers = new Headers(request.headers)
    headers.append("X-Ab-Testing-Group", abTestingGroup || defaultGroup)

    const nextResponse = NextResponse.next({
        request: {
            headers
        }
    })

    // Make sure to set a on the response
    if (!abTestingGroup) {
        nextResponse.cookies.set("ab-testing-group", defaultGroup, {httpOnly: true, secure: true, sameSite: "strict"})
    }
    return nextResponse
}

and then you can use the header instead of the cookie in your server components/routes.

Note: Server actions are alpha

As of writing this, server actions are still an alpha feature, so you might want to shy away from this until it’s stable.

5. Trying to pass non-serializable props from server to client

Let’s say we now wanted our facts to have IDs associated with them. For now, we’re just going to hash the text to get an ID. We decide to write a quick class to encapsulate all the logic:

export class CatFactHelper {
    public readonly fact: string
    constructor({ fact }: { fact: string }) {
        this.fact = fact
    }

    public hash(): string {
        return sha256(this.fact)
    }
}

We then make a client component to render the fact and its ID:

"use client"

import {CatFactHelper} from "@/components/CatFact";

type Props = {
    catFactHelper: CatFactHelper
}

export default function CatFactDisplay({catFactHelper}: Props) {
    return <div>
        ID: {catFactHelper.hash()}<br/>
        Fact: {catFactHelper.fact}
    </div>
}

And we update our server component to use this:

export default async function CatFact() {
    const catFactResponse = await fetch("https://catfact.ninja/fact", {
        cache: 'no-store'
    })
    const catFactHelper = new CatFactHelper(await catFactResponse.json())
    return <CatFactDisplay catFactHelper={catFactHelper} />
}

We are met with this strange error:

What’s also strange is if we log the catFactHelper we do see the fact.

However, your IDE can give a good hint at what’s going on:

“Props must be serializable for components in the “use client” entry file”

The problem is our object on the server is serialized to JSON when it’s sent to the client. This object can be serialized to JSON, but the object on the client is equivalent to:

{
  "fact": "the cat fact"
}

instead of the CatFactHelper class with the hash function.

Fix: Only send serializable props to client components

This means no classes or functions. If you really want to use CatFactHelper, you should construct it on the client:

type Props = {
    fact: string
}

export default function CatFactDisplay({fact}: Props) {
    const catFactHelper = new CatFactHelper({fact})
    return <div>
        ID: {catFactHelper.hash()}<br/>
        Fact: {catFactHelper.fact}
    </div>
}

Summary

Server Components are a powerful feature in Next13, but they also have some gotchas to be aware of. In this post, we went over things like re-rendering server components, avoiding importing server components in client components, and when you need to add “use client” to your components.

Abra-QR-dabra: Watch Passwordless Mobile Auth Magically Appear

propelauthblog — Thu, 01 Jun 2023 23:27:48 +0000

A few days ago, a post on hacker news caught my eye, where folks were playing around with and linking to various QR Code designers. This got me to thinking, how quickly could I add a QR flow into our authentication processes?

Starting Out

For ease and speed, I wanted to work with a preexisting application to see how quickly I could slot this feature in, without needing to spend time with setup. To that end, I started up our React/Express Starter Application as a base. Reminder, this is how the application looks at the end of our starter guide:

In terms of flow for the application, I thought about a kind of product that requires some version of mobile interaction after setting up an account on the browser. Think of a product like PagerDuty, which is used to send alerts when issues arise. Most customers that are configuring PagerDuty are going to use their desktop to set up their on-call schedule, generate API keys, etc.

However, an important step in the process is setting up your phone, for use cases like adding PagerDuty’s phone numbers to the exceptions to your DND settings. So one way to move customers from their desktop to their phones is to send them a magic link, which we can put in a QR code.

So the expected flow for this use case would be:

The user is already logged in on their laptop/desktop
The user needs to be logged in on their mobile device
We generate a magic link on the backend and return it to the browser
We render that as a QR code so the user can easily sign in on their mobile device
(Optional) We can direct them to a specific page so they are dropped in to the product exactly where they need to be

To begin, I set up another route for the page that would display the QR code, and built that component, called qr.jsx. Next, I installed a React friendly QR code generator

npm install qrcode.react

In the new component, I wrote a fetching function that would reach out to a new endpoint, ‘/generate-mobile-login-link’. Next, the component calls this function, and renders the response as a QR code generated from the library we imported.

import { withRequiredAuthInfo} from "@propelauth/react";
import { QRCodeSVG } from 'qrcode.react';
import { useEffect, useState } from "react";

function fecthNewLink(accessToken) {
    return fetch(`/generate-mobile-login-link`, {
        headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${accessToken}`
        }
    }).then(response => {
        console.log('response in fetch: ', response)
        if (response.ok) {
            return response.json()
        } else {
            return {status: response.status}
        }
    })
}

function QR({ accessToken }) {
    const [response, setResponse] = useState(null)

    useEffect(() => {
        fecthNewLink(accessToken).then(setResponse)
    }, [accessToken])

    if (response) {
        return <div>
            <QRCodeSVG value={JSON.stringify(response.newLink)} />
        </div>
    } else {
        return <div>Loading...</div>
    }
}

export default withRequiredAuthInfo(QR);

Creating a Magic Link

We have an endpoint in our backend client libraries that will take in a user’s email, along with a few other optional parameters, and produce a Magic Link for passwordless login.

So in order to produce this link, I added the new /generate-mobile-login-link route that I’m pointing to on my frontend, and used the createMagicLink function to pass this new URL back as a successful response. requireUser checks the token in the request to make sure it was made by a valid user, and then the new magic link is sent back in JSON.

app.get('/generate-mobile-login-link', requireUser, async (req, res) => {
    let newLink = await createMagicLink({
        email: req.user.email
    })

    res.json({ newLink: newLink})
})

How Does It Work?

Pretty well! You can see the new page below making successful calls to the server.

Granted, this is the MVP version of this kind of authentication flow. For a real product you might want to put this in a modal or as part of your onboarding flow.

That said, one optional parameter for the createMagicLink function is another URL to redirect to after the user is logged in, so in a production ready application I could be forwarding my users to additional setup or permissions pages.

I could also get much fancier with it! The mini project was inspired by QR code designers, so I could work in libraries like the ones mentioned in the hacker news post.

Or, go even wilder, using Halftone QR Codes like you can see here:

All in all, this was a fun exercise in working with our client libraries in ways that let me customize an authentication experience even more. We already offer easy passwordless login options via our hosted login pages, but it was fun to use the building blocks to make things more my own.

Using useMutation to make an advanced toggle in React

propelauthblog — Thu, 25 May 2023 16:29:02 +0000

Recently, we were adding some new functionality to our dashboard, and we wanted an experience like this:

The basic features are:

The toggle should make an external request when clicked to change the setting
While the request is being made, a loading spinner should appear next to the toggle
If the request succeeds, a check mark is displayed
The toggle should update optimistically, meaning it assumes the request will succeed
If the request fails, a red X is displayed and the toggle switches back to the current state

Using useQuery and useMutation

If our whole dashboard was just this one toggle, this would be a simpler challenge. However, we also fetch and update other values.

To manage our state, we use React Query, specifically useQuery and useMutation.

If you haven’t used it before, useQuery enables a straightforward interface for fetching data:

const {isLoading, error, data} = useQuery("config", fetchConfig)

and it comes with caching, re-fetching options, synchronizing state across your application, and more.

useMutation , as you probably expect, is the write to useQuery's read. The “Hello, World” of useMutation looks like this:

const { mutate } = useMutation({
    mutationFn: (partialConfigUpdate: Partial<Config>) => {
        return axios.patch('/config', partialConfigUpdate)
    },
})

// later on
const handleSubmit = (e) => {
    e.preventDefault();
    mutate({new_setting_value: e.target.checked});
}

In this UI, we are using a patch request to update some subset of our Config. The only problem is that with that code snippet alone, our UI won’t immediately update to reflect the new state.

Optimistic Updates

useMutation has a few lifecycle hooks that we can use to update our data:

useMutation({
    mutationFn: updateConfig,

    onMutate: (partialConfigUpdate) => {
        // this is called before the mutation
        // you can return a "context" object here which is passed in to the other 
        //   lifecycle hooks like onError and onSettled
        return { foo: "bar" }
    },
    onSuccess: (mutationResponse, partialConfigUpdate, context) => {
        // called if the mutation succeeds with the mutation's response
    }
    onError: (err, partialConfigUpdate, context) => {
        // called if the mutation fails with the error 
    },
    onSettled: (mutationResponse, err, partialConfigUpdate, context) => {
        // always called after a successful or failed mutation
    },
})

You can combine this with a QueryClient, which lets you interact with cached data.

To solve our issue where the UI wasn’t updating to reflect the new state, we can just invalidate the cache after it succeeds:

useMutation({
    mutationFn: updateConfig,
    onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: ['config'] })
    },
})

While this does technically work, it relies on us making an additional request after the mutation succeeded. If that request is slow, our UI might be slow to update.

If the mutation request returns the updated config, we have another option:

useMutation({
    mutationFn: updateConfig,
    onSuccess: (mutationResponse) => {
        // on successful mutation, update the cache with the new value
        queryClient.setQueryData(['config'], mutationResponse)

        // not strictly necessary, but we can also trigger a refetch to be safe
        queryClient.invalidateQueries({ queryKey: ['config'] })
    },
})

where we just set the data in the cache directly with our response.

One thing to note here though, is we do actually know the change we are making. If our config was: {a: 1, b: 2, c: 3} and we wanted to update a's value to be 5, we don’t really need to wait for the mutation response. The thing to be careful about, however, is we need to make sure to undo our change if the mutation fails.

useMutation({
    mutationFn: updateConfig,

    onMutate: async (partialConfigUpdate) => {
        // Cancel any outgoing refetches
        // (so they don't overwrite our optimistic update)
        await queryClient.cancelQueries({ queryKey: ['config'] })

        // Snapshot the previous value
        const previousConfig = queryClient.getQueryData(['config'])

        // Optimistically update to the new value
        queryClient.setQueryData(['config'], (oldConfig) => {
            ...oldConfig,
            ...partialConfigUpdate,
        })

        // Return a context object with the snapshotted value
        return { previousConfig }
    },
    onError: (err, partialConfigUpdate, context) => {
        // roll back our config update using the context
        queryClient.setQueryData(['config'], context?.previousConfig)
    },
    onSettled: (mutationResponse, err, partialConfigUpdate, context) => {
        // Other config changes could've happened, let's trigger a refetch
        //   but notably, our UI has been correct since the mutation started
        queryClient.invalidateQueries({ queryKey: ['config'] })
    },
})

(see here for the original source)

This is a little more involved, but it does update immediately and this doesn’t depend on the mutation’s response. Next, let’s add Loading, Success, and Error icons.

Adding Loading/Success/Error Icons with useTimeout

useMutation does actually come with status information that we could just use directly, however, we want to control how long the ✅ and ❌ icons stay on the screen for.

We use this pattern enough times that we’ve turned it into a hook — let’s first look at the version with no timers:

type FeedbackIndicatorStatus =
    | "loading"
    | "success"
    | "error"
    | undefined;

export const useFeedbackIndicator = () => {
    const [status, setStatus] = useState<FeedbackIndicatorStatus>();
    const setTimerToClearStatus = // TODO: how?

    // default is to display nothing
    let indicator = null;
    if (status === "loading") {
        indicator = <Loading />;
    } else if (status === "success") {
        indicator = <IconCheck />;
    } else if (status === "error") {
        indicator = <IconX />;
    }

    const setLoading = () => setStatus("loading");
    const setSuccess = () => {
        setStatus("success");
        setupTimerToClearStatus();
    };
    const setError = () => {
        setStatus("error");
        setupTimerToClearStatus();
    };
    return { indicator, setLoading, setSuccess, setError };
}

setTimeout can be a little tricky to use in React because you have to make sure to clear the timeout if the component unmounts. Luckily, we don’t have to worry about any of that as there are many implementations of useTimeout - a React hook that wraps setTimeout. We’ll use Mantine’s hook to complete the code snippet:

const { start: setupTimerToClearStatus } = useTimeout(
    () => setStatus(undefined),
    1000
);

And now, when setupTimerToClearStatus is called, after a second, the status is cleared and indicator will be null.

Combining it into a re-usable React hook

We now have all the pieces that we need. We can use useQuery to fetch data. We have a version of useMutation that lets us optimistically update the data that useQuery returns. And we have a hook that displays Loading, Success, and Error indicators.

Let’s put all of that together in a single hook:

import { useState } from "react";
import { QueryKey, useMutation, useQueryClient } from "react-query";

export function useAutoUpdatingMutation<T, M>(
    mutationKey: QueryKey,

    // the mutation itself
    mutationFn: (value: M) => Promise<void>,

    // Combining the existing data with our mutation
    updater: (oldData: T, value: M) => T
) {
    const { indicator, setLoading, setSuccess, setError } = useFeedbackIndicator();
    const queryClient = useQueryClient();

    const mutation = useMutation(mutationFn,
        {
            onMutate: async (value: M) => {
                setLoading();

                // Cancel existing queries
                await queryClient.cancelQueries(mutationKey);

                // Edge case: The existing query data could be undefined
                // If that does happen, we don't update the query data
                const previousData = queryClient.getQueryData<T>(mutationKey);
                if (previousData) {
                    queryClient.setQueryData(
                        mutationKey,
                        updater(previousData, value)
                    );
                }
                return { previousData };
            },
            onSuccess: () => {
                setSuccess();
            },
            onError: (err, _, context) => {
                setError();

                // Revert to the old query state
                queryClient.setQueryData(mutationKey, context?.previousData);
            },
            onSettled: async () => {
                // Retrigger fetches
                await queryClient.invalidateQueries(mutationKey);
            },
        }
    );

    return { indicator, mutation };
}

That’s a lot of code, but let’s see what its like to use it:

// Our query for fetching data
const { isLoading, error, data } = useQuery("config", fetchConfig)

// Our updater which performs the opportunistic update
const updater = (existingConfig: Config, partialConfigUpdate: Partial<Config>) => {
  return { ...existingConfig, ...partialConfigUpdate }
}

// Our hook which returns the mutation and a status indicator
const { indicator, mutation } = useAutoUpdatingMutation("config", updateConfig, updater)

// ... later on when displaying settings

<div>
    {indicator}
    <Toggle type="checkbox" 
            checked={data.mySetting} 
            onChange={e => mutation.mutate({
                mySetting: e.target.checked
            })}
            disabled={!!indicator} />
</div>

Pretty straightforward, we just supply our API call and our update function and we are done. When we click the toggle, it will:

Update the toggle’s checked state
Disable the toggle until the request is complete
Make a request to update mySetting
If it fails, revert the toggle back to it’s original state

Wrapping up

React Query provides some powerful abstractions for fetching and modifying data. In this example, we wanted a version of useMutation that both updates the server state immediately and provides a status indicator for the request itself. By using useMutation's hooks, we were able to make a hook specific to our use case that can be reused for all our config updates.

Who can sign up for your product?

propelauthblog — Thu, 18 May 2023 16:05:00 +0000

At PropelAuth, we believe that your authentication requirements will change over time. The features you need when building your MVP are very different from those you need as a Series C company.

One of the best examples of this is how you handle signups. So let’s look at a few decisions you’ll have to make (and periodically revisit) when figuring out how users access your product.

Self-Service Signup, Sales-led Signup, or Both

One of the first questions you’ll want to answer is: how does someone go from being a prospect to a customer?

One reasonable answer is to just create a signup page. Creating a public-facing signup page can be both exhilarating and a little terrifying. Any random person can read your marketing site, sign up, and start using the product.

However, depending on your stage and your product, you might not want that. The alternative is to disable the signup page and onboard your customers manually.

Why not allow anyone to signup?

Two common reasons we see people disabling signups are:

The product isn’t ready. Only a few select customers should have early access.
Each signup requires manual intervention. This could be the provisioning of resources, contract negotiation, agreement on pricing, etc.

It’s important to note that the decision is not “Should I allow my customers to self-serve onboarding OR should I set up accounts for my customers?” You may want to do both.

When would you want both self-serve and manual onboarding?

A typical trajectory that we see in Product Led Growth (PLG) companies is:

“The product is not ready yet. Let’s manually onboard trusted early users while we collect feedback.”
“The product is ready! Let anyone sign up! No more manual onboarding!”
“We’re starting to see traction among larger companies. Let’s go back to manual onboarding, but just for these customers.”

In the end, you are both letting some users sign up themselves, and some users are being onboarded manually.

Personal emails vs Work emails

If you decide to let anyone sign up, you then need to answer the question of if you actually want… anyone?

For some products, the answer is clearly yes. GitHub, for example, caters to any developer, whether working on a side project or something for their job.

For other products, the answer is clearly no. Take Clearbit, for example, a tool for enriching B2B leads. I don’t know about you, but I’m not enriching B2B leads in my free time. It’s pretty clearly designed with larger companies in mind, and you’d expect everyone using the product to have a work email.

By restricting signups to only those with a work email, you can save a few support tickets that look like “I accidentally signed up with my personal email. Could you transfer it to my work email instead?”

Enterprise user onboarding

Let’s look beyond a single user at a time. If you are building a B2B/multi-tenant product, your customers are not individuals; they are organizations.

We’ve talked about how the first user can be onboarded (signing up themselves, onboarded by you), but what about that user’s coworkers?

Onboarding coworkers

There are a few typical strategies:

Allow that first user to invite their coworkers.
Anyone with a matching email domain (e.g. @company.com) can automatically join.
Allow the first user to set up a SAML connection.

Which one you choose often depends on the size of the companies you work with. Smaller companies will be okay with inviting their few other employees. Larger companies, on the other hand, use a lot more products. They usually don’t want to have every single employee:

Figure out which products they need access to
Request access to different products
Sign up for those products
Have their accounts configured within the product

Instead, they’d prefer that their employees immediately have access to everything they need to do their job from day 1.

A SAML connection allows your customers to perform a one-time integration with you. Then they can roll you out to the entire company (or just a subset). Your product can even be listed in a dashboard of products they have access to:

If you are primarily working with smaller companies, you’ll want to prioritize fast, simple methods like invitations or matching email domains. If you work with larger companies, you’ll want to prioritize SAML, so they can quickly give access to your product to everyone that needs it.

PropelAuth can help onboard your customers

As we’ve seen, it’s natural to eventually have both a self-serve onboarding flow and a more traditional sales-led onboarding flow.

To help you with this, PropelAuth provides an internal dashboard for your team so you can easily set up customer accounts. There are also APIs so you can automate account creation.

You can also disable or enable public signups with a single click.

For personal emails, PropelAuth also makes this decision easy. You can enable or disable personal email signups by flipping this switch:

PropelAuth was designed with B2B products in mind. We provide configurable UIs so your users can invite their coworkers or allow anyone to join their organization by email domain. We also offer SAML support, so all you have to do is check the box that says “Can they setup SAML?”:

and your users will be able to set up a SAML connection with you using our step-by-step wizards. We take care of the rest.

Interested in learning more? Feel free to reach out to us at support@propelauth.com, or you can sign up directly here.

What My Cousin Vinny can teach us about debugging

propelauthblog — Tue, 16 May 2023 18:02:05 +0000

If you haven’t seen My Cousin Vinny yet, go watch it real quick, we’ll wait.

Great movie, right? Marisa Tomei absolutely deserved her Academy Award.

In case you didn’t watch a whole movie in between the first and second line of this post, the central plot of the movie involves two people on trial for a crime they didn’t commit. There are multiple witnesses who all claim to have seen them and they call up one of their cousins (Vinny) to defend them (this summary doesn’t come close to doing it justice though).

What does that have to do with debugging customer issues? Well, there’s actually a few things:

Witnesses are unreliable

If you’ve ever been in Customer Success, or just been on the receiving end of an unusual ticket that you need to fix, you know that your customer’s account of what’s happening is just one piece of the puzzle.

And while I would recommend…

Pictured here: not an ideal customer success strategy

…yelling at them until they admit that grits take 20 minutes to cook (or whatever your products version of that is), you should clarify exactly what the user is seeing. That way you won’t waste a ton of time chasing down the wrong issue.

A simple comment like “I can’t edit my settings” could mean anything from “Your APIs are down” to “The validation error isn’t displaying correctly” to “Someone changed my permissions and I am not allowed to edit settings anymore.” One of those isn’t even a bug!

Your questions might be BS

It’s really easy when you know your product inside and out to make assumptions about what a bug can be. The unfortunate truth is that those assumptions can blind you to real issues.

Pictured here: your users as you ask a BS question

This can be made worse if you go into a debugging situation assuming the customer doesn’t know as much as they do.

This might feel somewhat contradictory to the first point, but I don’t think it is. Your customers can be mistaken or use different language than you would use, but they still are seeing behavior that they weren’t expecting. If you ask your questions assuming you already know the answer, you might end up missing the real customer issue or a scarier underlying bug.

If only I knew what he knows

While having a conversation with a customer about what they are seeing is a good first step, you may need to rely on other sources to help you fix it. You can think of the entire process as collecting evidence and the conversation/bug report is just one piece of that.

There are tools like Sentry which can provide stack traces or you can set up an ELK stack for managing your logs/traces. At PropelAuth, we introduced user impersonation so you log into your product as your customer and see what they see.

The amount of evidence you need to gather will vary depending on the situation. However, having a few tools in your toolbelt ahead of time will simplify any process that involves debugging customer issues.

Closing arguments

Debugging may seem like a simple process, but it actually can be incredibly noisy. The next time you are struggling with a bug that you just can’t reproduce, try rechecking your assumptions. Does the user’s report of what happened make sense or do you need to clarify something? Is there more information you can gather that will help you get to the bottom of it?

If you aren’t careful, you might be accidentally convicted of murder (or… you know, whatever your product’s equivalent of that is).

What Does Identity Provider Actually Mean?

propelauthblog — Mon, 24 Apr 2023 17:15:32 +0000

When it comes to online security and authentication, the term “Identity Provider” is often thrown around. But what does it actually mean? In simple terms, an Identity Provider (IdP) is a trusted service that authenticates and verifies the identity of users and provides them with access to protected resources.

In other words, an IdP acts as a gatekeeper between the user and the resource they are trying to access. Instead of requiring the user to provide their credentials (such as a username and password) to each individual resource they want to access, the user provides their credentials to the IdP once, and the IdP then vouches for their identity to any resource that trusts it.

This can be particularly useful in scenarios where multiple resources need to be accessed using the same set of credentials. For example, in a situation where a company uses SAML Authentication, a user may have a single set of credentials for their company’s internal resources, such as email, HR systems, and project management tools. By using an IdP, the user only needs to provide their credentials once to gain access to all of these resources, rather than entering their credentials individually for each one.

Another advantage of using an IdP is that it can provide additional security features such as multi-factor authentication (MFA), which requires the user to provide additional proof of their identity before gaining access to a resource. MFA can include something the user knows (such as a password), something they have (such as a token or smart card), or something they are (such as a fingerprint or facial recognition).

So, what are some common examples of IdPs? One of the most well-known is Google, which provides an IdP service called Google Sign-In. This allows users to log in to third-party websites and applications using their Google credentials. Some companies uses IdPs like Okta, Rippling, and Jumpcloud to manage their employees. Other popular IdPs include Facebook, Microsoft, and LinkedIn.

An Identity Provider is a crucial component of modern online security and authentication systems. By acting as a trusted third-party service, an IdP can help simplify the process of accessing multiple resources using a single set of credentials, while also providing additional security features to protect user accounts. With PropelAuth, we can help you integrate with popular IdPs whether it’s Google, LinkedIn, or IdPs used more for workforce management like Okta, Azure AD, JumpCloud.