Angular Lib for OpenID Connect Code Flow with PKCE and Implicit Flow
OpenID Code Flow with PKCE, OpenID Connect Implicit Flow
OpenID Certification
This library is certified by OpenID Foundation. (RP Implicit and Config RP)
Features
Documentation : Quickstart | API Documentation | Changelog
Using the package
Navigate to the level of your package.json and type
npm install angular-auth-oidc-client
or with yarn
yarn add angular-auth-oidc-client
or you can add the npm package to your package.json
"angular-auth-oidc-client": "^10.0.14"
and type
npm install
Configuration
Approach 1: APP_INITIALIZER
Import the module and services in your module.
The OidcSecurityService
has a dependency on the HttpClientModule
which needs to be imported. The angular-auth-oidc-client module supports all versions of Angular 4.3 onwards.
Loading the configuration from the server
import { HttpClientModule } from '@angular/common/http';
import { APP_INITIALIZER, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
import { AuthModule, ConfigResult, OidcConfigService, OidcSecurityService, OpenIdConfiguration } from 'angular-auth-oidc-client';
import { AppComponent } from './app.component';
const oidc_configuration = 'assets/auth.clientConfiguration.json';
export function loadConfig(oidcConfigService: OidcConfigService) {
return () => oidcConfigService.load(oidc_configuration);
}
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
HttpClientModule,
RouterModule.forRoot([
{ path: '', component: AppComponent },
{ path: 'home', component: AppComponent },
{ path: 'forbidden', component: AppComponent },
{ path: 'unauthorized', component: AppComponent },
]),
AuthModule.forRoot(),
],
providers: [
OidcConfigService,
{
provide: APP_INITIALIZER,
useFactory: loadConfig,
deps: [OidcConfigService],
multi: true,
},
],
bootstrap: [AppComponent],
})
export class AppModule {
constructor(private oidcSecurityService: OidcSecurityService, private oidcConfigService: OidcConfigService) {
this.oidcConfigService.onConfigurationLoaded.subscribe((configResult: ConfigResult) => {
const config: OpenIdConfiguration = {
stsServer: configResult.customConfig.stsServer,
redirect_url: 'https://localhost:4200',
client_id: 'angularClient',
scope: 'openid profile email',
response_type: 'code',
silent_renew: true,
silent_renew_url: 'https://localhost:4200/silent-renew.html',
log_console_debug_active: true,
};
this.oidcSecurityService.setupModule(config, configResult.authWellknownEndpoints);
});
}
}
assets/auth.clientConfiguration.json
See Auth documentation
for the detail of each field.
{
"stsServer": "https://localhost:44318",
"redirect_url": "https://localhost:44311",
"client_id": "angularclient",
"response_type": "code",
"scope": "dataEventRecords securedFiles openid profile",
"post_logout_redirect_uri": "https://localhost:44311",
"start_checksession": true,
"silent_renew": true,
"silent_renew_url": "https://localhost:44311/silent-renew.html",
"post_login_route": "/home",
"forbidden_route": "/forbidden",
"unauthorized_route": "/unauthorized",
"log_console_warning_active": true,
"log_console_debug_active": true,
"max_id_token_iat_offset_allowed_in_seconds": 10
}
At present only the 'code' with PKCE, 'id_token token' or the 'id_token' flows are supported:
"response_type": ["code" | "id_token token" | "id_token" ]
Note the configuration json must have a property stsServer for this to work.
Approach 2. Configuration without APP_INITIALIZER
export class AppModule {
constructor(public oidcSecurityService: OidcSecurityService) {
const config: OpenIdConfiguration = {
stsServer: 'https://localhost:44363',
redirect_url: 'https://localhost:44363',
client_id: 'singleapp',
response_type: 'code',
scope: 'dataEventRecords openid',
post_logout_redirect_uri: 'https://localhost:44363/Unauthorized',
start_checksession: false,
silent_renew: true,
silent_renew_url: 'https://localhost:44363/silent-renew.html',
post_login_route: '/dataeventrecords',
forbidden_route: '/Forbidden',
unauthorized_route: '/Unauthorized',
log_console_warning_active: true,
log_console_debug_active: true,
max_id_token_iat_offset_allowed_in_seconds: 10,
};
const authWellKnownEndpoints: AuthWellKnownEndpoints = {
issuer: 'https://localhost:44363/.well-known/openid-configuration/jwks',
authorization_endpoint: 'https://localhost:44363/connect/authorize',
token_endpoint: 'https://localhost:44363/connect/token',
userinfo_endpoint: 'https://localhost:44363/connect/userinfo',
end_session_endpoint: 'https://localhost:44363/connect/endsession',
check_session_iframe: 'https://localhost:44363/connect/checksession',
revocation_endpoint: 'https://localhost:44363/connect/revocation',
introspection_endpoint: 'https://localhost:44363/connect/introspect',
};
this.oidcSecurityService.setupModule(config, authWellKnownEndpoints);
}
}
Custom STS server well known configuration
Sometimes it is required to load custom .well-known/openid-configuration. The load_using_custom_stsServer can be used for this.
export function loadConfig(oidcConfigService: OidcConfigService) {
return () =>
oidcConfigService.load_using_custom_stsServer(
'https://login.microsoftonline.com/fabrikamb2c.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=b2c_1_susi'
);
}
Usage
Code Flow with PKCE
It is recomended flow in SPA applications, see SECURELY USING THE OIDC AUTHORIZATION CODE FLOW AND A PUBLIC CLIENT WITH SINGLE PAGE APPLICATIONS.
Not all security service providers and servers support it yet.
Create the login, logout component and use the oidcSecurityService
import { Component, OnDestroy, OnInit } from '@angular/core';
import { OidcSecurityService } from 'angular-auth-oidc-client';
import { filter, take } from 'rxjs/operators';
@Component({
selector: 'app-root',
templateUrl: 'app.component.html',
})
export class AppComponent implements OnInit, OnDestroy {
isAuthenticated: boolean;
userData: any;
constructor(public oidcSecurityService: OidcSecurityService) {
if (this.oidcSecurityService.moduleSetup) {
this.doCallbackLogicIfRequired();
} else {
this.oidcSecurityService.onModuleSetup.subscribe(() => {
this.doCallbackLogicIfRequired();
});
}
}
ngOnInit() {
this.oidcSecurityService.getIsAuthorized().subscribe(auth => {
this.isAuthenticated = auth;
});
this.oidcSecurityService.getUserData().subscribe(userData => {
this.userData = userData;
});
}
ngOnDestroy(): void {}
login() {
this.oidcSecurityService.authorize();
}
logout() {
this.oidcSecurityService.logoff();
}
private doCallbackLogicIfRequired() {
this.oidcSecurityService.authorizedCallbackWithCode(window.location.toString());
}
}
Implicit Flow (Not recommended)
This flow is no longer recommended, but some servers support this flow only, and not the Code flow with PKCE.
Create the login, logout component and use the oidcSecurityService
private doCallbackLogicIfRequired() {
if (window.location.hash) {
this.oidcSecurityService.authorizedImplicitFlowCallback();
}
}
And a simple template for the component.
<button *ngIf="!isAuthenticated" (click)="login()">Login</button>
<button *ngIf="isAuthenticated" (click)="logout()">Logout</button>
<hr />
Is Authenticated: {{ isAuthenticated }}
<br />
<br />
{{ userData | json }}
Silent Renew
When silent renew is enabled, a DOM event will be automatically installed in the application's host window.
The event oidc-silent-renew-message
accepts a CustomEvent
instance with the token returned from the OAuth server
in its detail
field.
The event handler will send this token to the authorization callback and complete the validation.
Point the silent_renew_url
property to an HTML file which contains the following script element to enable authorization.
Code Flow with PKCE
<script>
window.onload = function () {
var parent = window.parent;
var event = new CustomEvent('oidc-silent-renew-message', { detail: window.location });
parent.dispatchEvent(event);
};
</script>
Silent Renew Angular-CLI
Add the silent-renew.html file to the angular.json assets configuration
"assets": [
"projects/sample-code-flow/src/silent-renew.html",
"projects/sample-code-flow/src/favicon.ico",
"projects/sample-code-flow/src/assets"
],
Using the access_token
In the http services, add the token to the header using the oidcSecurityService
private setHeaders() {
this.headers = new HttpHeaders();
this.headers = this.headers.set('Content-Type', 'application/json');
this.headers = this.headers.set('Accept', 'application/json');
const token = this._securityService.getToken();
if (token !== '') {
const tokenValue = 'Bearer ' + token;
this.headers = this.headers.set('Authorization', tokenValue);
}
}
Using Guards
import { Injectable } from '@angular/core';
import { Router, Route, CanActivate, CanLoad, ActivatedRouteSnapshot, RouterStateSnapshot } from '@angular/router';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import { OidcSecurityService } from 'angular-auth-oidc-client';
@Injectable()
export class AuthorizationGuard implements CanActivate, CanLoad {
constructor(private router: Router, private oidcSecurityService: OidcSecurityService) {}
canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<boolean> {
return this.checkUser();
}
canLoad(state: Route): Observable<boolean> {
return this.checkUser();
}
private checkUser(): Observable<boolean> {
return this.oidcSecurityService.getIsAuthorized().pipe(
map((isAuthorized: boolean) => {
if (!isAuthorized) {
this.router.navigate(['/unauthorized']);
return false;
}
return true;
})
);
}
}
Note about Guards
The guard should only be applied to protected URLs. The guard should not be active on the default route, where the authorization request is processed.
Adding custom parameters to the authorization request
Custom parameters can be added to the auth request by using the setCustomRequestParameters method. Here you could add ui_locale, acr or whatever you request for your token server.
this.oidcSecurityService.setCustomRequestParameters({ 'ui_locales': culture});
Custom Storage
If you need, you can create a custom storage (for example to use cookies).
Implement OidcSecurityStorage
class-interface and the read
and write
methods:
@Injectable()
export class CustomStorage implements OidcSecurityStorage {
public read(key: string): any {
...
return ...
}
public write(key: string, value: any): void {
...
}
}
Then provide the class in the module:
@NgModule({
imports: [
...
AuthModule.forRoot({ storage: CustomStorage })
],
...
})
See also oidc.security.storage.ts
for an example.
Http Interceptor
The HttpClient allows you to write interceptors. A common usecase would be to intercept any outgoing HTTP request and add an authorization header. Keep in mind that injecting OidcSecurityService into the interceptor via the constructor results in a cyclic dependency. To avoid this use the injector instead.
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
private oidcSecurityService: OidcSecurityService;
constructor(private injector: Injector) {}
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
let requestToForward = req;
if (this.oidcSecurityService === undefined) {
this.oidcSecurityService = this.injector.get(OidcSecurityService);
}
if (this.oidcSecurityService !== undefined) {
let token = this.oidcSecurityService.getToken();
if (token !== '') {
let tokenValue = 'Bearer ' + token;
requestToForward = req.clone({ setHeaders: { Authorization: tokenValue } });
}
} else {
console.debug('OidcSecurityService undefined: NO auth header!');
}
return next.handle(requestToForward);
}
}
You can call the Provider's authorization endpoint in a popup or iframe instead of navigating to it in the app's parent window.
This allows you to have the Provider's consent prompt display in a popup window to avoid unloading and reloading the app,
or to authorize the user silently by loading the endpoint in a hidden iframe if that supported by the Provider.
To get the fully-formed authorization URL, pass a handler function to OidcSecurityService.authorize
(this will also prevent the default behavior of loading the authorization endpoint in the current window):
login() {
this.oidcSecurityService.authorize((authUrl) => {
window.open(authUrl, '_blank', 'toolbar=0,location=0,menubar=0');
});
}
Silent Renew Implicit Flow
<script>
window.onload = function () {
var parent = window.parent;
var event = new CustomEvent('oidc-silent-renew-message', {detail: window.location.hash.substr(1) });
parent.dispatchEvent(event);
};
</script>
When silent renew is enabled, getIsAuthorized()
will attempt to perform a renew before returning the authorization state.
This allows the application to authorize a user, that is already authenticated, without redirects.
Silent renew requires CSP configuration, see next section.
X-Frame-Options / CSP ancestor / different domains
If deploying the client application and the STS server application with 2 different domains,
the X-Frame-Options HTTPS header needs to allow all iframes. Then use the CSP HTTPS header to only allow the required domains.
The silent renew requires this.
Add this header to responses from the server that serves your SPA:
Content-Security-Policy: script-src 'self' 'unsafe-inline';style-src 'self' 'unsafe-inline';img-src 'self' data:;font-src 'self';frame-ancestors 'self' https://localhost:44318;block-all-mixed-content
where https://localhost:44318
is the address of your STS server.
e.g. if you use NginX to serve your Angular application, it would be
http {
server {
...
add_header Content-Security-Policy "script-src 'self' 'unsafe-inline';style-src 'self' 'unsafe-inline';img-src 'self' data:;font-src 'self';frame-ancestors 'self' https://localhost:44318;block-all-mixed-content";
Examples using:
https://github.com/damienbod/AspNetCoreAngularSignalRSecurity
https://github.com/damienbod/dotnet-template-angular
https://github.com/damienbod/angular-auth-oidc-sample-google-openid
https://github.com/HWouters/ad-b2c-oidc-angular
Using src code directly:
https://github.com/damienbod/AspNet5IdentityServerAngularImplicitFlow
License
MIT