npm package: @ppwcode/ng-oauth
Description: This module is the ppwcode-way of dealing with OAuth in an Angular application.
Latest version: 2.0.0

# PPWCode Angular OAuth

This module is the ppwcode-way of dealing with OAuth in an Angular application.

The module ships with a token interceptor, a guard and a service managing the authentication process and using the
token.

## Installing

Run the following command to install the package using NPM:

```shell
npm install @ppwcode/ng-oauth
```

In case you're using Yarn:

```shell
yarn add @ppwcode/ng-oauth
```

## Run over HTTPS locally

Convert your application to run over `https` in development by changing the configuration of the `angular.json` file:

```json
{
    "projects": {
        "my-project": {
            "architect": {
                "serve": {
                    "configurations": {
                        "development": {
                            "port": 443,
                            "ssl": true
                        }
                    }
                }
            }
        }
    }
}
```

## Add to your application module

To add the module to your application, call the `.forRoot` method when importing in your root application module. By
adding the `PpwcodeOAuthModule` to your application module, this will automatically add the `TokenInterceptor`.

```ts
import { PpwcodeOAuthModule } from '@ppwcode/ng-oauth';

@NgModule({
    imports: [
        PpwcodeOAuthModule.forRoot([/** prefixes of urls to send token to */])
    ]
})
```

In the `.forRoot` call, specify an array of prefixes for urls to send the token to.

## Configure OAuth

The OAuth services used internally require some configuration parameters to be able to run the OAuth flow. Pass the
configuration in your main `AppComponent`:

```ts
import { OAuthService } from '@ppwcode/ng-oauth';

export class AppComponent {
    constructor(private readonly oAuthService: OAuthService) {
        this.configureOAuth();
    }

    private configureOAuth(): void {
        this.oAuthService.configureOAuth({
            issuer: '',
            redirectUri: '',
            clientId: '',
            resource: '',
            responseType: '',
            scope: ''
        });
    }
}
```

## Add the guard

Add the `OAuthAuthenticatedGuard` to the routes that you want to be accessible by users that are authenticated:

```ts
import { Routes } from '@angular/router';

const routes: Routes = [
    {
        path: 'awesome',
        component: MyAwesomeComponent,
        canActivate: [OAuthAuthenticatedGuard]
    }
];
```

This can even be applied on lazy loaded modules:

```ts
import { OAuthAuthenticatedGuard } from '@ppwcode/ng-oauth';

const routes: Routes = [
    {
        path: 'children',
        loadChildren: () => import('./children/children.module').then((m) => m.ChildrenModule),
        canActivate: [OAuthAuthenticatedGuard]
    }
];
```

## Getting the claims of the authenticated user

The `OAuthService.getIdentityClaims` function will give you the user claims or `null` if the user is not authenticated.

Because the claims can have any structure, you have to provide type safety yourself by leveraging the generic of the
function and make the interface extend `Record<string, unknown>`.

```ts
import { OAuthService } from '@ppwcode/ng-oauth';

export interface UserClaims extends Record<string, unknown> {
    unique_name: string;
    upn: string;
}

export class MyComponent {
    userClaims!: UserClaims | null;

    constructor(private readonly oAuthService: OAuthService) {}

    ngOnInit() {
        this.userClaims = this.oAuthService.getIdentityClaims<UserClaims>();
    }
}
```

> This will not limit the claims that are returned. Claims that have not been defined in the type are also returned.