@auth0/angular-jwt

What is @auth0/angular-jwt?

@auth0/angular-jwt is an Angular library that provides utilities for handling JSON Web Tokens (JWT). It helps in managing token-based authentication in Angular applications by providing features such as token decoding, token expiration checking, and HTTP request interception to automatically add JWTs to requests.

What are @auth0/angular-jwt's main functionalities?

Token Decoding

This feature allows you to decode a JWT to access its payload. The JwtHelperService provides a method decodeToken that takes a raw JWT string and returns its decoded payload.

import { JwtHelperService } from '@auth0/angular-jwt';

const helper = new JwtHelperService();
const decodedToken = helper.decodeToken(myRawToken);
console.log(decodedToken);

Token Expiration Checking

This feature allows you to check if a JWT has expired. The JwtHelperService provides a method isTokenExpired that takes a raw JWT string and returns a boolean indicating whether the token is expired.

import { JwtHelperService } from '@auth0/angular-jwt';

const helper = new JwtHelperService();
const isExpired = helper.isTokenExpired(myRawToken);
console.log(isExpired);

HTTP Request Interception

This feature allows you to automatically add JWTs to HTTP requests. By configuring the JwtModule and providing a tokenGetter function, you can intercept HTTP requests and add the JWT to the Authorization header.

import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';
import { JwtModule } from '@auth0/angular-jwt';

export function tokenGetter() {
  return localStorage.getItem('access_token');
}

@NgModule({
  imports: [
    HttpClientModule,
    JwtModule.forRoot({
      config: {
        tokenGetter: tokenGetter,
        allowedDomains: ['example.com'],
        disallowedRoutes: ['example.com/examplebadroute/'],
      },
    }),
  ],
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: JwtInterceptor, multi: true },
  ],
})
export class AppModule {}

Other packages similar to @auth0/angular-jwt

angular2-jwt

angular2-jwt is another Angular library for handling JWTs. It provides similar functionalities such as token decoding, token expiration checking, and HTTP request interception. However, @auth0/angular-jwt is more actively maintained and has better integration with Auth0 services.

ngx-auth

ngx-auth is a comprehensive authentication library for Angular that supports JWT. It provides features for token management, HTTP request interception, and route guarding. Compared to @auth0/angular-jwt, ngx-auth offers a more extensive set of features for handling authentication flows.

ngx-jwt-auth

ngx-jwt-auth is another Angular library focused on JWT authentication. It provides utilities for token storage, token expiration checking, and HTTP request interception. While it offers similar functionalities to @auth0/angular-jwt, it is less popular and has fewer community contributions.

README

@auth0/angular-jwt

NOTE: This library is now at version 5 and is published on npm as @auth0/angular-jwt. If you're looking for the pre-v1.0 version of this library, it can be found in the pre-v1.0 branch and on npm as angular2-jwt.

Version v5 of this library has some breaking changes concerning the allowedDomains and disallowedRoutes.

@auth0/angular-jwt v5 is to be used with Angular v10+ and RxJS v6+. For Angular v6+ to v9, use @auth0/angular-jwt v4

This library provides an HttpInterceptor which automatically attaches a JSON Web Token to HttpClient requests.

This library does not have any functionality for (or opinion about) implementing user authentication and retrieving JWTs to begin with. Those details will vary depending on your setup, but in most cases, you will use a regular HTTP request to authenticate your users and then save their JWTs in local storage or in a cookie if successful.

Note: This library can only be used with Angular 4.3 and higher because it relies on an HttpInterceptor from Angular's HttpClient. This feature is not available on lower versions.

Installation

# installation with npm
npm install @auth0/angular-jwt

# installation with yarn
yarn add @auth0/angular-jwt

Usage: Standalone

If you are only interested in the JWT Decoder, and are not interested in extended injectable features, you can simply create an instance of the utility and use it directly:

import { JwtHelperService } from "@auth0/angular-jwt";

const helper = new JwtHelperService();

const decodedToken = helper.decodeToken(myRawToken);
const expirationDate = helper.getTokenExpirationDate(myRawToken);
const isExpired = helper.isTokenExpired(myRawToken);

Usage: Injection

Import the JwtModule module and add it to your imports list. Call the forRoot method and provide a tokenGetter function. You must also add any domains to the allowedDomains, that you want to make requests to by specifying an allowedDomains array.

Be sure to import the HttpClientModule as well.

import { JwtModule } from "@auth0/angular-jwt";
import { HttpClientModule } from "@angular/common/http";

export function tokenGetter() {
  return localStorage.getItem("access_token");
}

@NgModule({
  bootstrap: [AppComponent],
  imports: [
    // ...
    HttpClientModule,
    JwtModule.forRoot({
      config: {
        tokenGetter: tokenGetter,
        allowedDomains: ["example.com"],
        disallowedRoutes: ["http://example.com/examplebadroute/"],
      },
    }),
  ],
})
export class AppModule {}

Any requests sent using Angular's HttpClient will automatically have a token attached as an Authorization header.

import { HttpClient } from "@angular/common/http";

export class AppComponent {
  constructor(public http: HttpClient) {}

  ping() {
    this.http.get("http://example.com/api/things").subscribe(
      (data) => console.log(data),
      (err) => console.log(err)
    );
  }
}

Configuration Options

tokenGetter: function(HttpRequest): string

The tokenGetter is a function which returns the user's token. This function simply needs to make a retrieval call to wherever the token is stored. In many cases, the token will be stored in local storage or session storage.

// ...
JwtModule.forRoot({
  config: {
    // ...
    tokenGetter: () => {
      return localStorage.getItem("access_token");
    },
  },
});

If you have multiple tokens for multiple domains, you can use the HttpRequest passed to the tokenGetter function to get the correct token for each intercepted request.

// ...
JwtModule.forRoot({
  config: {
    // ...
    tokenGetter: (request) => {
      if (request.url.includes("foo")) {
        return localStorage.getItem("access_token_foo");
      }

      return localStorage.getItem("access_token");
    },
  },
});

allowedDomains: array

Authenticated requests should only be sent to domains you know and trust. Many applications make requests to APIs from multiple domains, some of which are not controlled by the developer. Since there is no way to know what the API being called will do with the information contained in the request, it is best to not send the user's token to all APIs in a blind fashion.

List any domains you wish to allow authenticated requests to be sent to by specifying them in the allowedDomains array. Note that standard http port 80 and https port 443 requests don't require a port to be specified. A port is only required in the allowed domains host name if you are authenticating against a non-standard port e.g. localhost:3001

// ...
JwtModule.forRoot({
  config: {
    // ...
    allowedDomains: ["localhost:3001", "foo.com", "bar.com"],
  },
});

disallowedRoutes: array

If you do not want to replace the authorization headers for specific routes, list them here. This can be useful if your initial auth route(s) are on an allowed domain and take basic auth headers. These routes need to be prefixed with the correct protocol (http://, https://). If you want to add a route to the list of disallowed routes regardless of the protocol, you can prefix it with //.

// ...
JwtModule.forRoot({
  config: {
    // ...
    disallowedRoutes: [
      "http://localhost:3001/auth/",
      "https://foo.com/bar/",
      "//foo.com/bar/baz",
      /localhost:3001\/foo\/far.*/,
    ], // strings and regular expressions
  },
});

Note: If requests are sent to the same domain that is serving your Angular application, you do not need to add that domain to the allowedDomains array. However, this is only the case if you don't specify the domain in the Http request.

For example, the following request assumes that the domain is the same as the one serving your app. It doesn't need to be allowed in this case.

this.http.get('/api/things')
  .subscribe(...)

However, if you are serving your API at the same domain as that which is serving your Angular app and you are specifying that domain in Http requests, then it does need to be explicitely allowed.

// Both the Angular app and the API are served at
// localhost:4200 but because that domain is specified
// in the request, it must be allowed
this.http.get('http://localhost:4200/api/things')
  .subscribe(...)

headerName: string

The default header name is Authorization. This can be changed by specifying a custom headerName which is to be a string value.

// ...
JwtModule.forRoot({
  config: {
    // ...
    headerName: "Your Header Name",
  },
});

authScheme: string | function(HttpRequest): string

The default authorization scheme is Bearer followed by a single space. This can be changed by specifying a custom authScheme. You can pass a string which will prefix the token for each request.

// ...
JwtModule.forRoot({
  config: {
    // ...
    authScheme: "Basic ",
  },
});

If you want to change the auth scheme dynamically, or based on the request, you can configure a getter function which returns a string.

// ...
JwtModule.forRoot({
  config: {
    // ...
    authScheme: (request) => {
      if (request.url.includes("foo")) {
        return "Basic ";
      }

      return "Bearer ";
    },
  },
});

throwNoTokenError: boolean

Setting throwNoTokenError to true will result in an error being thrown if a token cannot be retrieved with the tokenGetter function. Defaults to false.

// ...
JwtModule.forRoot({
  config: {
    // ...
    throwNoTokenError: true,
  },
});

skipWhenExpired: boolean

By default, the user's JWT will be sent in HttpClient requests even if it is expired. You may choose to not allow the token to be sent if it is expired by setting skipWhenExpired to true.

// ...
JwtModule.forRoot({
  config: {
    // ...
    skipWhenExpired: true,
  },
});

Using a Custom Options Factory Function

In some cases, you may need to provide a custom factory function to properly handle your configuration options. This is the case if your tokenGetter function relies on a service or if you are using an asynchronous storage mechanism (like Ionic's Storage).

Import the JWT_OPTIONS InjectionToken so that you can instruct it to use your custom factory function.

Create a factory function and specify the options as you normally would if you were using JwtModule.forRoot directly. If you need to use a service in the function, list it as a parameter in the function and pass it in the deps array when you provide the function.

import { JwtModule, JWT_OPTIONS } from '@auth0/angular-jwt';
import { TokenService } from './app.tokenservice';

// ...

export function jwtOptionsFactory(tokenService) {
  return {
    tokenGetter: () => {
      return tokenService.getAsyncToken();
    },
    allowedDomains: ["example.com"]
  }
}

// ...

@NgModule({
  // ...
  imports: [
    JwtModule.forRoot({
      jwtOptionsProvider: {
        provide: JWT_OPTIONS,
        useFactory: jwtOptionsFactory,
        deps: [TokenService]
      }
    })
  ],
  providers: [TokenService]
})

Note:: If a jwtOptionsFactory is defined, then config is ignored. Both configuration alternatives can't be defined at the same time.

Configuration for Ionic 2+

The custom factory function approach described above can be used to get a token asynchronously with Ionic's Storage.

import { JwtModule, JWT_OPTIONS } from '@auth0/angular-jwt';
import { Storage } from '@ionic/storage';

export function jwtOptionsFactory(storage) {
  return {
    tokenGetter: () => {
      return storage.get('access_token');
    },
    allowedDomains: ["example.com"]
  }
}

// ...

@NgModule({
  // ...
  imports: [
    JwtModule.forRoot({
      jwtOptionsProvider: {
        provide: JWT_OPTIONS,
        useFactory: jwtOptionsFactory,
        deps: [Storage]
      }
    })
  ]
})

Note:: If a jwtOptionsFactory is defined, then config is ignored. Both configuration alternatives can't be defined at the same time.

Configuration Options

JwtHelperService: service

This service contains helper functions:

isTokenExpired (old tokenNotExpired function)

import { JwtHelperService } from '@auth0/angular-jwt';
// ...
constructor(public jwtHelper: JwtHelperService) {}

ngOnInit() {
console.log(this.jwtHelper.isTokenExpired()); // true or false
}

getTokenExpirationDate

import { JwtHelperService } from '@auth0/angular-jwt';
// ...
constructor(public jwtHelper: JwtHelperService) {}

ngOnInit() {
console.log(this.jwtHelper.getTokenExpirationDate()); // date
}

decodeToken

import { JwtHelperService } from '@auth0/angular-jwt';
// ...
constructor(public jwtHelper: JwtHelperService) {}

ngOnInit() {
console.log(this.jwtHelper.decodeToken(token)); // token
}

What is Auth0?

Auth0 helps you to:

• Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, among others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
• Add authentication through more traditional username/password databases.
• Add support for linking different user accounts with the same user.
• Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
• Analytics of how, when and where users are logging in.
• Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free Auth0 account

1. Go to Auth0 and click Sign Up.
2. Use Google, GitHub or Microsoft Account to login.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Changelog

Version 5.0.0

Warning: this version has some breaking changes concerning the allowed domains and dissalowed routes!

• Replace whitelistedDomains to allowedDomains #668
• Replace blacklistedRoutes to disallowedRoutes #668
• Removed the url dependency, as this is a Node module in the CommonJS format, and the Angular 10 CLI throws warnings when using dependencies in the CommonJS format. We're using the default URL interface, https://developer.mozilla.org/en-US/docs/Web/API/URL #666

Full Changelog