Utilize o MSAL Guard para proteger as rotas

O MSAL Angular fornece MsalGuard, uma classe que pode usar para proteger rotas e requer autenticação antes de aceder à rota protegida. Este documento fornece mais informações sobre a configuração e as considerações a ter em conta ao utilizar o MsalGuard.

MsalGuard é uma classe de conveniência que podes usar para melhorar a experiência do utilizador, mas não deve ser usada para segurança. Os atacantes podem potencialmente contornar os guardas do lado do cliente, e deve garantir que o servidor não devolve quaisquer dados que o utilizador não deva aceder.

Também pode precisar de uma guarda de rota que satisfaça necessidades específicas. Incentivamo-lo a criar a sua própria proteção se MsalGuard não responder a todas essas necessidades.

Configurações

Configurar o MsalGuard no app.module.ts e no app-routing.module.ts

O MsalGuard pode ser adicionado à sua aplicação como provedor no ficheiro app.module.ts, juntamente com a respetiva configuração. A importação inclui uma instância de MSAL, bem como dois objetos de configuração específicos do Angular. O segundo argumento é um MsalGuardConfiguration objeto, que contém os valores para interactionType, um opcional authRequest, e um opcional loginFailedRoute.

Depois, MsalGuard é usado para proteger as rotas no app-routing.module.ts. O exemplo de código abaixo demonstra como adicionar o MsalGuard à rota Profile. Proteger a rota Profile significa que, mesmo que o utilizador não inicie sessão através do botão Login, se tentar aceder à rota Profile ou clicar no botão Profile, o MsalGuard solicitará ao utilizador que se autentique através de uma janela de pop-up ou de redirecionamento antes de apresentar a página Profile.

A sua configuração pode parecer a que está abaixo. Consulte o nosso documento de configuração sobre outras formas de configurar o MSAL Angular para a sua aplicação, e as secções abaixo para mais detalhes sobre o MsalConfiguration objeto e interfaces para o encaminhamento.

// app.module.ts
import { NgModule } from '@angular/core';
import { HTTP_INTERCEPTORS, HttpClientModule } from "@angular/common/http";
import { MsalModule, MsalRedirectComponent, MsalGuard } from '@azure/msal-angular'; // Import MsalInterceptor
import { InteractionType, PublicClientApplication } from '@azure/msal-browser';
import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';

@NgModule({
    declarations: [
        AppComponent,
    ],
    imports: [
        MsalModule.forRoot( new PublicClientApplication({
            // MSAL Configuration
        }), {
            // MSAL Guard Configuration
            interactionType: InteractionType.Redirect,
            authRequest: {
                scopes: ['user.read']
            },
            loginFailedRoute: '/login-failed'
        }, {
            // MSAL Interceptor Configurations
        }),
        AppRoutingModule
    ],
    providers: [
        // ...
        MsalGuard
    ],
    bootstrap: [AppComponent, MsalRedirectComponent]
})
export class AppModule { }

// app-routing.module.ts
import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { ProfileComponent } from './profile/profile.component';
import { MsalGuard } from '@azure/msal-angular';

const routes: Routes = [
    {
        path: 'profile',
        component: ProfileComponent,
        canActivate: [MsalGuard]
    },
    {
        path: '',
        component: HomeComponent
    },
];

@NgModule({
    imports: [RouterModule.forRoot(routes)],
    exports: [RouterModule]
})
export class AppRoutingModule { }

Tipo de Interação

Definir o tipo de interação determina como o MsalGuard solicitará interativamente o início de sessão. Podem InteractionType ser importados de @azure/msal-browser e definidos para Popup ou Redirect.

AuthRequest opcional

O opcional authRequest é uma funcionalidade avançada que não é obrigatória. No entanto, recomendamos definir authRequest no MsalGuardConfiguration com scopes para que o consentimento possa ser obtido antecipadamente para os âmbitos. Se o consentimento para scopes não for concedido inicialmente, os escopos podem ser obtidos de forma incremental. Isto pode resultar na apresentação de um diálogo de consentimento ao utilizador da aplicação várias vezes.

A concessão prévia de consentimento para os scopes é demonstrada nos exemplos de código acima e nas nossas amostras.

Todos os parâmetros possíveis para o objeto de pedido podem ser encontrados aqui: PopupRequest e RedirectRequest.

Falha na rota de início de sessão

A loginFailedRoute cadeia pode ser definida em MsalGuardConfiguration. O MsalGuard redirecionará para esta rota se a autenticação for necessária e falhar.

Consulte o exemplo do Angular para exemplos de implementação no módulo de configuração e encaminhamento de aplicações.

Note que o redirecionamento em caso de falha não está disponível para aplicações Angular 9 que utilizam a CanLoad interface devido a diferenças no tipo base.

Interfaces

Além de canActivate, MsalGuard também implementa canActivateChild e canLoad, e estes podem ser adicionados às definições de rotas em app-routing.module.ts. Pode ver estes usados na nossa aplicação de exemplo mais antiga MSAL Angular v2 Angular 11, assim como abaixo. Para mais informações sobre interfaces, consulte a documentação do Angular.

const routes: Routes = [
    {
        path: 'profile',
        canActivateChild: [MsalGuard],
        children: [
        {
            path: '',
            component: ProfileComponent
        },
        {
            path: 'detail',
            component: DetailComponent
        }
        ]
    },
    { 
        path: 'lazyLoad', 
        loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule),
        canLoad: [MsalGuard]
    },
];

Considerações ao utilizar a MSAL Guard

Utilização do MSAL Guard na página inicial

Definir o MsalGuard na página inicial é a nossa recomendação, caso queira que os utilizadores sejam convidados a iniciar sessão quando acedirem à sua aplicação. Não recomendamos chamar login no ngOnInit em app.component.ts, pois isso pode causar ciclos de redirecionamento.

As nossas recomendações adicionais dependem da sua estratégia de encaminhamento e podem ser encontradas nas secções abaixo.

Utilização do MSAL Guard com roteamento de caminho

Ao utilizar o PathLocationStrategy e redirecionamentos na sua aplicação Angular, recomendamos a utilização de uma rota dedicada para redirecionamentos, o que ajudará a evitar ciclos. Esta rota também deve ser a sua redirectUri, e não deve ser protegida pelo MsalGuard.

const routes: Routes = [
    {
        path: 'profile',
        component: ProfileComponent,
        canActivate: [MsalGuard]
    },
    {
        // Dedicated route for redirects
        path: 'auth', 
        component: MsalRedirectComponent
    },
    {
        path: '',
        component: HomeComponent
    }
];

Para iniciar sessão dos utilizadores ao chegarem à sua aplicação, ao utilizar PathLocationStrategy, recomendamos:

  • Definir o MsalGuard na sua página inicial
  • Defina o seu redirectUri para 'http://localhost:4200/auth'
  • Adicionar um 'auth' caminho às suas rotas, definir o MsalRedirectComponent como o componente (esta rota não deve ser protegida pelo MsalGuard)
  • Garantir que o MsalRedirectComponent é inicializado
  • Opcionalmente: adicionar MsalGuard a todas as tuas rotas se quiseres proteger todas as tuas rotas

O nosso exemplo de módulos Angular utiliza o PathLocationStrategy e demonstra como proteger rotas com o MsalGuard.

Utilização de MSAL Guard com roteamento com hash

Ao usar o router HashLocationStrategy com a sua aplicação Angular, recomendamos vivamente que defina rotas de marcador (como /code) no ficheiro app-routing.module.ts para evitar que o router do Angular seja acionado quando o Microsoft Entra ID devolver a resposta do código de autenticação no hash, caso contrário, poderá ter problemas em concluir a autenticação. Estas rotas provisórias não devem ser protegidas pelo MsalGuard, nem devem apontar para um componente que desencadeie uma interação ou faça chamadas protegidas à API ao carregar a página.

const routes: Routes = [
  {
    path: 'profile',
    component: ProfileComponent,
    canActivate: [MsalGuard]
  },
  {
    // Needed for hash routing
    path: 'code',
    component: HomeComponent
  },
  {
    path: '',
    component: HomeComponent
  }
];

A redirectUri na Configuração do MSAL também deve ser definida para a página inicial.

Para iniciar sessão dos utilizadores ao chegarem à sua aplicação, ao utilizar HashLocationStrategy, recomendamos:

  • Definir o MsalGuard na sua página inicial
  • Não definir o MsalGuard em rotas de marcador de posição (por exemplo, /code, /error)
  • Garantir que o MsalRedirectComponent é inicializado
  • Opcionalmente: adicionar MsalGuard a todas as outras rotas se quiseres proteger todas as tuas rotas

Veja o nosso exemplo anterior do MSAL Angular v2 para Angular 11, que utiliza o HashLocationStrategy e demonstra como proteger rotas com MsalGuard.

Alterações da versão 1 para a versão 2 do msal-angular

  • Configuração: MsalAngularConfiguration foi descontinuada e já não funciona. A configuração do MsalGuard é agora feita através do MsalGuardConfiguration.
  • Interfaces: MsalGuard agora implementa CanActivateChild e CanLoad além de CanActivate. Consulte a secção acima sobre Interfaces para mais detalhes.
  • Redirecionamento em caso de falha: MsalGuard a configuração dispõe agora de um loginFailedRoute configurável. Consulte a secção acima sobre o loginFailedRoute para mais detalhes.
  • Last updated on