Merge branch 'master' into setupRefreshTimer

Author: l1b3r

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Stackblitz example**
+Provide a minimal [stackblitz](https://stackblitz.com/) based example that shows the issue. For this, you can use the example application of this repo and the identity providers used here.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/support-request--general-question.md

@@ -0,0 +1,33 @@
+---
+name: Support request/ general question
+about: Requesting help from the community
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Stackblitz example**
+Provide a minimal [stackblitz](https://stackblitz.com/) based example that shows the issue. For this, you can use the example application of this repo and the identity providers used here.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.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
@@ -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() {
@@ -228,11 +235,19 @@ 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.
 
+## Code Flow + PKCE
+
+See docs: https://manfredsteyer.github.io/angular-oauth2-oidc/docs/additional-documentation/code-flow-+-pcke.html
+
+## 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/).
 
-## More Documentation
+## More Documentation (!)
 
 See the [documentation](https://manfredsteyer.github.io/angular-oauth2-oidc/docs/) for more information about this library.
 

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.