potber-auth is a semi-compliant OAuth authorization service built with svelte. It provides clients with an API for authenticating and authorizing users on the german `forum.mods.de` board. The API is easy to use and follows the OAuth specification, albeit with limited functionality and compliance. The live service can be found at auth.potber.de. Consuming apps needs to be allowlisted first (more on that below).
potber-auth offers authentication according to the OAuth 2.0 specification, specifically via the Implicit Grant flow. Feel free to check out the specification or simply follow these steps:
Start by creating a pull request that changes the list of known clients and inserts a new entry representing your application. Make sure to follow the following syntax:
{
name: 'my-app',
id: '6c4defe9-4e08-420a-90ab-dbce69906fef',
allowedRedirectUris: [
'https://my-app.com/auth/callback'
]
}ℹ
idneeds to be a newly generatedUUID(Version 4). There are online generators where you can generate such an id, for example this one.
Make sure that you include the entire URI (including the protocol, the domain name and the entire path). Make sure that you get the details right (e.g. trailing slashes). If you need more than one URI allowlisted, make sure to include them all.
The redirect_uri is a web page that you want potber-auth to redirect the user after a succesful login. On that page, you will be able to retrieve token and use it in your application.
When you want your users to sign in, redirect them to potber-auth. This step is called the Authorization Request. Using the example from earlier, the request would look like this:
https://auth.potber.de/authorize?response_type=token&client_id=6c4defe9-4e08-420a-90ab-dbce69906fef&redirect_uri=https%3A%2F%2Fmy-app.com%2Fauth%2Fcallback
ℹ Note that you will likely need to encode your URI. For example in JavaScript, you can use encodeURIComponent.
Let's break down the Authorization Request:
response_type(required) The response type. MUST betokensince other flows are currently not supported.client_id(required) Your application's client id as specified here,redirect_uri(required) The URI that the user should be redirected to after a successful login. Must match whatever has been specified here.
After the user has signed in, potber-auth will then redirect them back to your application using redirect_uri. This step is called the Access Token Response. Assuming the redirect_uri from above, the request will look like this:
GET https://my-app.com/auth/callback#access_token=...&token_type=bearer&expires_in=3600
Let's break down the Access Token Response:
acccess_tokencontains the JWT that encodes the entire session. You can use it to authenticate a user towardspotber-apior simply validate whether the user has been able to log in at all. If you're interested in the details of the session (e.g. the username of the user), you can decode the token yourself or usepotber-api's GET /auth/session endpoint (more on that later).token_typetells the client that the token is of typeBearer(potber-authdoes not support other token types). Tokens of typeBearerare sent in subsequent requests using the following syntax (with...representing the token):
GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer ...
expires_inrepresents the number of seconds until the session expires. When that happens, the token will no longer be accepted bypotber-api.
When the user is being redirected to your application via the access token response, you will likely want to retrieve the access_token from the fragment identifier (that's the part that comes after the # symbol) and store it (e.g. in a cookie). It's a good idea to make sure that the cookie expires when the session expires to achieve the best user experience as well as security reasons.
If you simply wanted users to log in (e.g. to make sure that only users with access to the forum can use your application), you can stop at this point. However, if you want to go the extra mile and really make sure that the user has a valid session, you can always check with potber-api. When doing so, you only need to make sure to include the token:
GET /auth/session HTTP/1.1
Host: api.potber.de
Authorization: Bearer ...
ℹ Note that this also applies to all other endpoints of
potber-api. If you want to send an authenticated request, always include the token as shown here.
If the response contains status code 200 and a body containing information about the session (like the username), the session is valid. If it contains 401, the session is invalid or has expired.
As mentioned earlier, potber-auth is semi-compliant in regards to the OAuth specification. The following chapter describes its limitations as well as how and why it differs from the spec.
potber-auth does not provide support for any OAuth flows besides Implicit Grant. This means that more secure flows like Authorization Code Grant are currently not supported. The reason for this is that potber-auth is a very niche usecase. The data it provides access to is not sensitive and attack vectors like MitM attacks are extremely unlikely. The benefit of the Implicit Grant flow is that clients request the token directly, making it very convenient and simple to implement for both the authorization server (potber-auth) and the client. potber-auth attempts to diminish the weaknesses of Implicit Grant by maintaining an allowlist for redirect_uris.
Any (optional) parameters mentioned by the OAuth specification that have not been specifically mentioned in this document are not being supported.
Start by checking out this repository locally and installing dependencies:
git clone https://github.com/spuxx1701/potber-auth.git
cd potber-auth
npm installYou will also need to create a file in the project's root folder called .env.local with the following content (or possibly other values depending on your setup):
VITE_API_URL=https://api.potber.de
VITE_API_LOGIN_ENDPOINT=/auth/login
VITE_API_SESSION_ENDPOINT=/auth/sessionYou can then start your local development server by running:
npm start