cidp-angular-sdk

OIDC Angular SDK

A library for application built on angular 2 and above. Is used to integrate with identity server for authentication and authorization.

Features:

• anuglar library
• unit tests for the library
• a demo application that consumes the library in JIT mode and runs in watch mode
• an integration app that consumes the library in JIT and AOT mode and runs e2e tests

Common tasks are present as npm scripts:

• npm start to run a live-reload server with the demo app
• npm run build to build the library
• npm run lint to lint
• npm run clean to clean
• npm run integration:jit or npm run integration:aot to run the integration e2e tests
• npm install ./relative/path/to/lib after npm run build to test locally in another app

If you need to debug the integration app, please check ./integration/README.md. Before running integration test, need to make sure CIDP server is running and contains client oidc settings (clientId, scope, etc).

What's in the OIDC Angular SDK?

The OIDC Angular SDK contains a similar structure to the Quickstart lib.

Consequently, there are many different files in the project. Focus on the following TypeScript (.ts) files in the /src folder.

src/
├── demo/
|  └── app/
|     ├── app.component.ts
|     └── app.module.ts
└── lib/
   ├── index.ts
   └── src/
      ├── component/
      |  └── lib.component.ts
      |  └── lib.service.ts
      |  └── module.ts

Files outside src/ concern building, deploying, and testing app. They include configuration files and external dependencies.

Files inside src/lib/ "belong" to library, while src/demo/ contains a demo application that loads your library.

Libraries do not run by themselves, so it's very useful to have this "demo" app while developing to see how your library would look like to consumers.

When you run npm start, the demo application is served.

The build step

You can build the library by running npm run build. This will generate a dist/ directory with all the entry points described above.

All the logic for creating the build can be found in ./build.js. It consists of roughly 5 steps:

• Compile with the AOT Compiler (AOT compiler or ngc) for ES5 and ES2015.
• Inline html and css inside the generated JavaScript files.
• Copy typings, metatada, html and css.
• Create each bundle using Rollup.
• Copy LICENSE, package.json and README.md files

Testing

The OIDC Angular SDK includes a directory called integration containing a standalone app that consumes your built library in both AOT and JIT modes, with end-to-end tests to verify it works.

To run the integration tests, do npm run integration:jit and npm run integration:aot which does the following:

• Build your library.
• Enter the integration app's directory.
• Install dependencies.
• Build the app in AOT mode.
• Test the app in AOT mode.
• Test the app in JIT mode.

Running integration tests gives you greater confidence that your library is properly built.

Appendix: Supporting AOT

AOT plays an important role in optimizing Angular applications. It's therefore important that third party libraries be published in a format compatible with AOT compilation. Otherwise it will not be possible to include the library in an AOT compiled application.

Appendix: Supporting JIT

AOT compiled code is the preferred format for production builds, but due to the long compilation time it may not be practical to use AOT during development.

Using in the angular application

Install package in your app: npm install cidp-angular-sdk --save

Import the module and services in your module. Set the ClientOidcSettings properties to match the server configuration. Also configure logging. Available log levels:

• NONE
• ERROR
• WARN
• INFO
• DEBUG

import { NgModule } from '@angular/core';

import { OidcSettings, OidcModule, OidcService, Log } from 'cidp-angular-sdk';

@NgModule({
    imports: [
        ...
        OidcModule
    ],
    ...
})

export class AppModule {
  constructor(private oidcService: OidcService) {
    Log.level = Log.DEBUG;
    let settings : OidcSettings = {
    authority: 'http://localhost:5200',// authority url
    client_id: 'angular_client',// client id
    response_type: 'id_token token',// response type
    scope: 'openid profile',
    post_login_redirect_uri: 'identity',//post login redirect  route name, base root is used by default
    post_logout_redirect_uri: 'home',// post logout redirect route name, base root is used by default
    error_redirect_uri: 'unauthorized',//  route name in case of any CIDP error, base root is used by default. Error message is attached to errMsg query string. The route should be registerd as unauthorized/:errMsg
    
    ui_locales: 'fr-FR',// optional param to localize CIDP login page 
    automaticSilentRenew: true,//Flag to indicate if there should be an automatic attempt to renew the access token prior to its expiration.
    accessTokenExpiringNotificationTime: number = 60; //(default 60) Time in seconds before access token expires, to trigger silent renew 
    post_login_callback:Observable<any> // a callback required to run after user is logged in and before redirecting to client app
    post_logout_callback:Observable<any> // a callback required to run after user is logged out and before redirecting to client app
    extraQueryParams: { firstname: 'first', lastname: 'last' },// extra query params to pass to CIDP. In the query string it will be represented as ?firstname=first&lastname=last
  //The custom param will not be available directly in query string on login page, there is a redirectUrl that contains custom params
  //Following javascript code can be used to read custom_params on CIDP side:
  //let paramsString = decodeURIComponent(window.location.search);
  //let searchParams = new URLSearchParams(paramsString);
  //searchParams.get('firstname');
  //searchParams.get('lastname')
   };
    oidcService.init(settings);
  }

Register oidc routes handled by OidcComponent

import { OidcRoutes } from 'cidp-angular-sdk';
const appRoutes: Routes = [
  ...OidcRoutes
];

export const routing = RouterModule.forRoot(appRoutes);

Create the login, logout component and use the oidcService

  import { Subscription } from 'rxjs/Subscription';
  import { OidcService, User, OidcSettings } from 'cidp-angular-sdk';
  subscription: Subscription;
  user: User;
  constructor(public oidcService: OidcService) {    }

  ngOnInit() {
    // user load event is raised by SDK when user succesful logs in
	this.subscription = this.oidcService.onUserDataLoaded.subscribe((user: User) => {
	  this.user = user;
	});
  }

  signIn() {
    this.oidcService.signin();
    // optionally we can override initial ui_locales, scopes and response_type oidcSettings
    // let settings = {  
       //ui_locales : 'en-GB';
       //scopes:'openid profile newScope',
       //response_type: 'id_token token',
    //}
    // this.oidcService.signin(settings);
  }

  signOut() {
    this.oidcService.signout();
  }

//redirect user to CIDP change password page
//returnRouteName - optional parameter is route name to return after changing the password,if not defined, the oidcSettings.post_login_redirect_uri will be used as default
  changePassword()
  {
      this.oidcService.changePassword(returnRouteName);
  }

//redirects the user to login history page when he can view Login-Logout information
 loginHistory() {
    this.oidcService.loginHistory(returnRouteName);
  }

While registering the routes use AuthGuard to authorize the resource access. AuthGuard allow access only to authenticated user and redirects to CIDP login page when user is not authenticated. After user signs in on CIDP it will redirect back to the route the client tried to access (not to the configured post_login_redirect_uri) If you need to always redirect to post_login_redirect_uri, or to get the current application culture, implement you own similar AuthGuard service.

import { AuthGuard } from 'cidp-angular-sdk';
const appRoutes: Routes = [
    {
        path: 'profile',
        component: ProfileComponent,
        canActivate: [AuthGuard]
    },

The user services can be used to retrieve information for current user.

You can provide additional parameters before calling oidcService.signin() in by adding an object in OidcSettings.state, and they will be made available to you when you subscribe to oidcService.onUserDataLoaded():

  let settings = {  
    state : {foo: 'bar'}
  };
  this.oidcService.signin(settings);
  ....
  ngOnInit() {
    // user load event is raised by SDK when user succesful logs in
    this.subscription = this.oidcService.onUserDataLoaded.subscribe((user: User) => {
      this.user = user;
      let state = user.state;
      let value = state.foo;
    });
  }

import { UserService,Claim } from 'cidp-angular-sdk';
 this.userSevice.User:User // returns current user in case no promise usage is required
 this.userService.getUser(): Promise<User> // get current user info as promise
 this.userService.getIdentityClaims(): Promise<any> ; // get claims dictionary from id token
 this.userService.getAccessClaims(): Promise<any> ; // get claims dictionary from access token
 this.userService.hasIdentityClaim(claim: Claim): Promise<boolean> // if claims exist in id token
 this.userService.hasAccessClaim(claim: Claim): Promise<boolean> // if claims exist in access token

 //example of usage
 let user:User;
 this.userService.getUser().then((user:User) => this.user = user);

In the http services, add the token to the header using the oidcService.user. OidcService.user provides details about identity and access tokens.

import { UserService } from 'cidp-angular-sdk';
private setHeaders() {
        this.headers = new Headers();
        this.headers.append('Content-Type', 'application/json');
        this.headers.append('Accept', 'application/json');

        this.userService.getUser((user:User) => {);
          if (user && user.access_token !== '') {
              let tokenValue = 'Bearer ' + user.access_token;
              this.headers.append('Authorization', tokenValue);
          }
        }
    }