Merge branch 'master' into improve-default-oauth-interceptor

Author: manfredsteyer

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "chrome",
+            "request": "launch",
+            "name": "Launch Chrome against localhost",
+            "url": "http://localhost:4200",
+            "webRoot": "${workspaceFolder}"
+        }
+    ]
+}

.vscode/settings.json

@@ -25,9 +25,12 @@
         "typescriptreact",
         "yml"
     ],
-    "spellright.language": "de",
+    "spellright.language": [
+        "en"
+    ],
     "spellright.documentTypes": [
         "latex",
-        "plaintext"
+        "plaintext",
+        "markdown"
     ]
 }

README.md

@@ -37,11 +37,18 @@ Successfully tested with **Angular 7** and its Router, PathLocationStrategy as w
 ## Contributions
 - Feel free to file pull requests
 - The closed 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 OAuth2 and OpenId Connect (OIDC) Implicit Flow (where a user is redirected to Identity Provider)
+- Logging in via Implicit Flow (where a user is redirected to Identity Provider)
+- Logging in via Code Flow + PKCE
 - "Logging in" via Password Flow (where a user enters their password into the client)
-- Token Refresh for Password Flow by using a Refresh Token
+- 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
@@ -116,7 +123,7 @@ export const authConfig: AuthConfig = {
   // 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
+  // The SPA's id. The SPA is registered with this id at the auth-server
   clientId: 'spa-demo',
 
   // set the scope for the permissions the client should request
@@ -125,7 +132,7 @@ export const authConfig: AuthConfig = {
 }
 ```
 
-Configure the OAuthService with this config object when the application starts up:
+Configure the ``OAuthService`` with this config object when the application starts up:
 
 ```TypeScript
 import { OAuthService } from 'angular-oauth2-oidc';
@@ -140,10 +147,10 @@ import { Component } from '@angular/core';
 export class AppComponent {
 
     constructor(private oauthService: OAuthService) {
-      this.configureWithNewConfigApi();
+      this.configure();
     }
 
-    private configureWithNewConfigApi() {
+    private configure() {
       this.oauthService.configure(authConfig);
       this.oauthService.tokenValidationHandler = new JwksValidationHandler();
       this.oauthService.loadDiscoveryDocumentAndTryLogin();
@@ -168,7 +175,7 @@ export class HomeComponent {
     }
 
     public login() {
-        this.oauthService.initImplicitFlow();
+        this.oauthService.initLoginFlow();
     }
 
     public logoff() {
@@ -215,23 +222,7 @@ This directly redirects the user to the identity server if there are no valid to
 
 ### Calling a Web API with an Access Token
 
-Pass this Header to the used method of the ``Http``-Service within an Instance of the class ``Headers``:
-
-```TypeScript
-var headers = new Headers({
-    "Authorization": "Bearer " + this.oauthService.getAccessToken()
-});
-```
-
-If you are using the new ``HttpClient``, use the class ``HttpHeaders`` instead:
-
-```TypeScript
-var headers = new HttpHeaders({
-    "Authorization": "Bearer " + this.oauthService.getAccessToken()
-});
-```
-
-Since 3.1 you can also 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.
+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({
@@ -242,11 +233,13 @@ OAuthModule.forRoot({
 })
 ```
 
+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.
+
 ## 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/).
 
-## More Documentation
+## More Documentation (!)
 
 See the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/) for more information about this library.
 

angular.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "./node_modules/@angular-devkit/core/src/workspace/workspace-schema.json",
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
   "version": 1,
   "newProjectRoot": "projects",
   "projects": {
@@ -21,14 +21,6 @@
             }
           }
         },
-        "test": {
-          "builder": "@angular-devkit/build-angular:karma",
-          "options": {
-            "main": "projects/lib/src/test.ts",
-            "tsConfig": "projects/lib/tsconfig.spec.json",
-            "karmaConfig": "projects/lib/karma.conf.js"
-          }
-        },
         "lint": {
           "builder": "@angular-devkit/build-angular:tslint",
           "options": {
@@ -114,7 +106,8 @@
             "tsConfig": "projects/sample/tsconfig.spec.json",
             "karmaConfig": "projects/sample/karma.conf.js",
             "styles": [
-              "projects/sample/styles.css"
+              "projects/sample/src/styles.css",
+              "node_modules/bootstrap/dist/css/bootstrap.css"
             ],
             "scripts": [],
             "assets": [

docs-src/code-flow.bak.md

@@ -0,0 +1,66 @@
+# Code Flow
+
+Since Version 8, this library also 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. 
+
+
+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://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:
+
+```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.tokenValidationHandler = new JwksValidationHandler();
+this.oauthService.loadDiscoveryDocumentAndTryLogin();
+```
+
+
+

docs-src/code-flow.md

@@ -0,0 +1,64 @@
+# Code Flow
+
+Since Version 8, this library also 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. 
+
+
+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://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:
+
+  ```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.tokenValidationHandler = new JwksValidationHandler();
+this.oauthService.loadDiscoveryDocumentAndTryLogin();
+```
+
+
+

docs-src/configure-custom-oauthstorage.md

@@ -0,0 +1,42 @@
+# Configure custom OAuthStorage
+
+This library uses `sessionStorage` as the default storage provider. You can customize this by using `localStorage` or your own storage solution.
+
+## Using localStorage
+If  you want to use `localStorage` instead of `sessionStorage`, you can add a provider to your AppModule. This works as follows:
+
+```TypeScript
+import { HttpClientModule } from '@angular/common/http';
+import { OAuthModule } from 'angular-oauth2-oidc';
+// etc.
+
+// We need a factory, since localStorage is not available during AOT build time.
+export function storageFactory() : OAuthStorage {
+  return localStorage
+}
+ 
+@NgModule({
+  imports: [ 
+    // etc.
+    HttpClientModule,
+    OAuthModule.forRoot()
+  ],
+  declarations: [
+    AppComponent,
+    HomeComponent,
+    // etc.
+  ],
+  bootstrap: [
+    AppComponent 
+  ],
+  providers: [
+    { provide: OAuthStorage, useFactory: storageFactory }
+  ]
+})
+export class AppModule {
+}
+```
+
+## Custom storage solution
+
+If you want to use a custom storage solution, you can extend the `OAuthStorage` class. Documentation can be found [here](../classes/OAuthStorage.html#info). Then add it as a provider, just like in the `localStorage` example above.

docs-src/discovery-document-validation.md

@@ -0,0 +1,30 @@
+# Discovery Document Validation
+
+The configuration parameter `strictDiscoveryDocumentValidation` is set `true` by default. This ensures that all of the endpoints provided via the ID Provider discovery document share the same base URL as the `issuer` parameter.
+
+Several ID Providers (i.e. Google OpenID, WS02-IS, PingOne) provide different domains or path params for various endpoints in the discovery document. These providers may still adhere to the [OpenID Connect Provider Configuration specification](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse), but will fail to pass this library's discovery document validation.
+
+To use this library with an ID Provider that does not maintain a consistent base URL across the discovery document endpoints, set the `strictDiscoveryDocumentValidation` parameter to `false` in your configuration:
+
+```TypeScript
+import { AuthConfig } from 'angular-oauth2-oidc';
+
+export const authConfig: AuthConfig = {
+
+  // Url of the Identity Provider
+  issuer: 'https://steyer-identity-server.azurewebsites.net/identity',
+
+  // 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: 'spa-demo',
+
+  // set the scope for the permissions the client should request
+  // The first three are defined by OIDC. The 4th is a usecase-specific one
+  scope: 'openid profile email voucher',
+
+  // turn off validation that discovery document endpoints start with the issuer url defined above
+  strictDiscoveryDocumentValidation: false
+}
+```