418 lines
14 KiB
Markdown
418 lines
14 KiB
Markdown
# Authentification Cognito pour webapps Angular
|
||
|
||
Ce guide décrit comment intégrer l’authentification AWS Cognito (OIDC Code Flow avec PKCE) dans nos applications Angular.
|
||
|
||
## Pré‑requis côté Cognito
|
||
|
||
- Un User Pool Cognito créé
|
||
- Un App client « Public client » (sans secret) avec PKCE activé
|
||
- Un domaine Cognito configuré (ex: `my-tenant.auth.eu-west-1.amazoncognito.com`)
|
||
- Scopes OIDC: `openid`, `email`, `profile` (ajoutez d’autres scopes si besoin)
|
||
- URLs de redirection et de logout autorisées
|
||
- Dev (Angular local):
|
||
- Callback: `http://localhost:4200/callback`
|
||
- Logout: `http://localhost:4200`
|
||
- Prod: adaptez avec votre domaine (ex: `https://app.example.com/callback` et `https://app.example.com`)
|
||
|
||
## Variables de configuration (Angular)
|
||
|
||
Exemple d’entrée `environment.ts`:
|
||
|
||
```typescript
|
||
export const environment = {
|
||
production: false,
|
||
cognito: {
|
||
userPoolId: 'eu-west-1_XXXXXXXXX',
|
||
userPoolWebClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
|
||
domain: 'my-tenant.auth.eu-west-1.amazoncognito.com',
|
||
redirectSignIn: 'http://localhost:4200/callback',
|
||
redirectSignOut: 'http://localhost:4200',
|
||
region: 'eu-west-1',
|
||
scopes: ['openid', 'email', 'profile']
|
||
}
|
||
};
|
||
```
|
||
|
||
Mettez à jour `environment.prod.ts` avec les URLs de production.
|
||
|
||
## Option A — Hosted UI via AWS Amplify
|
||
|
||
Installation:
|
||
|
||
```bash
|
||
npm i aws-amplify @aws-amplify/ui-angular
|
||
```
|
||
|
||
Configuration (ex: `main.ts` ou `app.module.ts`):
|
||
|
||
```typescript
|
||
import { Amplify } from 'aws-amplify';
|
||
import { environment } from './environments/environment';
|
||
|
||
Amplify.configure({
|
||
Auth: {
|
||
region: environment.cognito.region,
|
||
userPoolId: environment.cognito.userPoolId,
|
||
userPoolWebClientId: environment.cognito.userPoolWebClientId,
|
||
oauth: {
|
||
domain: environment.cognito.domain,
|
||
scope: environment.cognito.scopes,
|
||
redirectSignIn: environment.cognito.redirectSignIn,
|
||
redirectSignOut: environment.cognito.redirectSignOut,
|
||
responseType: 'code'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
Initiation du login (Hosted UI) et gestion du callback (ex: dans un service d’auth):
|
||
|
||
```typescript
|
||
import { Auth } from 'aws-amplify';
|
||
|
||
export class AuthService {
|
||
signIn(): Promise<void> {
|
||
return Auth.federatedSignIn(); // redirige vers Hosted UI
|
||
}
|
||
|
||
async handleCallback(): Promise<void> {
|
||
// Amplify gère automatiquement l’échange du code contre les tokens
|
||
const session = await Auth.currentSession();
|
||
const idToken = session.getIdToken().getJwtToken();
|
||
const accessToken = session.getAccessToken().getJwtToken();
|
||
// Stockez/consommez les tokens selon vos besoins
|
||
}
|
||
|
||
signOut(): Promise<void> {
|
||
return Auth.signOut(); // redirige vers redirectSignOut
|
||
}
|
||
}
|
||
```
|
||
|
||
Routing du callback (ex: `app-routing.module.ts`):
|
||
|
||
```typescript
|
||
{ path: 'callback', component: CallbackComponent }
|
||
```
|
||
|
||
Dans `CallbackComponent`, appelez `handleCallback()` puis redirigez l’utilisateur vers l’app.
|
||
|
||
## Option B — angular-oauth2-oidc (OIDC Code Flow + PKCE)
|
||
|
||
Installation:
|
||
|
||
```bash
|
||
npm i angular-oauth2-oidc
|
||
```
|
||
|
||
Configuration (ex: `app.module.ts` et un `auth.config.ts`):
|
||
|
||
```typescript
|
||
// auth.config.ts
|
||
import { AuthConfig } from 'angular-oauth2-oidc';
|
||
|
||
export const authConfig: AuthConfig = {
|
||
issuer: 'https://my-tenant.auth.eu-west-1.amazoncognito.com',
|
||
clientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
|
||
responseType: 'code',
|
||
redirectUri: 'http://localhost:4200/callback',
|
||
postLogoutRedirectUri: 'http://localhost:4200',
|
||
scope: 'openid email profile',
|
||
showDebugInformation: false,
|
||
strictDiscoveryDocumentValidation: false, // Cognito n’expose pas toujours toutes les métadonnées standard
|
||
};
|
||
```
|
||
|
||
Initialisation au démarrage (ex: `app.module.ts`):
|
||
|
||
```typescript
|
||
import { OAuthService, OAuthModule } from 'angular-oauth2-oidc';
|
||
import { authConfig } from './auth.config';
|
||
|
||
providers: [
|
||
{
|
||
provide: APP_INITIALIZER,
|
||
multi: true,
|
||
deps: [OAuthService],
|
||
useFactory: (oauthService: OAuthService) => () => {
|
||
oauthService.configure(authConfig);
|
||
oauthService.setupAutomaticSilentRefresh();
|
||
return oauthService.loadDiscoveryDocumentAndLogin();
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
Déclenchement du login/logout:
|
||
|
||
```typescript
|
||
login(): void { this.oauthService.initLoginFlow(); }
|
||
logout(): void { this.oauthService.logOut(); }
|
||
getIdToken(): string | null { return this.oauthService.getIdToken(); }
|
||
```
|
||
|
||
Protection de routes (ex: guard minimal):
|
||
|
||
```typescript
|
||
canActivate(): boolean {
|
||
return this.oauthService.hasValidAccessToken() || this.oauthService.hasValidIdToken();
|
||
}
|
||
```
|
||
|
||
## Bonnes pratiques
|
||
|
||
- Utilisez le flow « Authorization Code + PKCE » pour les SPAs (sécurité accrue)
|
||
- Déclarez toutes les URLs de callback/logout (local, staging, prod) dans Cognito
|
||
- Synchronisez l’heure système (skew de plus de 5 min peut invalider les tokens)
|
||
- Évitez d’exposer des secrets côté frontend (client public uniquement)
|
||
- Renouvelez silencieusement les tokens lorsque possible (silent refresh)
|
||
|
||
## Dépannage
|
||
|
||
- `invalid_redirect_uri` / `redirect_mismatch`: vérifiez les URLs exactes dans Cognito
|
||
- Erreur « Not authorized » après login: facteurs possibles — scopes manquants, app client erroné
|
||
- Boucle de redirection: callback non routé ou handler non exécuté
|
||
- CORS/API: frontend authentifié ≠ API autorisée; configurez vos authorizers/API Gateway
|
||
- Cookies SameSite: si vous utilisez des cookies, ajustez SameSite/Lax/None selon le contexte
|
||
|
||
## Checklist déploiement
|
||
|
||
- Mettre à jour les URLs de callback/logout en prod
|
||
- Activer HTTPS sur le domaine de l’app
|
||
- Vérifier que le domaine Cognito est public et résout correctement
|
||
- Tester login/logout et rafraîchissement de token en environnement prod
|
||
|
||
## Activation conditionnelle via variable d’environnement + Guard Angular
|
||
|
||
Nous supportons un mode où l’authentification Cognito est optionnelle selon une variable d’environnement, et une Guard Angular assure la redirection vers une page de login configurable.
|
||
|
||
### Variables d’environnement
|
||
|
||
Dans `environment.ts` et `environment.prod.ts`:
|
||
|
||
```typescript
|
||
export const environment = {
|
||
production: false,
|
||
requireAuth: true, // si false, la Guard laisse passer sans authentification
|
||
loginRoute: '/login', // route Angular interne servant le bouton/flux de login
|
||
cognito: {
|
||
userPoolId: 'eu-west-1_XXXXXXXXX',
|
||
userPoolWebClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxxx',
|
||
domain: 'my-tenant.auth.eu-west-1.amazoncognito.com',
|
||
redirectSignIn: 'http://localhost:4200/callback',
|
||
redirectSignOut: 'http://localhost:4200',
|
||
region: 'eu-west-1',
|
||
scopes: ['openid', 'email', 'profile']
|
||
}
|
||
};
|
||
```
|
||
|
||
Mettez `requireAuth: false` sur des environnements de démonstration internes si nécessaire. En production, laissez `true`.
|
||
|
||
### Utilisation des fichiers .env d’Angular
|
||
|
||
Nous utilisons les fichiers `.env` d’Angular pour fournir ces variables au build. Créez les fichiers à la racine du projet Angular (même niveau que `package.json`) :
|
||
|
||
- `.env` (valeurs par défaut communes)
|
||
- `.env.development` (lues en dev)
|
||
- `.env.production` (lues en prod)
|
||
|
||
Exemple `.env.development` :
|
||
|
||
```bash
|
||
NG_APP_REQUIRE_AUTH=true
|
||
NG_APP_LOGIN_ROUTE=/login
|
||
NG_APP_COGNITO_USER_POOL_ID=eu-west-1_XXXXXXXXX
|
||
NG_APP_COGNITO_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
NG_APP_COGNITO_DOMAIN=my-tenant.auth.eu-west-1.amazoncognito.com
|
||
NG_APP_COGNITO_REDIRECT_SIGNIN=http://localhost:4200/callback
|
||
NG_APP_COGNITO_REDIRECT_SIGNOUT=http://localhost:4200
|
||
NG_APP_COGNITO_REGION=eu-west-1
|
||
NG_APP_COGNITO_SCOPES=openid,email,profile
|
||
```
|
||
|
||
Exemple `.env.production` :
|
||
|
||
```bash
|
||
NG_APP_REQUIRE_AUTH=true
|
||
NG_APP_LOGIN_ROUTE=/login
|
||
NG_APP_COGNITO_USER_POOL_ID=eu-west-1_YYYYYYYYY
|
||
NG_APP_COGNITO_WEB_CLIENT_ID=yyyyyyyyyyyyyyyyyyyyyyyyyy
|
||
NG_APP_COGNITO_DOMAIN=prod-tenant.auth.eu-west-1.amazoncognito.com
|
||
NG_APP_COGNITO_REDIRECT_SIGNIN=https://app.example.com/callback
|
||
NG_APP_COGNITO_REDIRECT_SIGNOUT=https://app.example.com
|
||
NG_APP_COGNITO_REGION=eu-west-1
|
||
NG_APP_COGNITO_SCOPES=openid,email,profile
|
||
```
|
||
|
||
Conventions :
|
||
- Préfixe recommandé: `NG_APP_` pour exposer la variable au code frontend
|
||
- Les `.env.*` sont sélectionnés selon la configuration Angular (ex: `ng serve` utilise `development`, `ng build --configuration=production` utilise `production`)
|
||
|
||
Lecture dans le code Angular (Angular 17+/Vite) :
|
||
|
||
```typescript
|
||
const env = (import.meta as any).env as Record<string, string>;
|
||
|
||
export const environment = {
|
||
production: env['MODE'] === 'production',
|
||
requireAuth: String(env['NG_APP_REQUIRE_AUTH']).toLowerCase() === 'true',
|
||
loginRoute: env['NG_APP_LOGIN_ROUTE'] || '/login',
|
||
cognito: {
|
||
userPoolId: env['NG_APP_COGNITO_USER_POOL_ID'],
|
||
userPoolWebClientId: env['NG_APP_COGNITO_WEB_CLIENT_ID'],
|
||
domain: env['NG_APP_COGNITO_DOMAIN'],
|
||
redirectSignIn: env['NG_APP_COGNITO_REDIRECT_SIGNIN'],
|
||
redirectSignOut: env['NG_APP_COGNITO_REDIRECT_SIGNOUT'],
|
||
region: env['NG_APP_COGNITO_REGION'],
|
||
scopes: (env['NG_APP_COGNITO_SCOPES'] || 'openid,email,profile').split(',')
|
||
}
|
||
};
|
||
```
|
||
|
||
Note : selon la version de l’outillage Angular, l’accès peut être `import.meta.env.NG_APP_...` au lieu de l’indexation par chaîne. Gardez le préfixe `NG_APP_` pour garantir l’exposition au build.
|
||
|
||
### Injection des `.env` via Docker / docker-compose
|
||
|
||
Nos builds frontend sont statiques (servis par `serve`). Les variables doivent donc être connues au BUILD. Utilisez des `build.args` dans `docker-compose.yml` et, côté Dockerfile, écrivez un fichier `.env.production` avant le build Angular.
|
||
|
||
Exemple `docker-compose.yml` (extrait service `frontend`) :
|
||
|
||
```yaml
|
||
services:
|
||
frontend:
|
||
build:
|
||
context: ./frontend
|
||
dockerfile: ./frontend-dockerfile.yml
|
||
args:
|
||
NG_APP_REQUIRE_AUTH: "true"
|
||
NG_APP_LOGIN_ROUTE: "/login"
|
||
NG_APP_COGNITO_USER_POOL_ID: "eu-west-1_XXXXXXXXX"
|
||
NG_APP_COGNITO_WEB_CLIENT_ID: "xxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||
NG_APP_COGNITO_DOMAIN: "my-tenant.auth.eu-west-1.amazoncognito.com"
|
||
NG_APP_COGNITO_REDIRECT_SIGNIN: "https://app.example.com/callback"
|
||
NG_APP_COGNITO_REDIRECT_SIGNOUT: "https://app.example.com"
|
||
NG_APP_COGNITO_REGION: "eu-west-1"
|
||
NG_APP_COGNITO_SCOPES: "openid,email,profile"
|
||
```
|
||
|
||
Adaptation optionnelle du `frontend-dockerfile.yml` (à ajouter avant `npm run build`) :
|
||
|
||
```dockerfile
|
||
# Arguments build-time pour générer .env.production
|
||
ARG NG_APP_REQUIRE_AUTH
|
||
ARG NG_APP_LOGIN_ROUTE
|
||
ARG NG_APP_COGNITO_USER_POOL_ID
|
||
ARG NG_APP_COGNITO_WEB_CLIENT_ID
|
||
ARG NG_APP_COGNITO_DOMAIN
|
||
ARG NG_APP_COGNITO_REDIRECT_SIGNIN
|
||
ARG NG_APP_COGNITO_REDIRECT_SIGNOUT
|
||
ARG NG_APP_COGNITO_REGION
|
||
ARG NG_APP_COGNITO_SCOPES
|
||
|
||
# Écrire le fichier .env.production à partir des args
|
||
RUN printf "NG_APP_REQUIRE_AUTH=%s\nNG_APP_LOGIN_ROUTE=%s\nNG_APP_COGNITO_USER_POOL_ID=%s\nNG_APP_COGNITO_WEB_CLIENT_ID=%s\nNG_APP_COGNITO_DOMAIN=%s\nNG_APP_COGNITO_REDIRECT_SIGNIN=%s\nNG_APP_COGNITO_REDIRECT_SIGNOUT=%s\nNG_APP_COGNITO_REGION=%s\nNG_APP_COGNITO_SCOPES=%s\n" \
|
||
"$NG_APP_REQUIRE_AUTH" \
|
||
"$NG_APP_LOGIN_ROUTE" \
|
||
"$NG_APP_COGNITO_USER_POOL_ID" \
|
||
"$NG_APP_COGNITO_WEB_CLIENT_ID" \
|
||
"$NG_APP_COGNITO_DOMAIN" \
|
||
"$NG_APP_COGNITO_REDIRECT_SIGNIN" \
|
||
"$NG_APP_COGNITO_REDIRECT_SIGNOUT" \
|
||
"$NG_APP_COGNITO_REGION" \
|
||
"$NG_APP_COGNITO_SCOPES" \
|
||
> .env.production
|
||
```
|
||
|
||
Ainsi, le build Angular lit automatiquement ces variables via `import.meta.env` et les injecte dans le bundle.
|
||
|
||
Remarques :
|
||
- Les `environment.*.ts` peuvent mapper `import.meta.env` pour exposer une API typed au reste de l’app.
|
||
- Pour des valeurs sensibles, préférez des mécanismes backend (ne jamais exposer de secrets côté SPA).
|
||
- Si vous avez besoin de « runtime config » (changer après build), utilisez une approche `config.json` servie par le serveur et chargée au démarrage de l’app.
|
||
|
||
### Guard Angular (générique)
|
||
|
||
Exemple de Guard compatible avec Amplify ou angular-oauth2-oidc: elle vérifie `requireAuth`. Si l’auth est requise mais absente/expirée, elle redirige vers `loginRoute`.
|
||
|
||
```typescript
|
||
import { Injectable } from '@angular/core';
|
||
import { CanActivate, Router, UrlTree } from '@angular/router';
|
||
import { environment } from '../environments/environment';
|
||
|
||
@Injectable({ providedIn: 'root' })
|
||
export class AuthGuard implements CanActivate {
|
||
constructor(private router: Router) {}
|
||
|
||
async canActivate(): Promise<boolean | UrlTree> {
|
||
if (!environment.requireAuth) {
|
||
return true;
|
||
}
|
||
|
||
// 1) Vérification via Amplify (si utilisé)
|
||
try {
|
||
const { Auth } = await import('aws-amplify');
|
||
const session = await Auth.currentSession();
|
||
const valid = !!session?.getIdToken()?.getJwtToken();
|
||
if (valid) return true;
|
||
} catch (_) {
|
||
// ignore si Amplify non configuré
|
||
}
|
||
|
||
// 2) Vérification via angular-oauth2-oidc (si utilisé)
|
||
try {
|
||
const { OAuthService } = await import('angular-oauth2-oidc');
|
||
const oauth = (window as any).ngInjector?.get?.(OAuthService);
|
||
// Note: exposez éventuellement l'injector globalement au bootstrap
|
||
if (oauth && (oauth.hasValidAccessToken() || oauth.hasValidIdToken())) {
|
||
return true;
|
||
}
|
||
} catch (_) {
|
||
// ignore si non installé
|
||
}
|
||
|
||
return this.router.parseUrl(environment.loginRoute);
|
||
}
|
||
}
|
||
```
|
||
|
||
Astuce: pour récupérer des services dans la Guard sans injection directe (quand on veut la rendre agnostique), on peut exposer l’`Injector` Angular globalement au bootstrap: `window.ngInjector = injector;` et l’utiliser comme ci‑dessus.
|
||
|
||
### Routage protégé
|
||
|
||
Protégez les routes nécessitant une session valide:
|
||
|
||
```typescript
|
||
{
|
||
path: 'app',
|
||
canActivate: [AuthGuard],
|
||
loadChildren: () => import('./features/app/app.module').then(m => m.AppModule)
|
||
}
|
||
```
|
||
|
||
### Page de login (route `loginRoute`)
|
||
|
||
La page associée à `environment.loginRoute` doit offrir un bouton « Se connecter ». Selon l’implémentation:
|
||
|
||
- Avec Amplify:
|
||
|
||
```typescript
|
||
import { Auth } from 'aws-amplify';
|
||
|
||
login(): Promise<void> {
|
||
return Auth.federatedSignIn();
|
||
}
|
||
```
|
||
|
||
- Avec angular-oauth2-oidc:
|
||
|
||
```typescript
|
||
constructor(private oauthService: OAuthService) {}
|
||
|
||
login(): void {
|
||
this.oauthService.initLoginFlow();
|
||
}
|
||
```
|
||
|
||
Au retour sur `/callback`, suivez la section correspondante (Amplify: `currentSession()`, OIDC: `loadDiscoveryDocumentAndLogin()` déjà appelé au bootstrap) puis redirigez vers l’espace protégé.
|
||
|