Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/manfredsteyer/angular-oauth2-oidc

Support for OAuth 2 and OpenId Connect (OIDC) in Angular.
https://github.com/manfredsteyer/angular-oauth2-oidc

Last synced: about 1 month ago
JSON representation

Support for OAuth 2 and OpenId Connect (OIDC) in Angular.

Lists

README 

        
# angular-oauth2-oidc



Support for OAuth 2 and OpenId Connect (OIDC) in Angular. Already prepared for the upcoming OAuth 2.1.



![OIDC Certified Logo](https://raw.githubusercontent.com/manfredsteyer/angular-oauth2-oidc/master/oidc.png)



## Credits



- [jsrsasign](https://kjur.github.io/jsrsasign/) for validating token signature and for hashing

- [Identity Server](https://github.com/identityserver) for testing with an .NET/.NET Core Backend

- [Keycloak (Redhat)](http://www.keycloak.org/) for testing with Java

- [Auth0](https://auth0.com/)



## Resources



- Sources and Sample: [https://github.com/manfredsteyer/angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc)

- Source Code Documentation: [https://manfredsteyer.github.io/angular-oauth2-oidc/docs](https://manfredsteyer.github.io/angular-oauth2-oidc/docs)

- Community-provided sample implementation: [https://github.com/jeroenheijmans/sample-angular-oauth2-oidc-with-auth-guards/](https://github.com/jeroenheijmans/sample-angular-oauth2-oidc-with-auth-guards/)



## Tested Environment



Successfully tested with **Angular 4.3 to Angular 16** and its Router, PathLocationStrategy as well as HashLocationStrategy and CommonJS-Bundling via webpack.



At server side we've used **IdentityServer** (.NET / .NET Core), Redhat's **Keycloak** (Java), and **Auth0** (Auth0 is officially supported since version 10 of this lib). For Auth0, please have a look into the respective documentation page here.



For using this library with **Azure Active Directory** (**Azure AD**), we recommend an additional look to this [blog post](https://dev.to/yuriburger/azure-active-directory-b2c-with-pkce-for-your-angular-app-1dcg) and the example linked at the end of this blog post.



Also, the Okta community created some guidelines on how to use this lib with Okta. See the links at the end of this page for more information.



**Angular 17**: Use 17.x versions of this library (**should also work with older Angular versions!**).



**Angular 16**: Use 16.x versions of this library (**should also work with older Angular versions!**).



**Angular 15**: Use 15.x versions of this library (**should also work with older Angular versions!**).



**Angular 14**: Use 14.x versions of this library (**should also work with older Angular versions!**).



**Angular 13**: Use 13.x versions of this library (**should also work with older Angular versions!**).



**Angular 12**: Use 12.x versions of this library (**should also work with older Angular versions!**).



**Angular 11**: Use 10.x versions of this library (**should also work with older Angular versions!**).



**Angular 10**: Use 10.x versions of this library (**should also work with older Angular versions!**).



**Angular 9**: Use 9.x versions of this library (**should also work with older Angular versions!**).



**Angular 8**: Use 8.x versions of this library.



**Angular 7**: Use 7.x versions of this library.



**Angular 6**: Use Version 4.x of this library. Version 4.x was tested with Angular 6. You can also try the newer version 5.x of this library which has a much smaller bundle size.



**Angular 5.x or 4.3**: If you need support for Angular < 6 (4.3 to 5.x) you can download the former version 3.1.4 (npm i angular-oauth2-oidc@^3 --save).



## Release Cycle



- We plan one major release for each Angular version

  - Will contain new features

  - Will contain bug fixes and PRs

- Critical bugfixes on demand



## Contributions



- Feel free to file pull requests

- The issues contain some ideas for PRs and enhancements (see labels)

- If you want to contribute to the docs, you can do so in the `docs-src` folder. Make sure you update `summary.json` as well. Then generate the docs with the following commands:



  ```sh

  npm install -g @compodoc/compodoc

  npm run docs

  ```



## Features



- Logging in via Code Flow + PKCE

  - Hence, you are safe for the upcoming OAuth 2.1

- Logging in via Implicit Flow (where a user is redirected to Identity Provider)

- "Logging in" via Password Flow (where a user enters their password into the client)

- Token Refresh for all supported flows

- Automatically refreshing a token when/some time before it expires

- Querying Userinfo Endpoint

- Querying Discovery Document to ease configuration

- Validating claims of the id_token regarding the specs

- Hook for further custom validations

- Single-Sign-Out by redirecting to the auth-server's logout-endpoint

- Tested with all modern browsers and IE

- Token Revocation according to [RFC 7009](https://tools.ietf.org/html/rfc7009#section-2.2)



## Sample-Auth-Server



You can use the OIDC-Sample-Server used in our examples. It assumes, that your Web-App runs on http://localhost:4200



Username/Password:



- max/geheim

- bob/bob

- alice/alice



_clientIds:_



- spa (Code Flow + PKCE)

- implicit (implicit flow)



_redirectUris:_



- localhost:[4200-4202]

- localhost:[4200-4202]/index.html

- localhost:[4200-4202]/silent-refresh.html



## Installing



```sh

npm i angular-oauth2-oidc --save

```



## Option 1: Standalone APIs



If you use Standalone Components introduced with Angular 14, you can use our standalone API (call to ``provideOAuthClient``) in your ``main.ts`` to setup the ``OAuthClient``:



```TypeScript

// main.ts -- Angular 15+ version

import { bootstrapApplication } from '@angular/platform-browser';



import { provideHttpClient } from '@angular/common/http';



import { AppComponent } from './app/app.component';

import { provideOAuthClient } from 'angular-oauth2-oidc';



bootstrapApplication(AppComponent, {

  providers: [

    provideHttpClient(),

    provideOAuthClient()

  ]

});

```



As Angular 14 does have Standalone Components but no Standalone API for its ``HttpClient``, you need to go with the traditional ``HttpClientModule`` in this version:



```TypeScript

// main.ts -- Angular 14 version

import { bootstrapApplication } from '@angular/platform-browser';



import { HttpClientModule } from '@angular/common/http';



import { AppComponent } from './app/app.component';

import { provideOAuthClient } from 'angular-oauth2-oidc';

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



bootstrapApplication(AppComponent, {

  providers: [

    importProvidersFrom(HttpClientModule),

    provideOAuthClient()

  ]

});

```



The ``provideOAuthClient`` function takes the same parameters as the forRoot function of the OAuthModule that is still in place for the sake of compatibility with existing code bases.



## Option 2: Using NgModules



```TypeScript

import { HttpClientModule } from '@angular/common/http';

import { OAuthModule } from 'angular-oauth2-oidc';

// etc.



@NgModule({

  imports: [

    // etc.

    HttpClientModule,

    OAuthModule.forRoot()

  ],

  declarations: [

    AppComponent,

    HomeComponent,

    // etc.

  ],

  bootstrap: [

    AppComponent

  ]

})

export class AppModule {

}

```



# Logging in



Since Version 8, this library supports code flow and [PKCE](https://tools.ietf.org/html/rfc7636) to align with the current draft of the [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13) document. This is also the foundation of the upcoming OAuth 2.1.



To configure your solution for code flow + PKCE you have to set the `responseType` to `code`:



```TypeScript

  import { AuthConfig } from 'angular-oauth2-oidc';



  export const authCodeFlowConfig: AuthConfig = {

    // Url of the Identity Provider

    issuer: 'https://idsvr4.azurewebsites.net',



    // URL of the SPA to redirect the user to after login

    redirectUri: window.location.origin + '/index.html',



    // The SPA's id. The SPA is registerd with this id at the auth-server

    // clientId: 'server.code',

    clientId: 'spa',



    // Just needed if your auth server demands a secret. In general, this

    // is a sign that the auth server is not configured with SPAs in mind

    // and it might not enforce further best practices vital for security

    // such applications.

    // dummyClientSecret: 'secret',



    responseType: 'code',



    // set the scope for the permissions the client should request

    // The first four are defined by OIDC.

    // Important: Request offline_access to get a refresh token

    // The api scope is a usecase specific one

    scope: 'openid profile email offline_access api',



    showDebugInformation: true,

  };

```



After this, you can initialize the code flow using:



```TypeScript

this.oauthService.initCodeFlow();

```



There is also a convenience method `initLoginFlow` which initializes either the code flow or the implicit flow depending on your configuration.



```TypeScript

this.oauthService.initLoginFlow();

```



Also -- as shown in the readme -- you have to execute the following code when bootstrapping to make the library to fetch the token:



```TypeScript

this.oauthService.configure(authCodeFlowConfig);

this.oauthService.loadDiscoveryDocumentAndTryLogin();

```



### Logging out



The logOut method clears the used token store (by default ``sessionStorage``) and forwards the user to the auth servers logout endpoint if one was configured (manually or via the discovery document).



```typescript

this.oauthService.logOut();

```



If you want to revoke the existing access token and the existing refresh token before logging out, use the following method:



```typescript

this.oauthService.revokeTokenAndLogout();

```



### Skipping the Login Form



If you don't want to display a login form that tells the user that they are redirected to the identity server, you can use the convenience function `this.oauthService.loadDiscoveryDocumentAndLogin();` instead of `this.oauthService.loadDiscoveryDocumentAndTryLogin();` when setting up the library.



This directly redirects the user to the identity server if there are no valid tokens. Ensure you have your `issuer` set to your discovery document endpoint!



### Calling a Web API with an Access Token



You can automate this task by switching `sendAccessToken` on and by setting `allowedUrls` to an array with prefixes for the respective URLs. Use lower case for the prefixes.



```TypeScript

OAuthModule.forRoot({

    resourceServer: {

        allowedUrls: ['http://www.angular.at/api'],

        sendAccessToken: true

    }

})

```



If you need more versatility, you can look in the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/additional-documentation/working-with-httpinterceptors.html) how to setup a custom interceptor.



## Token Refresh



See docs: https://manfredsteyer.github.io/angular-oauth2-oidc/docs/additional-documentation/refreshing-a-token.html



## Routing



If you use the `PathLocationStrategy` (which is on by default) and have a general catch-all-route (`path: '**'`) you should be fine. Otherwise look up the section `Routing with the HashStrategy` in the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/).



## Implicit Flow



Nowadays, using code flow + PKCE -- as shown above -- is the recommended OAuth 2/OIDC flow for SPAs. To use the older implicit flow, lookup this docs: https://manfredsteyer.github.io/angular-oauth2-oidc/docs/additional-documentation/using-implicit-flow.html



## More Documentation (!)



See the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/) for more information about this library.



## Breaking Change in Version 9



With regards to tree shaking, beginning with version 9, the `JwksValidationHandler` has been moved to a library of its own. If you need it for implementing **implicit flow**, please install it using npm:



```

npm i angular-oauth2-oidc-jwks --save

```



After that, you can import it into your application by using this:



```typescript

import { JwksValidationHandler } from 'angular-oauth2-oidc-jwks';

```



instead of that:



```typescript

import { JwksValidationHandler } from 'angular-oauth2-oidc';

```



Please note, that this dependency is not needed for the **code flow**, which is nowadays the **recommended** flow for single page applications. This also results in smaller bundle sizes.



### Breaking change in 9.1.0



The use of `encodeURIComponent` on the argument passed to `initImplicitFlow` and its Code Flow counterparts was mandatory before this version.



Since that was considered a _bug_, the need to do so was removed.

Now the reverse is true **if you're upgrading from before 9.0.0**: you need to remove any call to encode URI components in your own application, as the library will now do it for you.



## Tutorials



- [Tutorial with Demo Servers available online](https://www.softwarearchitekt.at/post/2016/07/03/authentication-in-angular-2-with-oauth2-oidc-and-guards-for-the-newest-new-router-english-version.aspx)

- [Angular Authentication with OpenID Connect and Okta in 20 Minutes](https://developer.okta.com/blog/2017/04/17/angular-authentication-with-oidc)

- [Add Authentication to Your Angular PWA](https://developer.okta.com/blog/2017/06/13/add-authentication-angular-pwa)

- [Build an Ionic App with User Authentication](https://developer.okta.com/blog/2017/08/22/build-an-ionic-app-with-user-authentication)

- [On-Site Workshops](https://www.softwarearchitekt.at)

- [Angular 6 with Auth0 using this library](https://github.com/jeroenheijmans/sample-auth0-angular-oauth2-oidc)



## Thanks to all Contributors



[alexandis](https://github.com/alexandis)[anbiniyar](https://github.com/anbiniyar)[anoordende](https://github.com/anoordende)[ArsProgramma](https://github.com/ArsProgramma)[nihanth007](https://github.com/nihanth007)



[bobvandevijver](https://github.com/bobvandevijver)[BobCui20](https://github.com/BobCui20)[Bottswana](https://github.com/Bottswana)[ErazerBrecht](https://github.com/ErazerBrecht)[Chris3773](https://github.com/Chris3773)



[ChristianMurphy](https://github.com/ChristianMurphy)[d-moos](https://github.com/d-moos)[enterprisebug](https://github.com/enterprisebug)[craniodev](https://github.com/craniodev)[FabianGosebrink](https://github.com/FabianGosebrink)



[FabienDehopre](https://github.com/FabienDehopre)[FRosner](https://github.com/FRosner)[MisterJames](https://github.com/MisterJames)[JessePreiner](https://github.com/JessePreiner)[jesusbotella](https://github.com/jesusbotella)



[Jojofoulk](https://github.com/Jojofoulk)[kristofdegrave](https://github.com/kristofdegrave)[saxicek](https://github.com/saxicek)[lukasmatta](https://github.com/lukasmatta)[Maximaximum](https://github.com/Maximaximum)



[mpbalmeida](https://github.com/mpbalmeida)[mhyfritz](https://github.com/mhyfritz)[mdaehnert](https://github.com/mdaehnert)[mcserra](https://github.com/mcserra)[nhumblot](https://github.com/nhumblot)



[l1b3r](https://github.com/l1b3r)[oleersoy](https://github.com/oleersoy)[OskarsPakers](https://github.com/OskarsPakers)[hellerbarde](https://github.com/hellerbarde)[paweldyminski](https://github.com/paweldyminski)



[bechhansen](https://github.com/bechhansen)[peterneave](https://github.com/peterneave)[pmccloghrylaing](https://github.com/pmccloghrylaing)[akehir](https://github.com/akehir)[RubenVermeulen](https://github.com/RubenVermeulen)



[ryanmwright](https://github.com/ryanmwright)[scttcper](https://github.com/scttcper)[abshoff](https://github.com/abshoff)[SpazzMarticus](https://github.com/SpazzMarticus)[srenatus](https://github.com/srenatus)



[sven-codeculture](https://github.com/sven-codeculture)[Rocket18](https://github.com/Rocket18)[Ceteareth](https://github.com/Ceteareth)[vadjs](https://github.com/vadjs)[Varada-Schneider](https://github.com/Varada-Schneider)



[Gimly](https://github.com/Gimly)[akkaradej](https://github.com/akkaradej)[coyoteecd](https://github.com/coyoteecd)[darbio](https://github.com/darbio)[filipvh](https://github.com/filipvh)



[kyubisation](https://github.com/kyubisation)[luciimon](https://github.com/luciimon)[mike-rivera](https://github.com/mike-rivera)[drobert-bfm](https://github.com/drobert-bfm)[roblabat](https://github.com/roblabat)



[wdunn001](https://github.com/wdunn001)[adrianbenjuya](https://github.com/adrianbenjuya)[Andreas-Hjortland](https://github.com/Andreas-Hjortland)[adematte](https://github.com/adematte)[cgatian](https://github.com/cgatian)



[dirkbolte](https://github.com/dirkbolte)[enricodeleo](https://github.com/enricodeleo)[Gregordy](https://github.com/Gregordy)[jeroenhinfi](https://github.com/jeroenhinfi)[linjie997](https://github.com/linjie997)



[jfyne](https://github.com/jfyne)[kevincathcart-cas](https://github.com/kevincathcart-cas)[martin1cerny](https://github.com/martin1cerny)[marvinosswald](https://github.com/marvinosswald)[nick1699](https://github.com/nick1699)



[paulyoder](https://github.com/paulyoder)[reda-alaoui](https://github.com/reda-alaoui)[remiburtin](https://github.com/remiburtin)[gingters](https://github.com/gingters)[kranich](https://github.com/kranich)



[StefanoChiodino](https://github.com/StefanoChiodino)[tpeter1985](https://github.com/tpeter1985)[dennisameling](https://github.com/dennisameling)[dependabot[bot]](https://github.com/apps/dependabot)[jdgeier](https://github.com/jdgeier)



[mraible](https://github.com/mraible)[ajpierson](https://github.com/ajpierson)[artnim](https://github.com/artnim)[fmalcher](https://github.com/fmalcher)[Flofie](https://github.com/Flofie)



[mabdelaal86](https://github.com/mabdelaal86)[nhance](https://github.com/nhance)[Razzeee](https://github.com/Razzeee)[maxisam](https://github.com/maxisam)[ismcagdas](https://github.com/ismcagdas)



[Toxicable](https://github.com/Toxicable)[ManuelRauber](https://github.com/ManuelRauber)[vdveer](https://github.com/vdveer)[jeroenheijmans](https://github.com/jeroenheijmans)[manfredsteyer](https://github.com/manfredsteyer)