Incorrect / confusing use of the :realm option?

[fredwu]

Hi,

First of all thanks for the great work on Guardian, it's a library that many of my colleagues and myself have been benefiting from immensely. :)

We have a use case where we need to support accepting one JWT from potentially different sources (issuers). After digging around and experimenting, we've figured out we can use the :realm option to differentiate the JWTs so that the token verification works as intended.

However, we noticed that the :realm option in Guardian.Plug.VerifyHeader does not conform to any of the RFCs¹:

The default value for :realm is Bearer, but according to the RFCs and IANA, Bearer is a type of HTTP authentication scheme, whereas realm (and others) are attributes.

To accept a Bearer token with a particular realm, in Guardian we have to work around it by setting it like: realm: "Bearer realm=\"example.com\"".

Ideally we should have a :scheme option that defaults to Bearer, and either a dedicated :realm option, or a more flexible :attributes option that allows any attributes.

I am in no way an expert on this topic, so please let me know if I've missed something. Thanks!

---

1. RFCs I've looked into:

• RFC2617 HTTP Authentication: https://tools.ietf.org/html/rfc2617
• RFC6749 OAuth 2.0 https://tools.ietf.org/html/rfc6749
• RFC6750 OAuth 2.0 Bearer Token https://tools.ietf.org/html/rfc6750
• RFC7235 HTTP/1.1 https://tools.ietf.org/html/rfc7235
• RFC7519 JWT https://tools.ietf.org/html/rfc7519

[scrogson]

Great stuff @fredwu! I've often thought that realm was not the best name for this myself. Unfortunately, this looks like it would be a breaking change. So we might need to put this off until we're ready for 2.0.

I'll try to find some time to read through the links you've provided and talk it over with the rest of the @ueberauth/core team.

[Hanspagh]

@scrogson. Where are we on this?

[yordis]

I agree on this one, this is misleading, a better key name should be enough for now. Maybe add a new key, and announce the breaking change without having to have a breaking change today