Walk Through

Creating an App

The first step is to create a new App in the dashboard. You will need to give the app a name, decided whether to allow refresh tokens, and where to redirect users who authenticate using magic links. You also set a threshold to be notified if you are nearing your allotted authentications. (Billing is done by pre-purchasing a certain number of authentication attempts for your account which never expire)

Once you send the form, your app is saved as a document in MongoDB associated with your account (which was auto-created on your first login). The backend will generate a unique id and secret keys for your app and show you the created app. You will need your app id to implement the authentication on your site, but it's not a secret so it can be viewed at any time. You will also need the public portion of the generated keys. If you use my authentication client for Python, this is handled automatically.

Updating and Deleting

In addition to viewing your created app, you can also edit the app's attributes (except the app id), rotate the secret keys, and delete the app. Editing the name and URLs for the app shouldn't break anything and users likely won't notice.

Rotating the keys will immediately invalidate all active user sessions and everyone will need to re-authenticate. You will also need to ensure that the new keys are downloaded anywhere they are needed and removed from any caches. This is your only real recourse if tokens become compromised. However, re-authenticating someone isn't that big of a deal. They would have had to sign back in tomorrow anyway since refresh tokens only last 24 hours.

To prevent accidental deletion, which could be catastrophic for a production application, I've enabled deletion protection by default. It is straightforward to since the system will walk you through it, but very difficult to do by accident.

Using Purple Authentication

Now that you have an app setup, you will need to add it to your site. You can either access the REST API directly, or use my authentication client for python, or access the REST API directly. FastAPI (which is the basis for this system) generates documentation automatically, so the best way to understand the api is to look at them .

Briefly, your site/app sends a request to my server with your app id from the dashboard and a user email. I will generate either a secret code or magic link and store that hashed secret with the email and app id in a redis cache for five minutes and email it to the user.

Link Authentication

If the user/you chose magic link authentication, all they have to do is click the link in their email. They will first be taken to Purple Authentication to have their secret code authenticated, then be redirected to the configured URL depending on whether the authentication was successful or not. If it was successful, an id token and refresh token (if enabled) will be included in the query string of the URL. You can then save that in a cookie (or whatever) and use it to authenticate the user.

Code Authentication

If the user/you chose one time code authentication, they will enter the code they were sent on your site, which you then submit for validation. If it is the correct code and hasn't expired, the backend will send back a payload with the user's new tokens to be saved on the client.

Validating Tokens

All tokens generated by Purple Auth are JWTs. ID Tokens can be validated using the public portion of your app key accessible on the API. Tokens all use the ES256 algorithm. User email is in the "sub" claim. Everything else is standard. The API docs show where to get the public key. The easiest way will be to use my authentication client, but you can also send tokens to the API for validation. This is going to be very slow at scale compared to using the client or doing it yourself.

Refresh tokens can only be authenticated by sending them to the refresh endpoint. If the token is valid, a new ID Token will be generated and sent back.

User Management and Authorization

I don't do it. Purple Auth handles authentication only. This system will verify that someone is the email address they say they are, but nothing more. It doesn't handle any authorization, doesn't store information about users, and doesn't limit who can log in. If you want any of that, you have to do it yourself. Anyone with an email address can be authenticated against any app unless there are restrictions somewhere else in the chain.

Portal Authentication

Of course, you have to authenticate yourself in order to access your apps dashboard and create/edit apps. Naturally, Purple Auth uses itself for authentication. Purple Auth uses purple-auth-client to access itself and authenticate users. It's open source, so if you want to see a reference implementation (or the whole thing), you can! Check out the portal folder. You can even host it yourself if you want. The only real difference from a production app is that it's been hard-coded to app id 0 and cannot be deleted, and its own url is used as the endpoint for the auth client (rather than https://purpleauth.com). This is really just for easier development and testing.