This post is mainly a small set of opinions I have about how the current documentation and sample code, for web SPA clients that use the Angular (2+) framework, are out of date to the point that they are now confusing. IOW, almost as much harm as good.
Here are my points, very short and sweet. Let me know if you’d like me to elaborate:
-
All current samples use “angular2-jwt” as an npm dependency. This package has been deprecated, and all samples should instead use ’ “@auth0/angular-jwt”: “^1.0.0-beta.9” ’
… this has important ramifications for client-session management (see below)
-
Once a dev figures out he/she should be using “@auth0/angular-jwt” in their (angular) clients, they visit @auth0/angular-jwt - npm. Unfortunately, the repo pointed to by this package is still “GitHub - auth0/angular2-jwt: Helper library for handling JWTs in Angular apps”, which is wrong & confusing
-
Once a dev figures out that the real github repo is here: GitHub - auth0/angular-jwt: Library to help you work with JWTs on AngularJS, the README (though voluminus) is 100% geared towards angular-js. As we all know, angular-js & Angular(2+) are different animals.
-
Once a dev figures out that they should read this article: Angular — Upgrading your JWT strategy from angular2-jwt to auth0/angular-jwt | by Augie Gardner | Augie Gardner | Medium, then they (finally) head back here to read the best doco available: @auth0/angular-jwt - npm
-
Once a dev figures out how to properly use “@auth0/angular-jwt”, there are still no examples provide for how to create a (simple, but effective) custom “tokenGetter()” function, that attempts to refresh a token (via SSO session / checkSession()) if/when an existing access_token is expired
To make a long story short, the current Angular samples here (GitHub - auth0-samples/auth0-angular-samples: Auth0 Integration Samples for Angular 2+ Applications), are not bad, they are just out of date, and they don’t demonstrate how to provide a properly managed client session. It took me >1 months to snake through the above path, before I finally have my own “template-angular-web” repo that is useful for my company’s developers.
Hello Joe!
We’re currently working to bring the Angular Quick Start content and samples up to date. In the meantime, while we work on these changes, please check out the Angular tutorials we have published in our blog. These are up to date for Angular 5 and do not use deprecated libraries. Hopefully they can also cover some additional material for you as well:
The Complete Guide to Angular User Authentication with Auth0 (8 part series on building a real-world MEAN stack application)
Thanks for your patience while we get our documentation updated! Please let us know if you have further questions or concerns.
1 Like
Thanks for the reply Kim, I’m gratified to see that you and others are paying attention & putting in valuable work for continued Angular (5 and beyond) support. I’ve actually been following your work (along with Ryan Chenkie) on Github since ~ December 2017.
To be honest, the hardest part of the above ‘puzzle’ I mentioned was figuring out these points:
-
The very latest work on “@auth0/angular-jwt” is in a branch called “v1.0” in here: https://github.com/auth0/angular2-jwt/tree/v1.0
-
In order to effectively use “@auth0/angular-jwt”, one must figure out how to add configuration meta-dat in the jwtOptionsProvider.useFactory method, like this:
export function JwtModuleConfigFactory(authService): any {
return {
whitelistedDomains: ['localhost:3000', 'api.test.foo.com', 'api.prod.foo.com'],
tokenGetter: () => {
return authService.getFreshToken();
}
}
}
There is no documentation or code samples showing how to provide the whitelistedDomains, in this factory function. Seems like such a simple omission, but it’s painful to figure out.
Again, thanks for the reply.
Hi Joe! Please don’t use the Angular JWT libraries. Our newer samples do not use these libraries and I’m working on removing angular2-jwt from our docs and Quick Starts right now, as they are an unnecessary layer of abstraction–particularly with HttpHeaders and also now with HttpInterceptor (as of Angular 4.3). As you can see, they tend to make the situation more confusing rather than more straightforward, and this should never be the case when using a helper library.
If you’d like to see an example app that uses interceptors, please check out this code: sample-auth0-angular/token-interceptor.service.ts at master · kmaida/sample-auth0-angular · GitHub Please note that interceptors currently act on ALL outgoing requests, so if you only want to attach the header to certain requests, use HttpHeaders as demonstrated in the two blog posts cited in my response above.
To be sure I’m understanding:
- You are saying: do not use either angular2-jwt or @auth0/angular-jwt, right?
- Instead, I should use custom class(es) that implement HttpInteceptor, rather than relying on the use of HttpInterceptor within @auth0/angular-jwt, and I should follow the example you have provided above as a guide?
- Should I not use @auth0/angular-jwt because it is an unnecessary layer of abstraction, or because it has more serious problems?
The reason I ask #3, is because we are using it now, and it appears to work well, though we are still testing it. We attempt to seamlessly renew our user’s access_token on the fly in our SPA clients, when they start the app (client), as they are using it, and if/when they make xhr requests after a period of hibernation so to speak (e.g. the user has closed the lid on their laptop and then opened it again, after their current access_token is expired)
Hi Joe. You are free to use the library at your own risk, so to speak: it is not maintained by Auth0 any longer at this time, but instead by Ryan independently. You should continue to use the library if it is currently working for you, but the bottom line here is:
The libraries are no longer actively maintained by Auth0, so support for them is limited to the GitHub issues / community. If you need urgent support, the best strategy is actually to contact Ryan Chenkie.
The libraries do not have any serious problems that I am aware of, but the risk in using them is that they may end up deprecated and archived, or they may pass out from under the Auth0 umbrella and into the community. (The latter is more likely.) The functionality in the library can be reverse-engineered fairly easily from the interceptor code here: https://github.com/auth0/angular2-jwt/blob/v1.0/src/jwt.interceptor.ts. However, I will mention to Ryan that you are looking for support and send him the link to your questions here.
Gotcha, that all makes sense and I appreciate the open-ness about where Auth0 is at in the process of updating its angular-specific (authentication / authorization / jwt-stuff) code & doco. To circle back to the beginning of this conversation, I would make these 2 ‘final points’:
-
The current ‘official angular samples’ (articles (e.g. https://manage.auth0.com/#/clients/abc123/quickstart) & Github repo) don’t inform us developers (yet) that angular2-jwt should no longer be used and that angular-jwt is not its replacement. Even a pointer to one of your current blogs would be helpful there. Also, there are articles out there like the one on medium.com that I posted above that make it look like Angular5/Auth0 customers should ‘migrate’ to @auth0/angular-jwt.
-
I can’t help but think that most Auth0 customers (who are building web SPA clients) want to see how to properly maintain/manage a ‘client session’, and how that works within the context of a SSO session, and the auth0-js’ .checkSession() function. Obviously @auth0/angular-jwt purports to do most of the heavy lifting of client session management for you, so that’s why it seemed natural (to me) to use it.
-
The official samples are being updated along with the Quick Start docs (they go hand-in-hand) so when the documentation is updated, the samples will be too. In fact, both are likely being merged today. I’ve had some conversations today with Ryan as well as with the docs team regarding the future of the jwt library, and it will continue to be maintained as a cooperative effort. At the moment, however, it is in a confusing state (master branch vs. 1.0 branch, etc.), so we will not include it in tutorials on the blog, docs, or code samples until it’s in a more stable state with the 1.0 branch merged. We also have a few other Angular improvements that we are working on that should help you out that will be rolled out soon. We really appreciate your patience while we work through this!
-
Again, we’re working through consolidating our information to hopefully make this as consistent and straightforward as possible. Due to the sheer amount of documentation (and content sources) that exist, it’s a big undertaking. I would recommend that you check out our blog posts on https://auth0.com/blog if you are looking for the latest information about using Angular with Auth0. Our docs should catch up, and we’re not in control of what gets posted on external sites like Medium. If you want the most up-to-date recommendations from Auth0, please leverage the resources on our blog over open blogging platforms like Medium.
Again, we appreciate your patience, and apologize for the confusion. Please feel free to reach out to me on Twitter (@KimMaida) or Hangouts (kim.maida@auth0.com) if you’d like to keep in touch for on-the-fly updates, and we hope to have this situation sorted out soon!
1 Like
I just published v1.0 of @auth0/angular-jwt on npm and added some notes to the readme which will hopefully clarify the version issue. @Joe_Tillotson, as @kim.maida mentioned, the library isn’t really necessary if you want to create your own interceptor class. The angular2-jwt library was originally created because Angular didn’t have interceptors before v4.3 and attaching tokens to requests had to be done every time. The library might still provide some value to you if you want to just set some config and use that as your request interception. Otherwise, it’s not difficult to put together your own interceptors.