Interface for OAuth providers

[benmccann]

I was thinking about creating an official sveltekit-auth package using arctic, the lucia guide, etc. However, one thing I'm a bit uncertain of is whether all the arctic providers have the same interface. Like do they all have the same signature for createAuthorizationURL, etc.? I think it would help both for my usecase and for implementers of providers if they implemented some common interface where possible

[benmccann]

It looks like they don't quite share a common interface. I only looked at createAuthorizationURL and they can all take state: string, codeVerifier: string, scopes: string[], but it can define neither, either, or both of the last two parameters.

One idea would be to make createAuthorizationURL take a single object parameter like { state: string, codeVerifier?: string, scopes?: string[] }. Then those could be included or not based on whether the particular provider needed them. And probably the base provider type could be generic and specify which of those parameters were used for a given provider

Similarly for validateAuthorizationCode, which takes a code and sometimes codeVerifier (and scopes for start.gg).

Having a consistent interface to call against would help a lot as I could then write generic SvelteKit code to invoke the arctic provider

[pilcrowonpaper]

No, the providers don't implement a shared interface. This was an intentional design choice.

Unfortunately there are several optional features and extensions of OAuth 2.0 that make it difficult to create a shared API that would work for all providers. Worse, there are several providers that just don't follow the RFC.

I would love to have a shared interface but the clients in Arctic wasn't designed to be pluggable/injectable "adapters" in the first place. They were meant to be used directly as is. IMO a shared interface is only realistic at an abstraction layer one or two level above Arctic's.

Of course, I've still designed clients to have a similar API since they all either just follow the base OAuth 2.0 or OAuth 2.0 with PKCE.

[absolutejs]

It sounds like your use case is exactly what I had when creating Absolute-Auth for Elysia, I ran into a similar issue. Pilcrow is right that arctic wasn't designed for interchangeability and that it would be a major design change.

The providers do all have a different usage and there's a few outliers that do not follow RFC. However I built Citra with different design principles so that it can be used as a basepoint for other auth packages. You call createOAuth2Client and send it the name of the provider you want and the required credentials. Under the hood its using that string to map to the provider object and determine what type of provider is it (Base, PKCE, OIDC, Scope Required).

Your idea is spot on about creating a base object and then attaching provider specific things to that. That's how i made it all type safe. All of the providers are BaseOAuth2Clients and then based on conditionals the extra type info gets attached. This is because in TypeScript, T & unknown simplifies to T.

This project is still in beta but its used in production for my (unrelated) companies main projects. Citra offers every provider that Arctic does plus a few more. It is also trivial to add a new provider you just have to add it to the defineProviders

[benmccann]

I looked at what grant is doing. They specify a profile_url in profile.json and access_url, authorize_url, oauth, request_url, scope_delimiter in oauth.json. With this common set of fields they're able to support over 200 providers. I really like their interface. The big problem is that the library is not very actively maintained and my PR to support the standard Request class for SvelteKit has thus far gone unreviewed. I'd love to build SvelteKit's auth on top of arctic as it's more actively maintained, but would need to find a way to make this work

They do the provider-specific stuff in this file:
https://github.com/simov/grant/blob/500ab2066e177f14856fd50bf0b507651111692b/lib/flow/oauth2.js

Their authorize method is basically the equivalent of arctic's createAuthorizationURL that we'd need to figure out.

There they use the following:

provider.authorize_url
provider.key,
provider.redirect_uri,
provider.scope,
provider.state,
provider.nonce
provider.pkce
provider.code_challenge
provider.custom_params
provider.subdomain

Interestingly, grant only documents custom_params for Google, Reddit, and Trello. arctic supports Google and Reddit, but none of the mentioned parameters

Anyway, luckily, the situation for arctic is much more straightforward. Because arctic hides away most of these details internally or takes most of these via the constructor, there's very little that needs to be common across the interface.

[pilcrowonpaper]

Honestly, I think the issue is that we have provider-specific clients in the first place. It's based on APIs that do have shared interfaces and are pluggable (like Auth.js) even though Arctic aims to be at a very different abstraction level. It hasn't caused technical issues but it's been the source of a lot of unnecessary design/development issues.

My current idea is to just have a unified Client interface with implementations based on the standardized auth methods (none/public, HTTP basic, client secret, JWT). Each provider, if we are still going to have them, will just implement a simple Provider interface with a authorizationEndpoint and tokenEndpoint property. Arctic will provide a few methods that takes those interfaces to build authorization URLs and send requests. Something like:

import * as arctic from "arctic";

const googleOAuthClient = new arctic.HTTPBasicAuthenticationClient(
    GOOGLE_CLIENT_ID,
    GOOGLE_CLIENT_SECRET
);

const authorizationURL = arctic.createAuthorizationURLWithPKCE(
    googleOAuthClient,
    arctic.google.authorizationEndpoint,
    state,
    "s256",
    codeVerifier,
    GOOGLE_REDIRECT_URI,
    scopes
);

const tokens = await arctic.issueAccessTokenWithPKCE(
    googleOAuthClient,
    arctic.google.tokenEndpoint,
    authorizationCode,
    codeVerifier,
    GOOGLE_REDIRECT_URI
);

[pilcrowonpaper]

So, yes, I agree that it's weird that we don't have a shared interface in our current API, but the issue is with our current API and not the lack of a shared interface IMO.

I'll keep this issue for now until I come up with a more concrete API design for v3, but it's probably not going to be implemented.

[benmccann]

There are other clients that work similarly to what you describe and it's certainly appealing in terms of simplifying the implementation. However, these clients are quite confusing to me as a user. I really like that with arctic, if I want connect to Google I simply use the Google provider. But if I have to start making choices about whether to use an Authorization Code Grant with Proof Key for Code Exchange (PKCE), or an Authorization Code Grant, or a Resource Owner Password Credentials (ROPC) Grant (example: https://authts.github.io/oidc-client-ts/) then it just becomes an unintelligble mess of jargon. It's much nicer for users to not have to become an expert in the underlying implementation details. I really love arctic for the simplicity as a user today as it's what makes it the nicest library out there for OAuth. I'd hate to see it become just like the other clients and lose the ease of use that differentiates it in the first place.

[pilcrowonpaper]

The issue I find is that providers support multiple flows and authentication methods, so you already need to read the docs before starting. Auth0 only supports PKCE with public clients, Microsoft supports multiple client authentication methods, Google doesn't always return the refresh token.

I see the value of a library that just gives you a single, opinionated API for each provider, but I don't think Arctic should aim to be that.

[benmccann]

Auth0 only supports PKCE with public clients

Why not just have two providers then? Auth0Public and Auth0Private. This would help a lot for people who are setting up Auth0 to understand that there are two ways to do it and a single simple class to use in each case

Microsoft supports multiple client authentication methods

I think you could have a provider for the most commonly used one and tell the user they need to do something custom for the other cases

Google doesn't always return the refresh token

You could have an option to show the user the consent screen, which causes the refresh token to be returned