Skip to content
Support for OAuth 2 and OpenId Connect (OIDC) in Angular.
TypeScript HTML JavaScript Other
Branch: master
Clone or download

Latest commit

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Jul 18, 2019
.vscode docs Jul 18, 2019
docs-src Update silent-refresh.md Mar 24, 2020
docs chore: make version 9.2 ready Mar 28, 2020
e2e angular 6 + angular cli 6 workspace May 14, 2018
projects chore: make version 9.2 ready Mar 28, 2020
scripts chore: added contributers list Mar 23, 2020
.editorconfig angular 6 + angular cli 6 workspace May 14, 2018
.gitignore reverted to previous .gitignore May 30, 2018
.prettierignore chore: Add prettier and execute it Mar 23, 2020
.prettierrc chore: Add prettier and execute it Mar 23, 2020
CHANGELOG.md chore(release): 9.2.0 Mar 28, 2020
LICENSE Add LICENSE back to repository Oct 24, 2018
README.md chore: make version 9.2 ready Mar 28, 2020
angular.json chore: Add prettier and execute it Mar 23, 2020
commitlint.config.js chore: Add conventional-changelog Mar 23, 2020
contributors.bat chore: added contributers list Mar 23, 2020
contributors.md chore: make version 9.2 ready Mar 28, 2020
oidc.png angular 6 + angular cli 6 workspace May 14, 2018
package-lock.json chore(release): 9.2.0 Mar 28, 2020
package.json chore(release): 9.2.0 Mar 28, 2020
tsconfig.json chore: Add prettier and execute it Mar 23, 2020
tsconfig.npm.json chore: Add prettier and execute it Mar 23, 2020
tslint.json chore: Add prettier and execute it Mar 23, 2020

README.md

angular-oauth2-oidc

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

OIDC Certified Logo

Credits

Resources

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:

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

instead of that:

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.

Tested Environment

Successfully tested with Angular 9 and its Router, PathLocationStrategy as well as HashLocationStrategy and CommonJS-Bundling via webpack. At server side we've used IdentityServer (.NET / .NET Core) and Redhat's Keycloak (Java).

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:

    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

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

npm i angular-oauth2-oidc --save

Importing the NgModule

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 to align with the current draft of the OAuth 2.0 Security Best Current Practice 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:

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

  export const authCodeFlowConfig: AuthConfig = {
    // Url of the Identity Provider
    issuer: 'https://demo.identityserver.io',

    // 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,

    // Not recommented:
    // disablePKCI: true,
  };

After this, you can initialize the code flow using:

this.oauthService.initCodeFlow();

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

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:

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).

this.oauthService.logOut();

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

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.

OAuthModule.forRoot({
    resourceServer: {
        allowedUrls: ['http://www.angular.at/api'],
        sendAccessToken: true
    }
})

If you need more versatility, you can look in the documentation 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.

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 for more information about this library.

Tutorials

Thanks to all Contributors

dorianweidlerwdunn001roblabatdrobert-bfmmike-rivera

luciimonkillzonerfilipvhdarbioakkaradej

GimlyVarada-SchneidervadjssrenatusSpazzMarticus

scttcperryanmwrightRubenVermeulenMrJustrebornakehir

pmccloghrylaingpeterneavebechhansenhellerbardeOskarsPakers

oleersoyl1b3rnhumblotmdaehnertanbiniyar

anoordendeArsProgrammabobvandevijverErazerBrechtChris3773

ChristianMurphyenterprisebugdirkboltemhyfritzFabienDehopre

MisterJamesJessePreinerjesusbotellasaxiceklukasmatta

Maximaximummpbalmeidamraiblejeroenhinfidennisameling

tpeter1985StefanoChiodinogingtersremiburtinpaulyoder

marvinosswaldmartin1cernyManuelRauberjfynelinjie997

jdgeierGregordyenricodeleoadematteadrianbenjuya

ismcagdasmaxisamRazzeeenhancefmalcher

artnimajpiersonToxicablevdveerjeroenheijmans

manfredsteyer

You can’t perform that action at this time.