Skip to content

Commit

Permalink
docs: update readme for standalone api
Browse files Browse the repository at this point in the history
  • Loading branch information
@manfredsteyer
manfredsteyer committed Nov 18, 2022
1 parent ebeca23 commit be84e3d
Show file tree
Hide file tree
Showing 18 changed files with 341 additions and 191 deletions.
32 changes: 30 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,18 @@ Support for OAuth 2 and OpenId Connect (OIDC) in Angular. Already prepared for t

## Tested Environment

Successfully tested with **Angular 4.3 to Angular 12** and its Router, PathLocationStrategy as well as HashLocationStrategy and CommonJS-Bundling via webpack.
Successfully tested with **Angular 4.3 to Angular 15** 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 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!**).
Expand Down Expand Up @@ -107,7 +111,31 @@ _redirectUris:_
npm i angular-oauth2-oidc --save
```

## Importing the NgModule

## 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
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()
]
});
```

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';
Expand Down
65 changes: 57 additions & 8 deletions docs/classes/AuthConfig.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,11 @@ <h6><b>Properties</b></h6>
<span class="modifier">Optional</span>
<a href="#customTokenParameters" >customTokenParameters</a>
</li>
<li>
<span class="modifier">Public</span>
<span class="modifier">Optional</span>
<a href="#decreaseExpirationBySec" >decreaseExpirationBySec</a>
</li>
<li>
<span class="modifier">Public</span>
<span class="modifier">Optional</span>
Expand Down Expand Up @@ -355,7 +360,7 @@ <h3 id="constructor">Constructor</h3>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="275" class="link-to-prism">projects/lib/src/auth.config.ts:275</a></div>
<div class="io-line">Defined in <a href="" data-line="280" class="link-to-prism">projects/lib/src/auth.config.ts:280</a></div>
</td>
</tr>

Expand Down Expand Up @@ -418,7 +423,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="275" class="link-to-prism">projects/lib/src/auth.config.ts:275</a></div>
<div class="io-line">Defined in <a href="" data-line="280" class="link-to-prism">projects/lib/src/auth.config.ts:280</a></div>
</td>
</tr>

Expand Down Expand Up @@ -616,6 +621,45 @@ <h3 id="inputs">

</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
<td class="col-md-4">
<a name="decreaseExpirationBySec"></a>
<span class="name">
<span class="modifier">Public</span>
<span class="modifier">Optional</span>
<span ><b>decreaseExpirationBySec</b></span>
<a href="#decreaseExpirationBySec"><span class="icon ion-ios-link"></span></a>
</span>
</td>
</tr>
<tr>
<td class="col-md-4">
<i>Type : </i> <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/number" target="_blank" >number</a></code>

</td>
</tr>
<tr>
<td class="col-md-4">
<i>Default value : </i><code>0</code>
</td>
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="243" class="link-to-prism">projects/lib/src/auth.config.ts:243</a></div>
</td>
</tr>

<tr>
<td class="col-md-4">
<div class="io-description"><p>Decreases the Expiration time of tokens by this number of seconds</p>
</div>
</td>
</tr>

</tbody>
</table>
<table class="table table-sm table-bordered">
<tbody>
<tr>
Expand Down Expand Up @@ -673,7 +717,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="270" class="link-to-prism">projects/lib/src/auth.config.ts:270</a></div>
<div class="io-line">Defined in <a href="" data-line="275" class="link-to-prism">projects/lib/src/auth.config.ts:275</a></div>
</td>
</tr>

Expand Down Expand Up @@ -707,7 +751,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="258" class="link-to-prism">projects/lib/src/auth.config.ts:258</a></div>
<div class="io-line">Defined in <a href="" data-line="263" class="link-to-prism">projects/lib/src/auth.config.ts:263</a></div>
</td>
</tr>

Expand Down Expand Up @@ -1063,7 +1107,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="288" class="link-to-prism">projects/lib/src/auth.config.ts:288</a></div>
<div class="io-line">Defined in <a href="" data-line="293" class="link-to-prism">projects/lib/src/auth.config.ts:293</a></div>
</td>
</tr>

Expand Down Expand Up @@ -1171,7 +1215,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="264" class="link-to-prism">projects/lib/src/auth.config.ts:264</a></div>
<div class="io-line">Defined in <a href="" data-line="269" class="link-to-prism">projects/lib/src/auth.config.ts:269</a></div>
</td>
</tr>

Expand Down Expand Up @@ -2168,7 +2212,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="251" class="link-to-prism">projects/lib/src/auth.config.ts:251</a></div>
<div class="io-line">Defined in <a href="" data-line="256" class="link-to-prism">projects/lib/src/auth.config.ts:256</a></div>
</td>
</tr>

Expand Down Expand Up @@ -2210,7 +2254,7 @@ <h3 id="inputs">
</tr>
<tr>
<td class="col-md-4">
<div class="io-line">Defined in <a href="" data-line="243" class="link-to-prism">projects/lib/src/auth.config.ts:243</a></div>
<div class="io-line">Defined in <a href="" data-line="248" class="link-to-prism">projects/lib/src/auth.config.ts:248</a></div>
</td>
</tr>

Expand Down Expand Up @@ -2474,6 +2518,11 @@ <h3 id="inputs">
*/
public clockSkewInSec?: number;

/**
* Decreases the Expiration time of tokens by this number of seconds
*/
public decreaseExpirationBySec? &#x3D; 0;

/**
* The interceptors waits this time span if there is no token
*/
Expand Down
22 changes: 20 additions & 2 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,12 @@ <h2 id="resources">Resources</h2>
<li>Community-provided sample implementation: <a href="https://github.com/jeroenheijmans/sample-angular-oauth2-oidc-with-auth-guards/">https://github.com/jeroenheijmans/sample-angular-oauth2-oidc-with-auth-guards/</a></li>
</ul>
<h2 id="tested-environment">Tested Environment</h2>
<p>Successfully tested with <strong>Angular 4.3 to Angular 12</strong> and its Router, PathLocationStrategy as well as HashLocationStrategy and CommonJS-Bundling via webpack. </p>
<p>Successfully tested with <strong>Angular 4.3 to Angular 15</strong> and its Router, PathLocationStrategy as well as HashLocationStrategy and CommonJS-Bundling via webpack. </p>
<p>At server side we&#39;ve used <strong>IdentityServer</strong> (.NET / .NET Core), Redhat&#39;s <strong>Keycloak</strong> (Java), and <strong>Auth0</strong> (Auth0 is officially supported since version 10 of this lib). For Auth0, please have a look into the respective documentation page here.</p>
<p>For using this library with <strong>Azure Active Directory</strong> (<strong>Azure AD</strong>), we recommend an additional look to this <a href="https://dev.to/yuriburger/azure-active-directory-b2c-with-pkce-for-your-angular-app-1dcg">blog post</a> and the example linked at the end of this blog post.</p>
<p>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.</p>
<p><strong>Angular 15</strong>: Use 15.x versions of this library (<strong>should also work with older Angular versions!</strong>).</p>
<p><strong>Angular 14</strong>: Use 14.x versions of this library (<strong>should also work with older Angular versions!</strong>).</p>
<p><strong>Angular 13</strong>: Use 13.x versions of this library (<strong>should also work with older Angular versions!</strong>).</p>
<p><strong>Angular 12</strong>: Use 12.x versions of this library (<strong>should also work with older Angular versions!</strong>).</p>
<p><strong>Angular 11</strong>: Use 10.x versions of this library (<strong>should also work with older Angular versions!</strong>).</p>
Expand Down Expand Up @@ -118,7 +120,23 @@ <h2 id="sample-auth-server">Sample-Auth-Server</h2>
<li>localhost:[4200-4202]/silent-refresh.html</li>
</ul>
<h2 id="installing">Installing</h2>
<div><pre class="line-numbers"><code class="language-sh">npm i angular-oauth2-oidc --save</code></pre></div><h2 id="importing-the-ngmodule">Importing the NgModule</h2>
<div><pre class="line-numbers"><code class="language-sh">npm i angular-oauth2-oidc --save</code></pre></div><h2 id="option-1-standalone-apis">Option 1: Standalone APIs</h2>
<p>If you use Standalone Components introduced with Angular 14, you can use our standalone API (call to <code>provideOAuthClient</code>) in your <code>main.ts</code> to setup the <code>OAuthClient</code>:</p>
<div><pre class="line-numbers"><code class="language-TypeScript">// main.ts
import { bootstrapApplication } from &#39;&#64;angular/platform-browser&#39;;

import { provideHttpClient } from &#39;&#64;angular/common/http&#39;;

import { AppComponent } from &#39;./app/app.component&#39;;
import { provideOAuthClient } from &#39;angular-oauth2-oidc&#39;;

bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(),
provideOAuthClient()
]
});</code></pre></div><p>The <code>provideOAuthClient</code> 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.</p>
<h2 id="option-2-using-ngmodules">Option 2: Using NgModules</h2>
<div><pre class="line-numbers"><code class="language-TypeScript">import { HttpClientModule } from &#39;&#64;angular/common/http&#39;;
import { OAuthModule } from &#39;angular-oauth2-oidc&#39;;
// etc.
Expand Down
Loading

0 comments on commit be84e3d

Please sign in to comment.