@christianacca/angular-swa-auth

Programmatically work with Azure Static Web Apps authentication in an angular app

Features

- an AuthService facade
- methods to programmatically trigger sign-in, sign-up, sign-out and purge flows
- exposes convenient observables to allow your app to examine and/or react to current user and authentication session events
- optionally send authentication session events to your functions app
- AuthGuard
- add to a route to trigger the sign in flow when the user is not already authenticated
- SwaRoleGuard
- add to a route to perform an authorization check using roles defined in Status Web App
- SwaRoleCheckDirective
- structural directive to perform an authorization check using roles defined in Status Web App
- AutoLoginHttpInterceptor
- triggers the sign in flow when your functions api return an unauthenticated (401) response
- convenient types and values representing the authenticated user and identity providers
- configure the list of identity providers that should be available to your users to sign in with
- IdentityProviderInteractiveSelectorService
- utility service that can be used to build a UI to prompt the user to select an identity provider

When to use this library?

Depending on your use case you might not need this library at all. You likely do NOT need this library if your requirements are simple:
* Your angular app is ONLY served up to authenticated users
* It's not a problem that authentication does not work for deep linking (see issue 502)
* The same authorization rules apply to all client-side routes
* You don't need to inform your functions app when a user has signed in / out

If this is your app, then have a look at angular-swa-auth-nolib:
a sample app that does not use this library to implement authentication

For all other use cases, this library will likely add value.

Usage

$3

``bash
npm install @christianacca/angular-swa-auth
`

$3

1. Import library in app module:

`ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { SwaAuthModule } from '@christianacca/angular-swa-auth';

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

@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
SwaAuthModule.forRoot({
// overrides to the default configuration here
})
],
bootstrap: [AppComponent]
})
export class AppModule {}
`

2. Implement login/logout/purge

The following is guidance only. For an alternative, where the user is prompted with a modal
to select the identity provider to sign in with see IdentityProviderInteractiveSelectorService

`ts
import { Component } from '@angular/core';
import { AuthService, ClientPrincipal } from '@christianacca/angular-swa-auth';
import { Observable } from 'rxjs';

@Component({
selector: 'app-auth',
template:

})
export class AuthComponent {
userInfo$: Observable;
providers = this.authService.identityProviders;

constructor(private authService: AuthService) {
this.userInfo$ = this.authService.currentUser$;
}

login(identityProvider: string) {
this.authService.login({ identityProvider });
}

logout() {
this.authService.logout();
}

purge() {
this.authService.purge();
}
}
`

3. Optionally add AuthGuard to your route(s)

If your app can only be accessed by authenticated users then add the guard to the top level route. EG:

`ts
import { AuthGuard } from '@christianacca/angular-swa-auth';

const routes: Route[] = [
{
path: '',
canActivate: [AuthGuard],
children: [
{
path: 'home',
component: ShellComponent,
children: [
// routes to your "content" pages in your app
]
},
{ path: '', pathMatch: 'full', redirectTo: '/home' }
]
}
];
`

4. Optionally add SwaRoleGuard to your route(s)

`ts
import { AuthGuard } from '@christianacca/angular-swa-auth';

const routes: Route[] = [
{
path: 'product-admin',
data: {
allowedRoles: 'admin' // other ex: ['admin', 'owner'] ['admin', ['product-reader', 'owner']]
},
canActivate: [SwaRoleGuard],
component: AdminComponent
},
{
path: 'user-admin',
data: {
allowedRoles: 'owner'
},
canLoad: [SwaRoleGuard],
loadChildren: () => import('@christianacca/demo-app/user-admin').then(m => m.UserAdminModule)
}
];
`

5. Optionally send authentication session events to your function app api

`ts
imports: [
BrowserModule,
SwaAuthModule.forRoot({
sendSessionEventsToApi: true,
sessionEventsApiUrl: '/api/authevents' // this is the default if not supplied
})
]
`

IMPORTANT: you will need to add a function to your functions app api that receives via a POST an instance of AuthEventPayload

Next steps

$3

1. Install the Azure Static Web app emulator

`bash
npm i @azure/static-web-apps-cli -D
`

2. Add npm script to run your angular app

In package.json add the following to the scripts block:

`json
{
"scripts": {
"start:swa": "swa start http://localhost:4200 --run \"npm start\""
}
}
`

3. Serve your app:

`bash
npm run start:swa
``

You can now browse to your app at:

$3

Follow the official guidance here:

More resources

- Azure Static Web Apps documentation
- Library source code
- Library documentation:
- reference
- storybook
- Full working demo:
- deployed site
- source code
- Demo app that does NOT use a library to implement simple authentication:
- deployed site
- source code