EXTJWT command for integrating external web services #341

prawnsalad · 2018-07-21T20:19:35Z

This spec provides a way for web services hosted externally to an IRC server to authenticate users that are connected to the IRC server by making use of the standard JWT tokens (https://jwt.io/).

This allows a web service to do things such as:

Granting admin access to a networks wiki page if a user has +o on the network
Granting write access to a channels wiki page if the user has +o in the channel
Automatically creating a user account if the user is logged into the IRC server and has an account name

For a more indepth example we could use the free audio/video conference service - Jitsi Meet. This service has built in JWT verification in that an application can send a user to a URL that contains a JWT token, and if the Jitsi Meet server verifies this token successfully, the user is granted access to that conference room.
When an IRC client wants to join a conference room, it would first call EXTJWT #testchannel to receive a JWT token from the IRCd. The client would then open a browser window navigating to the Jitsi Meet URL while passing that token. It is up to the client to decide how and where to use this token, eg. via a "Jitsi Call" button for example.

progval · 2018-07-22T01:44:45Z

extensions/extjwt.md

+
+The client MAY send `EXTJWT` or `EXTJWT *` to the server to request a new JWT token. The server MUST then reply with `EXTJWT *` and a JWT token as its jwt_token parameter containing the following claims that are relevant to the client at that time:
+
+* `exp` Number; Unix timestamp for when this token expires. Usually less than 1 minute from the token generation.


Unix timestamp is consistent with other parts such as RPL_TOPICWHOTIME so we don't want to go changing that.

progval · 2018-07-22T01:48:17Z

extensions/extjwt.md

+
+### The EXTJWT Command
+
+Syntax: `EXTJWT [channel]`


should be: EXTJWT ( <channel> | * )

progval · 2018-07-22T01:50:53Z

extensions/extjwt.md

+
+* `channel` String; The channel name this token is related to.
+* `joined` Boolean; True if the client that requested this token is joined to the channel.
+* `time_joined` Number; The time in which the user joined the channel.


What should its value be if joined is False?

The best solution would probably to merge join and time_joined as a single optional attribute, so the receiver of the JWT does not need to sanity-check this.

I think originally I preferred to be explicit with the claim names, but being more concise here would save a lot of space.

I can change this by dropping the time_joined claim, changing joined to contain the timestamp of when joined and setting it to 0 when not joined to the channel

This change has now been applied, good shout

progval · 2018-07-22T01:52:23Z

extensions/extjwt.md

+
+#### Handling long responses
+
+In some cases the encoded token may be longer than the maximum line length allowed between the client and server. In this case, the first parameter of the response MUST be `*` to indicate that further data will follow. The final chunk of the response sent to the client MUST NOT include `*` as the first parameter.


You should use the same mechanism as AUTHENTICATE, for consistency between IRCv3 specs.

This is the mechanism that CAP LS 302 uses, so there's consistency between that and EXTJWT at least.

Indeed. As the CAP LS 302 way is much easier to implement, I agree this mechanism should be used.

progval · 2018-07-22T01:56:32Z

extensions/extjwt.md

+* `channel` String; The channel name this token is related to.
+* `joined` Boolean; True if the client that requested this token is joined to the channel.
+* `time_joined` Number; The time in which the user joined the channel.
+* `modes` []String; An array of the channel modes the client has in this channel.


Maybe add a way to disclose modes with arguments? eg. +I to tell the mask that allows the user to be in that channel.

progval · 2018-07-22T01:57:41Z

extensions/extjwt.md

+* `iss` String; The server name that generated this token.
+* `nick` String; The nick of the client that requested this token.
+* `account` String; The account name of the user that requested this token. Empty if not available.
+* `net_modes` []String; An array of user modes the IRCd may want to disclose. Eg, if the user is an operator.


Some generic net modes should probably added to this spec.

progval · 2018-07-22T01:58:25Z

extensions/extjwt.md

+
+Where the replied token is decoded into:
+~~~json
+{"exp":1529917513,"iss":"irc.example.org","nick":"somenick","account":"somenick","net_modes":["o"]}


"o" looks like a channel op, you should probably rename it. A non-single-letter name would be nice too (let's not repeat the mistakes of the past).

These modes are the user modes the IRC server has set. Ie. o for operator. If an IRCd introduces named modes then the named modes will be placed in here too.

progval · 2018-07-22T01:59:10Z

extensions/extjwt.md

+
+Where the replied token is decoded into:
+~~~json
+{"exp":1529917513,"iss":"irc.example.org","nick":"somenick","account":"","net_modes":[]}


Why not allow "account": null, or making that attribute optional?

progval · 2018-07-22T02:00:54Z

Looks like a cool idea! Even if it does not get implemented by IRC daemons (or networks), this could be partially provided by (non-privileged) bots.

SadieCat · 2019-03-11T04:09:49Z

extensions/extjwt.md

+
+Response syntax: `EXTJWT <requested_target> [*] <jwt_token>`
+
+The client MAY send `EXTJWT` or `EXTJWT *` to the server to request a new JWT token. The server MUST then reply with `EXTJWT *` and a JWT token as its jwt_token parameter containing the following claims that are relevant to the client at that time:


Is there any reason to have two command syntax variants for a non-channel JWT (no parameters and *)?

SadieCat · 2019-03-11T04:11:12Z

extensions/extjwt.md

+* `iss` String; The server name that generated this token.
+* `sub` String; The nick of the client that requested this token.
+* `account` String; The account name of the user that requested this token. Empty if not available.
+* `net_modes` []String; An array of user modes the IRCd may want to disclose. Eg, if the user is an operator.


Bikeshed: net_modes should be referred to as user_modes and modes (below) should be channel_modes.

SadieCat · 2019-03-11T04:13:06Z

How should a server behave if there was an issue with generating the JWT for some reason?

SadieCat · 2019-03-11T04:27:25Z

Is it useful to add a context parameter to the command so that JWTs can be generated with different secrets for integrating with multiple services? e.g. EXTJWT #channel servicename.

prawnsalad · 2019-03-11T12:35:38Z

@SaberUK I could imagine that use case, yes. If I make the * in EXTJWT * required instead of optional as you questioned in another comment, then the service name could be an optional second parameter, EXTJWT * [servicename] / EXTJWT #channel [servicename]

DanielOaks · 2019-03-11T21:34:20Z

I like this, sounds like a nice way to let nets setup external services without giving db access and similar. From the looks of it, it's not useful for services being setup without the network's prior OK (agreement on the secret, etc), and that's intended?

Will look at writing up an implementation of this in Ora. The servicename stuff being discussed above sounds especially useful, once that change is resolved I'll write up our impl.

prawnsalad · 2020-04-07T16:10:57Z

I'm about to update this draft spec with some minor tweaks that's come up during testing since this was first implemented.

Adding the optional [servicename] argument as mentioned above.
Renaming net_modes and modes with umodes and cmodes respectively.
Replacing iss with iat (issued at) so that the external service can decide how long the token should be valid for. Different services may require different lengths of time.

It has been mentioned by a few people that usage would be fairly limited since third parties would need to be configured with JWT secrets from the IRCd. To get around this I could add an optional verify claim in the token that contains a URL. This will allow any external service to make a simple HTTP call to verify a token they received from the network.
eg.

A client receives a JWT token containing "verify":"https://irc.foo.net/extjwtverify/%s".
The client opens a third party service that accepts the token.
The service makes a HTTP call to the verify URL replacing %s with the token
The verify URL replies with either a 200 or 403 HTTP status if the token is valid.

Advantages:

The IRCd JWT secrets will never need to be shared to third party services
No previous agreement needs to be configured between the IRCd and third party services
The URL is determined by the IRCd and can be configured as fits. eg. it may use a separate host instead of the IRCd directly to verify tokens.

extensions/extjwt.md

Co-Authored-By: Kyle Fuller <kyle@fuller.li>

RyanSquared · 2020-04-15T04:53:27Z

What happens if a user forges a JWT and sets the "vfy" URL to something like, for example, "https://gib_200_always.fusionscript.info/%s"?

~~I'd suggest instead changing the "vfy" format to instead be the following format:~~

~~"https://%s/extjwtverify?t=%s"~~

This would take the "iss" field as the first input, and the token as a whole as the second field.

~~Additionally, from what I can tell, it's possible to downgrade HTTPS to HTTP using the same method?~~ (resolved by just not having the URI passed in, have it "composed")

DanielOaks · 2020-04-15T07:16:32Z

extensions/extjwt.md

+
+Where the replied token is decoded into:
+~~~json
+{"exp":1529917513,"iss":"irc.example.org",vfy":"https://irc.example.org/extjwt?t=%s","sub":"testnick","account":"testnick","umodes":[],"channel":"#channel","joined":1529917501,"cmodes":["o"]}


json's a tiny bit mangled here, should be ,"vfy" instead of ,vfy"

RyanSquared · 2020-04-15T07:24:05Z

02:19 <LordRyan> a user-supplied path is bound to have issues.
02:20 <LordRyan> i'd suggest a verify subdomain and a verify path, if you want to go that route.
02:20 <LordRyan> that way it is impossible to spoof the origin.
02:20 <LordRyan> "origin" => "issuer"
02:21 <LordRyan> so { verify_subdomain => "verify", iss => "example.com", verify_path => "/verify_extjwt?t=%s" }
02:21 <LordRyan> would go to https://verify.example.com/verify_extjwt?t=<token>
02:21 <LordRyan> and add in an enforcement that verify_path MUST be preceded by a /, enforced in any implementation that uses this system
02:21 <LordRyan> because otherwise you can just pass ".gib_200_always.example.com"
02:23 <LordRyan> and if you do it this way you can still do a "configuration-less", i.e. this gets added to meet.jit.si and they don't need to know anything about the server, they can just do the request.

extensions/extjwt.md

Co-Authored-By: Sadie Powell <sadie@witchery.services>

SadieCat · 2020-04-16T10:34:54Z

As I mentioned on IRC last night, what do people think about sending the token using an Authorisation header instead of the %s thing? A quick search seems to show some precedent for doing this.

RyanSquared · 2020-04-16T10:51:03Z

I would be fine with that. That means you only need to specify an optional "issuer subdomain" and an optional "issuer verification path" which can both be static strings.

RyanSquared · 2020-04-16T10:55:55Z

I see some continued comments on IRC (both within IRCv3 and when discussing with some infosec friends) where the reason for this validation URL is misunderstood. I think it would be good to put some emphasis on only using the validation URL IF there is no possible shared secret. Most importantly, if there is a shared secret and it fails, I think that the validation URL MUST NOT attempted, as the shared secret is a more secure method and should take higher priority.

RyanSquared · 2020-04-16T10:56:19Z

Additionally, some conversations that prawnsalad and I had about this:

02:00 <prawnsalad> LordRyan: if a user tampers with the token then it won’t match the hash any more
02:01 <LordRyan> and so the user makes a new hash
02:01 <LordRyan> i wasn't even thinking "tamper" i was thinking "forge" as in make it themselves
02:02 <LordRyan> if you're using vfy as a backup for not using a signature then there's no integrity in that signature and your ONLY verification is that URL in "vfy"
02:02 <LordRyan> anything including "vfy" can be forged
02:06 <prawnsalad> hm no. a jwt token is "$header.$payload.<hmac($header+"."+$payload . $secret)>"
02:06 <LordRyan> yes
02:06 <prawnsalad> to forge it you would need to know the secret that the ircd has
02:06 <LordRyan> why?
02:06 <LordRyan> this is supposed to be used if the service ALSO doesn't know the secret.
02:07 <LordRyan> you can just make it up. the service doesn't care.
02:10 <LordRyan> btw prawnsalad this issue also came up in a similar context in webauthn domain phish+MITMing so the request for the WebAuthn challenge must include the origin domain, kinda like a "client-side" salt.
02:11 <LordRyan> prawnsalad: let me phrase it this way: how does the party using the JWT for authentication know that you're not spoofing it if they don't have the secret either?
02:13 <prawnsalad> yea i get what you mean now, a rather than a vfy url it would be safer to have that pre set with the third party so there is only ever 1 verify url then
02:14 <LordRyan> or like i suggested on the GitHub, tie the issuer into the vfy url
02:14 <LordRyan> though that has the same issue, now that i think about it

RyanSquared · 2020-04-16T22:33:11Z

Discussion on IRC brought up usage of an asymmetric key, with the public version stored in a standardized location in the issuer. This resolves both the issue of the external service not having a shared secret and the issue of the client being able to spoof the endpoint used for authentication.

slingamn · 2020-04-17T02:08:57Z

What is the use case for including the channel join time in the token?

slingamn · 2020-04-17T16:35:06Z

From discussion in #kiwiirc: we're tentatively proposing that server implementations that do not store channel join time information can send joined: 1, which indicates that the user is joined to the channel but the join time is unavailable for whatever reason.

SadieCat · 2020-04-17T22:09:41Z

What is the reason for this change exactly? It's not hard to update an existing implementation to store the join time if necessary.

slingamn · 2020-04-19T01:45:04Z

I'd prefer not to add it to my implementation, given that there is no use case for it right now.

slingamn · 2020-04-19T05:41:56Z

Clarification questions that came up during Dan's implementation:

Is the signing algorithm always HS256?
What should happen when the service name is not specified, or is *? Should the server be configured with a default secret key for signing these tokens?

prawnsalad · 2020-04-19T13:18:48Z

Is the signing algorithm always HS256?

JWT tokens allow you to use any algo your implementation can support. As long as you can create + verify your own token, you're all good.

What should happen when the service name is not specified, or is *? Should the server be configured with a default secret key for signing these tokens?

A default should be used, yes. This default would be the most used as clients making use of EXTJWT wouldn't know what services your IRCd has running or what name to use for them unless the network has a dedicated client for it.

prawnsalad · 2020-04-20T12:19:32Z

@RyanSquared

Discussion on IRC brought up usage of an asymmetric key, with the public version stored in a standardized location in the issuer. This resolves both the issue of the external service not having a shared secret and the issue of the client being able to spoof the endpoint used for authentication.

Other than the service being able to cache a pub key from the issuer, what other benefit would this have? Both algo types will need a request back to the issuer either for the pub key or verification as far as I understood.

Also to note, the external service is not required to know the shared secret for a token. While services run by the same IRCd network may share the secret which saves the verification request trip, third parties can make the verification request without knowing any secrets.

RyanSquared · 2020-04-20T21:54:53Z

Both algo types will need a request back to the issuer either for the pub key or verification as far as I understood.

For pubkey based verification you can just put a static key in a directory. For verifying the JWT itself, you'd have to implement something server side. I think a majority of hosts would rather have a static file option.

RyanSquared · 2020-04-21T08:37:18Z

Can we add the supported services to the ISUPPORT token in any way? Something like, EXTJWT=V:1&S:nextcloud,jitsi

k4bek4be · 2020-06-25T08:08:23Z

EXTJWT=V:1&S:nextcloud,jitsi

Any explanation for this example, please?

k4bek4be · 2020-07-02T17:28:07Z

I have created an implementation for the EXTJWT command. I'm supporting HS, ES and RS type tokens, with method and key/password selectable per service. Users on our network are already using the HS384 method.

The specification does not mention any error handling. That's what I've devised:

No arguments: send ERR_NEEDMOREPARAMS.
The first parameter is neither an existing channel name nor *: send ERR_NOSUCHNICK
The second parameter does not match any configured service name: send :irc.example.com FAIL EXTJWT NO_SUCH_SERVICE :No such service
Token generation failed for some other reason: send :irc.example.com FAIL EXTJWT UNKNOWN_ERROR :Failed to generate token

The vfy claim can be specified in configuration, separately for each service, and the IRC server is not handling the verification, requiring administrator to set up some separate verification service.

k4bek4be · 2021-12-28T18:57:19Z

This draft is now shipped as optional feature with unrealircd 6.0.0.

prawnsalad added 2 commits July 21, 2018 21:11

Create extjwt.md

e2e85ab

Update extjwt.md

41c6187

progval suggested changes Jul 22, 2018

View reviewed changes

prawnsalad added 4 commits October 5, 2018 22:23

Example syntax update; Combine joined+time_joined claims

b53eb93

Replacing the nick claim with the JWT standard sub (subject) claim

d1ad8d1

Versioning support

51a288a

Notes on token expiration

66c11e1

SadieCat reviewed Mar 11, 2019

View reviewed changes

Optional verify URL; Optional service names; *modes claim renamed;

4a390fa

kylef reviewed Apr 11, 2020

View reviewed changes

extensions/extjwt.md Outdated Show resolved Hide resolved

vfy 403 > 401

6be574e

Co-Authored-By: Kyle Fuller <kyle@fuller.li>

DanielOaks reviewed Apr 15, 2020

View reviewed changes

SadieCat reviewed Apr 15, 2020

View reviewed changes

extensions/extjwt.md Outdated Show resolved Hide resolved

Update extensions/extjwt.md

6ceab95

Co-Authored-By: Sadie Powell <sadie@witchery.services>

slingamn mentioned this pull request Apr 19, 2020

Basic EXTJWT support ergochat/ergo#948

Closed

2 tasks

Channel joined claim to be 1 if no timestamp is available

f3facfb

DanielOaks mentioned this pull request Mar 1, 2021

Update Registry wrt new PRs (esp fail/warn codes) ircv3/ircv3.github.io#356

Closed

10 tasks


		The client MAY send `EXTJWT` or `EXTJWT ` to the server to request a new JWT token. The server MUST then reply with `EXTJWT ` and a JWT token as its jwt_token parameter containing the following claims that are relevant to the client at that time:

		* `exp` Number; Unix timestamp for when this token expires. Usually less than 1 minute from the token generation.


		#### Handling long responses

		In some cases the encoded token may be longer than the maximum line length allowed between the client and server. In this case, the first parameter of the response MUST be `` to indicate that further data will follow. The final chunk of the response sent to the client MUST NOT include `` as the first parameter.


		Response syntax: `EXTJWT <requested_target> [*] <jwt_token>`

		The client MAY send `EXTJWT` or `EXTJWT ` to the server to request a new JWT token. The server MUST then reply with `EXTJWT ` and a JWT token as its jwt_token parameter containing the following claims that are relevant to the client at that time:

EXTJWT command for integrating external web services #341

Are you sure you want to change the base?

EXTJWT command for integrating external web services #341

Conversation

prawnsalad commented Jul 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

progval Jul 22, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

progval commented Jul 22, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SadieCat commented Mar 11, 2019

SadieCat commented Mar 11, 2019

prawnsalad commented Mar 11, 2019

DanielOaks commented Mar 11, 2019

prawnsalad commented Apr 7, 2020

RyanSquared commented Apr 15, 2020 • edited

Choose a reason for hiding this comment

RyanSquared commented Apr 15, 2020

SadieCat commented Apr 16, 2020 • edited

RyanSquared commented Apr 16, 2020

RyanSquared commented Apr 16, 2020

RyanSquared commented Apr 16, 2020

RyanSquared commented Apr 16, 2020

slingamn commented Apr 17, 2020

slingamn commented Apr 17, 2020

SadieCat commented Apr 17, 2020 • edited

slingamn commented Apr 19, 2020

slingamn commented Apr 19, 2020

prawnsalad commented Apr 19, 2020

prawnsalad commented Apr 20, 2020

RyanSquared commented Apr 20, 2020

RyanSquared commented Apr 21, 2020 • edited

k4bek4be commented Jun 25, 2020

k4bek4be commented Jul 2, 2020

k4bek4be commented Dec 28, 2021

progval Jul 22, 2018 •

edited

progval commented Jul 22, 2018 •

edited

RyanSquared commented Apr 15, 2020 •

edited

SadieCat commented Apr 16, 2020 •

edited

SadieCat commented Apr 17, 2020 •

edited

RyanSquared commented Apr 21, 2020 •

edited