ng-ebi-authorization

The ng-ebi-authorization is a simple authentication Angular library that relies on EBI's Authentication and Authorization Profile (AAP) infrastructure. After successful login, a JWT token is stored on the browser (via cookie, local or session storage).

Because of CORS, if the library is tested against 'explore.api.aai.ebi.ac.uk' origin should be localhost:4200.

See example in stackblitz.

Installation

To install this library, run:

npm install --save ng-ebi-authorization @auth0/angular-jwt

or

yarn add ng-ebi-authorization @auth0/angular-jwt

Compatibility table

| Angular version | ng-ebi-authorization version | | --------------- | ----------------------------------------------------------------------------------- | | >=5 <6 | <= [email protected] (deprecated) | | >=6 <8 | >= [email protected] (deprecated) or [email protected] |

ng-ebi-authorization is an updated version of angular-aap-auth.

Consuming the library

The library exposes user information through User objects, which have information that's usually required for web application to work:

• The unique identifier (uid): if a unique identifier has to be used, use this field.
• Name (name): the full name of the user, for display purposes
• Nickname (nickname): if the user is in a local aap account, it will contain the username, otherwise will have a weird string.
• Email (email): the account's email, this is for information only and several accounts may have the same username.
• Domains (domains): not directly provided because they may be misused. The checking of domains should be done always server-side. If the domains information wants to be shown to the user as information it can still be done, check the Advanced usage to see how to expose arbitrary token claims, or the embedded app.

In your Angular AppModule (app.module.ts):

import {
    BrowserModule
} from '@angular/platform-browser';
import {
    NgModule
} from '@angular/core';

import {
    HttpClientModule
} from '@angular/common/http';
import {
    AuthModule
} from 'ng-ebi-authorization';
import {
    JwtModule
} from '@auth0/angular-jwt';

import {
    AppComponent
} from './app.component';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        HttpClientModule,
        AuthModule.forRoot(), // Defaults to localStorage `id_token` key.
        JwtModule.forRoot({
            config: {
                tokenGetter: () => localStorage.getItem('id_token')
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule {}

The default configuration uses localStorage to save the JWT token under the key 'id_token'. See Advanced usage for a more fine grained configuration.

Example use on a component:

import {
    Component,
    OnInit
} from '@angular/core';
import {
    Observable,
} from 'rxjs';

import {
    AuthService,
    User
} from 'ng-ebi-authorization';

@Component({
    selector: 'app-root',
    template: `
    <button (click)="auth.openLoginWindow()">Login small window</button>
    <button (click)="auth.openLoginTab()">Login new tab</button>
    <button (click)="auth.logOut()">Logout</button>

    <div *ngIf="user | async; else loggedOut">
        <p>Name: {{ user.name }}</p>
        <p>Unique Identifier: {{ user.uid }}</p>
        <p>Email: {{ user.email }}</p>
        <p>Token: {{ user.token }}</p>
    </div>
    <ng-template #loggedOut>
        <p>Please, log in.</p>
    </ng-template>
    `
})
export class AppComponent implements OnInit {
    user: Observable < User | null > ;

    constructor(
        // Public for demonstration purposes
        public auth: AuthService,
    ) {
        this.user = auth.user();
    }

    ngOnInit() {
        this.auth.addLogInEventListener(() => console.log('Welcome'));
        this.auth.addLogOutEventListener(() => console.log('Bye'));
    }
}

Advanced usage

Advanced module configuration:

import {
    BrowserModule
} from '@angular/platform-browser';
import {
    NgModule
} from '@angular/core';

import {
    HttpClientModule
} from '@angular/common/http';
import {
    AuthModule
} from 'ng-ebi-authorization';
import {
    JwtModule
} from '@auth0/angular-jwt';

import {
    AppComponent
} from './app.component';

export function getToken(): string {
    return localStorage.getItem('jwt_token') || '';
}
export function updateToken(newToken: string): void {
    return localStorage.setItem('jwt_token', newToken);
}
// Optional
export function removeToken(): void {
    return localStorage.removeItem('jwt_token');
}

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        HttpClientModule
        AuthModule.forRoot({
            aapURL: 'https://api.aai.ebi.ac.uk',
            tokenGetter: getToken,
            tokenUpdater: updateToken,
            tokenRemover: removeToken // Optional
        }),
        JwtModule.forRoot({
            config: {
                tokenGetter: getToken,
                whitelistedDomains: ['api.aai.ebi.ac.uk'], // Necessary for creating domains
                blacklistedRoutes: ['https://api.aai.ebi.ac.uk/auth'] // Necessary for login via AAP local account (instead of ELIXIR)
            }
        })
    ],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule {}

Example on how to get specific claims:

import {
    Component,
    OnInit
} from '@angular/core';
import {
    Observable
} from 'Observable';
import {
    map
} from 'rxjs/operators';

import {
    AuthService,
    TokenService // Needed for JWT claim introspection
} from 'ng-ebi-authorization';

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

@Component({
    selector: 'app-root',
    template: `
    <button (click)="openLoginWindow()">Login small window</button>
    <button (click)="logOut()">Logout</button>

    <div *ngIf="(user | async) as user; else loggedOut">
        <p>Expiration Date: {{ expiration | async }}</p>
        <p>Issuer: {{ iss | async }}</p>

    </div>
    <ng-template #loggedOut>
        <p>Please, log in.</p>
    </ng-template>
    `
})
export class AppComponent implements OnInit {
    user: Observable < User | null > ;

    // How to obtain other claims
    expiration: Observable < Date | null > ;
    domains: Observable < string[] > ;
    iss: Observable < string | null > ;

    constructor(
        // Public for demonstration purposes
        private auth: AuthService,
        private token: TokenService
    ) {
        this.user = auth.user();

        this.expiration = this.user.pipe(
            map(user => token.getTokenExpirationDate())
        );

        this.domains = this.user.pipe(
            map(_ => _tokens.getClaim < string[], string[] > ('domains', []))
        );

        this.iss = this.user.pipe(
            map(_ => token.getClaim < string, null > ('iss', null))
        );
    }

    openLoginWindow() {
        // ttl: time of live, and location
        this.auth.openLoginWindow({
            'ttl': '1'
        }, 500, 500, 100, 100);
    }

    logOut() {
        this.auth.logOut();
    }

    ngOnInit() {
        // Demonstration of register and unregister login events
        this.auth.addLogInEventListener(() => console.log('Welcome'));
        const firstEventID = this.auth.addLogInEventListener(() => console.log('This should not be visible'));
        this.auth.removeLogInEventListener(firstEventID);
        this.auth.addLogInEventListener(() => alert('Welcome'));
        const secondEventID = this.auth.addLogInEventListener(() => alert('This should never be displayed'));
        this.auth.removeLogInEventListener(secondEventID);

        // Demonstration of register and unregister logout events
        this.auth.addLogOutEventListener(() => console.log('Bye'));
        const thirdEventID = this.auth.addLogOutEventListener(() => console.log('This should not be visible'));
        this.auth.removeLogOutEventListener(thirdEventID);
        this.auth.addLogOutEventListener(() => alert('Bye'));
        const fourthEventID = this.auth.addLogOutEventListener(() => alert('This should never be displayed'));
        this.auth.removeLogOutEventListener(fourthEventID);
    }
}

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our guidelines for contributing.

License

Apache 2.0 © EMBL - European Bioinformatics Institute