From 49e4dccc2e849b0d6b1521f3c501205fab42ea24 Mon Sep 17 00:00:00 2001 From: Ryan Diehl Date: Thu, 9 Jul 2020 16:15:48 -0400 Subject: [PATCH] updates readme --- libs/utils/security-ngrx/README.md | 33 +++++++-- .../src/lib/security.facade.spec.ts | 2 +- libs/utils/security/README.md | 69 ++++++++++++++++++- 3 files changed, 97 insertions(+), 7 deletions(-) diff --git a/libs/utils/security-ngrx/README.md b/libs/utils/security-ngrx/README.md index 9caf987..3a6d3c0 100644 --- a/libs/utils/security-ngrx/README.md +++ b/libs/utils/security-ngrx/README.md @@ -1,7 +1,32 @@ -# utils-security-ngrx +# @psu/utils/security-ngrx -This library was generated with [Nx](https://nx.dev). +NgRx extensions for @psu/utils/security. -## Running unit tests +## Class Interfaces -Run `nx test utils-security-ngrx` to execute the unit tests. +This library makes use of class interfaces for dependency injection of vendor-specific authentication functionality. +External libraries such as @psu/msal-oidc will provide implementation of these interfaces. + +### SecurityEventListener + +`SecurityEventListener` defines an interface for a service that handles authentication related events that should +trigger NgRx actions. + +### Providers + +This library exports a helper function to allow you to provide implementations for these class interfaces - +`provideSecurityEventListener()`. + +``` + providers: [ + ..., + VendorSecurityEventListener, + provideSecurityEventListener(VendorSecurityEventListener), + ] +``` + +## Facade + +The `SecurityFacade` abstracts away most details of the NgRx implementation and provides helper functions and properties +for apps to use. It injects the `SecurityEventListener` and listens for login success, failure, etc. events, and +then dispatches corresponding actions against the store. diff --git a/libs/utils/security-ngrx/src/lib/security.facade.spec.ts b/libs/utils/security-ngrx/src/lib/security.facade.spec.ts index d42be87..a722804 100644 --- a/libs/utils/security-ngrx/src/lib/security.facade.spec.ts +++ b/libs/utils/security-ngrx/src/lib/security.facade.spec.ts @@ -58,7 +58,7 @@ describe('SecurityFacade', () => { it('listener loginFailure should dispatch loginFailure action', () => { loginFailed$.next('no'); expect(store.dispatch).toHaveBeenCalledWith(loginFailure({ message: 'no' })); - loginFailed$.next(undefined); + loginFailed$.next(); expect(store.dispatch).toHaveBeenCalledWith(loginFailure({})); }); }); diff --git a/libs/utils/security/README.md b/libs/utils/security/README.md index 0777509..da9106a 100644 --- a/libs/utils/security/README.md +++ b/libs/utils/security/README.md @@ -1,3 +1,68 @@ -# Security Utils +# @psu/utils/security -This will eventually be the home of the refactored and de-spaghettified security utils, but for now it just has a single string constant for the `REQUIRE_AUTH_HEADER` since I needed somewhere to put it and didn't want to import the entire security library just for one constant. +This entrypoint contains cross-cutting security functionality that is independent of any actual auth +implementation. Where we need to interact with a specific auth implementation (@psu/security, @psu/msal-oidc, etc.), +this entrypoint exposes class interfaces and dependency injection helpers for the implementor. + +## Class Interfaces + +This library makes use of class interfaces for dependency injection of vendor-specific authentication functionality. +External libraries such as @psu/msal-oidc will provide implementation of these interfaces. + +### AuthService + +`AuthService` defines methods to log a user into a system and get user information such as userName (ideally from +something like an ID token using OIDC). + +### TokenService + +`TokenService` defines methods to acquire tokens during HTTP flows. + +### Providers + +This library exports a couple of helper functions to allow you to provide implementations for these class interfaces - +`provideAuthService()` and `provideTokenService()`. + +``` + providers: [ + ..., + VendorAuthService, + provideAuthService(VendorAuthService), + VendorTokenService, + provideVendorTokenService(VendorTokenService), + ] +``` + +## Interceptors + +### AuthInterceptor + +`AuthInterceptor` provides an implementation-agnostic way to attach `Bearer` tokens to outgoing HTTP requests. +It leverages the existing `REQUIRE_AUTH_HEADER` constant that our apis library already uses. It should be a drop-in +replacement for the implementation from @psu/security, with the exception that we no longer support the legacy +`protectedUrls` configuration parameter (though it could be re-added if needed). + +The interceptor injects `TokenService`, which is a class interface. This library does not provide an implementation +for this service, instead it should be implemented by vendor-specific libraries like @psu/msal-oidc. The TokenService +is used to acquire a token. + +### UseridRequestTracingInterceptor + +`UseridRequestTracingInterceptor` provides an implementation-agnostic way to set custom `x-request-id` headers that +include the username of the currently logged in user. It is a drop-in replacement for the version in @psu/security. + +The interceptor injects `AuthService`, which is a class interface. This library does not provide an implementation +for this service, instead it should be implemented by vendor-specific libraries like @psu/msal-oidc. The AuthService +is used to determine if a user is currently logged in. + +## Models + +The `User` interface defines an authenticated user. Its only field is a `userName` at this point. Your implementation +will likely have additional fields such as identity claims. + +## Guards + +### AlreadyLoggedInGuard + +The `AlreadyLoggedInGuard` can be used to redirect users away from anonymous resources like a login screen, if they are +currently authenticated. It injects `AuthService`, see above. -- GitLab