Asteroid - an OAuth2 server

Hi everybody,

I’m glad to release the project I’ve been working for the last few months to learn Elixir: Asteroid (for Authorization Server on sTEROIDs) which is a standalone OAuth2 server.

OAuth2 is the main protocol used for decentralized access control on APIs. I guess most have already used it.

Project’s genesis

Before taking a year off, I was working in an IT consulting firm and specifically on the authentication, access control and identity management fields. At work we’ve designed secure architectures and deployed many authorization servers. I found that most lacked the extensibility needed to do what had to be done (read: bugs) and had poor performance when under heavy load. Hence the idea to create one in Elixir!

What is it made of?

An authorization server is at the junction of authentication schemes, user / application / device databases and token stores (state everywhere!), and is made of APIs and web UIs.

For API access, Asteroid can use APIac libraries:

For user / application / device databases, it uses AttributeRepository whose data model is close to the SCIM standard and simplified compared with SQL databases. It is instantiated to:

For token backends you can use either Mnesia or Riak.

What is it capable of?

It implements the following standards:

What is it not capable of?

You still have to implement authentication and authorization workflows by yourself, compared with other solutions that have it built-in.


Documentation (or run mix docs)

Known issues

Asteroid uses a lot of callback functions in its config files (for extensibility) such as:

config :asteroid, :oauth2_refresh_token_lifetime_callback, &Asteroid.Token.RefreshToken.lifetime/1

However, due to a bug in the Erlang standard library, those Elixir callback functions cannot be written in release configuration files. Distillery and mix release fail at building releases, so you can only deploy it with mix (which is not recommended as far as I know).

I’d prefer keeping it as is and waiting for the next OTP version, but I’ll consider switching to MFA notation if needed. Lesson learnt here: release early!

Guidance regarding the use OAuth2

In my opinion:

Asteroid is not in the latter list because 1) it doesn’t have authentication workflows contrary to the servers listed 2) it doesn’t support OpenID Connect (OIDC) and you’ll probably want to use it sooner or later.

That said Asteroid might be interesting for some complex deployments: banking / PSD2 deployments (you’ll need to customize everything anyway), phone carriers implementing Mobile Connect (Erlang processes fit perfectly the need for backend connections to the phones), large fleet management (automotive?)…

Testing it

I’ve deployed it to a Gigalixir server. If you want to test it the OAuth2 issuer is: (metadata at
Then follow this documentation.

What’s next


  • OpenID Connect support
  • Authentication workflows: something similar to a form workflow (have been discussed here before) and that would be UI-independant (standard web, REST or LiveView) and some authentication modules (Social Login, MiniPOW, CAPTCHA, WebAuthn, and so on)
  • More OAuth2 specifications support: token exchange, resource indicators, pushed request objects…
  • Structured logging

Any feedback is welcome, and feel free to try to break the demo app :slight_smile:

Have a good day!


This is really awesome! Had this been here before we might have gone this path instead of Keycloak.

Great work! I have some questions if you don’t mind:

  • Why isn’t the docs hosted on hexdocs?
  • You mention here that hex does not guarantee the integrity of packages but it is my understanding that it does. Here is the specification about it. Could you explain this part better?

One thing that might help you with such a big project is to create an organization on GHub and put your projects there. This might entice more people to contribute.

Thanks for your awesome work!

1 Like

Thanks, means a lot!

So I checked something like 1.5 year ago and at that time my understanding was that you couldn’t be sure that the code you receive was the code that was sent by the updater. I’ve checked again quickly (thanks for the link):

  • Still not sure how it’s possible to make sure the received package is the one sent by the maintainer. After sending it to, is it possible to substitute it with another one (with a valid checksum)? I can see checksums here: so how can the hex client check it receives the correct checksum for a package?
  • I don’t understand neither when packages are signed: directly after uploading? Or when served?

Don’t get me wrong, is a great package manager and I love using it. On the contrary, referencing git reps in mix.exs is a pain as soon as you have different versions for the same lib. But I’d like to understand the sec tradeoffs of using first, especially for sensitive security-releated libs.

Didn’t think of it, that’s a good idea!

Which makes me think I forgot to thank the community that has been super helpful and open on my way to become an Elixir programmer. So, thank you all!


Maybe @ericmj might answer you better on how checksums are used on hex. I haven’t browsed the whole code but I think that is a genuine question.

1 Like

Hi all,

I’m pleased to release version v0.2.0 of Asteroid which brings OpenID Connect support.

It implements:

It does not implement OpenID Connect logout yet.

Here are 2 videos of how it can look like:

OAuth2 flow:

OpenID Connect flow:

As a reminder, the authentication flow is still a do-it-yourslef thing.

Good news: the bug mentioned in the first post was swiftly fixed by the Erlang team, which means Asteroid will be releasable with the next OTP version.

Next steps:

  • Consolidating the AttributeRepository implementations + Ecto / SQL implementation
  • Create a project page as suggested by @victorolinasc
  • Structured logging
  • Authentication workflows: something similar to a form workflow (have been discussed here before) and that would be UI-independant (standard web, REST or LiveView) and some authentication modules (Social Login, MiniPOW, CAPTCHA, WebAuthn, and so on)
  • More OAuth2 specifications support: token exchange, resource indicators, pushed request objects…

Anyone wanting to contribute is welcome! The OAuth2 & OpenID Connect ecosystem is super rich and full of specifications to implement, and I’d be glad to help if you wanna join. I have started filling some issues on Github, so if you’re looking for a project to contribute to or if you start with Elixir and want to practice feel free to pick one.




Just going to use the traditional delete session token pipeline?

1 Like

It’s definitely a possibility for simple cases.

When writing this I was thinking of the implementation of OpenID Connect Session Management 1.0 - draft 28 to make it in a standard way. Also, logging out is not so easy because:

  • You might want some long-live cookies to remember some information like the accounts having logged in (account selection - in the demo I’ve used LocalStorage but this might not be satisfying) or just for long-lived authentication sessions
  • In the actual implementation, the session cookie and the authenticated session (Asteroid.OIDC.AuthenticatedSession) are two different things, so that:
    • one can have several active authenticated sessions in one browser (again, account selection)
    • the session can be destroyed independently of the cookie that might be used somewhere else if Asteroid is embedded in another Elixir app, or maybe some other cases
  • there are two additional logout specifications to take into account (OpenID Connect Front-Channel Logout 1.0 and OpenID Connect Back-Channel Logout 1.0). Plus when you logout from website A: should you logout from the OpenID Provider too? Should the OpenID Provider logout the user to all the other sites?

That might be one of the most tricky part of OIDC actually and I dared not touching it at this point :sweat_smile:

1 Like

It seems what I am looking! I want to try it right now

is this project under active development and future proof to receive updates?

What do you mean by “future proof to receive updates”?

This project is paused. I’ve been working on it a bit last months but now I’m focusing on Wax (new release soon) and next month I plan to work on a much needed library IMO (code name: Plugoid :wink: ).

I plan to start working again on Asteroid in May. If the question is: may I use Asteroid today? I would answer that it’s still version 0.2 and it might be a bit too early. There’s no SQL backend and there’s a lot of rework to do. All of this will probably be done by Q3 this year. But if you’re audacious you can give it a try, I’d be glad to help! Note, however, that it requires OpenID Connect (OIDC) expertise to implement OIDC authentication workflows correctly as of today (there’s no authentication workflow engine yet).

Thanks for the detailed response was looking for this info to consider it.