From 35d780c75240427c033e6fff689569ae03705f1a Mon Sep 17 00:00:00 2001 From: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com> Date: Fri, 18 Oct 2024 13:11:52 +0200 Subject: [PATCH] docs: update auto-login page --- .../docs/documentation/auto-login.md | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/docs/site/angular-auth-oidc-client/docs/documentation/auto-login.md b/docs/site/angular-auth-oidc-client/docs/documentation/auto-login.md index 464221b2..e9abdb6a 100644 --- a/docs/site/angular-auth-oidc-client/docs/documentation/auto-login.md +++ b/docs/site/angular-auth-oidc-client/docs/documentation/auto-login.md @@ -5,24 +5,18 @@ sidebar_position: 9 # Auto Login -The library supports route-based automatic login thanks to the route guard: `AutoLoginPartialRoutesGuard`. The guard implements the necessary handlers for both `canActivate` and `canLoad`, and will preserve the route upon completing a successful login. - -:::info - -If you are using multiple configurations, the guards currently select the first provided configuration to perform the login.\_ - -::: +The library supports route-based automatic login thanks to the functional route guard: `autoLoginPartialRoutesGuard`. The guard implements the necessary handlers for both `canActivate` and `canMatch`, and will preserve the route upon completing a successful login. ## Common Scenarios Here are a couple of the common use cases. -### Auto Login when default route is not guarded +### Auto Login when the default route is not guarded -In this use case, some of your routes should be freely accessible, while others should be protected by a login, and the login should start when the user enters the protected route. +In this use case, some of your routes should be freely accessible, while others should be protected by a login, which should start when the user enters the protected route. ```ts -import { AutoLoginPartialRoutesGuard } from 'angular-auth-oidc-client'; +import { autoLoginPartialRoutesGuard } from 'angular-auth-oidc-client'; const routes: Routes = [ { path: '', pathMatch: 'full', redirectTo: 'home' }, @@ -30,77 +24,83 @@ const routes: Routes = [ { path: 'protected', component: ProtectedComponent, - canActivate: [AutoLoginPartialRoutesGuard], + canActivate: [autoLoginPartialRoutesGuard], }, { path: 'customers', - loadChildren: () => - import('./customers/customers.module').then((m) => m.CustomersModule), - canLoad: [AutoLoginPartialRoutesGuard], + loadChildren: () => import('./customers/customers.routes').then((m) => m.customerRoutes), + canLoad: [autoLoginPartialRoutesGuard], }, { path: 'unauthorized', component: UnauthorizedComponent }, ]; ``` In this case, the `/home` and `/unauthorized` routes are not protected, and they are accessible without a login. -Please make sure to call `checkAuth()` like normal in your `app.component.ts`. - -```ts -export class AppComponent implements OnInit { - private readonly oidcSecurityService = inject(OidcSecurityService); - - ngOnInit() { - this.oidcSecurityService - .checkAuth() - .subscribe(({ isAuthenticated, userData, accessToken }) => { - // ... - }); - } -} -``` - -### Auto Login when all routes are guarded - -:::caution +Please make sure to call [`checkAuth()`](./public-api#checkauthurl-string-configid-string) on the component that is bootstrapped (e.g. `app.component.ts`) to check the authentication status at the beginning of your application, or use the `withAppInitializerAuthCheck` function to automatically check the authentication status when the application starts. -Please do not use the `AutoLoginAllRoutesGuard` anymore as it is not recommended anymore, deprecated and will be removed in future versions of this library. - -More information [Why is AutoLoginAllRoutesGuard not recommended?](https://github.com/damienbod/angular-auth-oidc-client/issues/1549) - -::: +### Custom Params for the guard -If you want to protect your complete application, every route in your app, we recommend having one public route, e.g. `/callback` where your identity provider can redirect to. In this route you can set up the authentication and then redirect to the route you wanted to go to initially. This would be the "normal" behaviour of a SPA. You have to call `checkAuth()` in this `CallbackComponent` so that the url can be processed and set up, then redirect. Also think of calling `checkAuth()` in the AppComponent +If you need to pass custom params to the login request you can use the [data](https://angular.dev/api/router/Route#data) attribute of the route. +These parameters will then be appended to the login request. ```ts -import { AutoLoginPartialRoutesGuard } from 'angular-auth-oidc-client'; +import { autoLoginPartialRoutesGuard } from 'angular-auth-oidc-client'; const routes: Routes = [ { path: '', pathMatch: 'full', redirectTo: 'home' }, { path: 'home', component: HomeComponent, - canActivate: [AutoLoginPartialRoutesGuard], + canActivate: [autoLoginPartialRoutesGuard], + data: { custom: 'param' }, }, { path: 'callback', component: CallbackComponent }, // does nothing but setting up auth ]; ``` -### Custom Params for the guard +### Guard for a specific configuration + +To guard a route using a specific configuration, you can use the `autoLoginPartialRoutesGuardWithConfig` function. +This function takes the configuration ID as a parameter and will use the specified configuration to perform the login process. + +```ts +import { autoLoginPartialRoutesGuardWithConfig } from 'angular-auth-oidc-client'; + +const routes: Routes = [ + { + path: 'protected', + component: ProtectedComponent, + canActivate: [autoLoginPartialRoutesGuardWithConfig('config-id')], + }, +]; +``` -If you need to pass custom params to the login request you can simply use the [data](https://angular.io/api/router/Route#data) attribute of the route. -These parameters will then be appended to the login request +### NgModule (Guard classes) + +Instead of the functional guards, you can also use the guard classes. + +:::info + +If you use multiple configurations, the AutoLoginPartialRoutesGuard class-based guard selects the first provided configuration to perform the login. + +::: ```ts import { AutoLoginPartialRoutesGuard } from 'angular-auth-oidc-client'; const routes: Routes = [ { path: '', pathMatch: 'full', redirectTo: 'home' }, + { path: 'home', component: HomeComponent }, { - path: 'home', - component: HomeComponent, + path: 'protected', + component: ProtectedComponent, canActivate: [AutoLoginPartialRoutesGuard], - data: { custom: 'param' }, }, - { path: 'callback', component: CallbackComponent }, // does nothing but setting up auth + { + path: 'customers', + loadChildren: () => import('./customers/customers.module').then((m) => m.CustomersModule), + canLoad: [AutoLoginPartialRoutesGuard], + }, + { path: 'unauthorized', component: UnauthorizedComponent }, ]; ```