Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update configuration documentation #2039

Merged
merged 1 commit into from
Oct 27, 2024
Merged

docs: update configuration documentation #2039

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 67 additions & 87 deletions docs/site/angular-auth-oidc-client/docs/documentation/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,33 +10,34 @@ Prior to using the library, you must configure it with the appropriate values fo

## Configure with static config

You can pass the static config with the `config` property into the `forRoot()` method like this
You can pass the static config with the `config` property using the `provideAuth` function.

```ts
import { NgModule } from '@angular/core';
import { AuthModule } from 'angular-auth-oidc-client';
import { ApplicationConfig } from '@angular/core';
import { provideAuth } from 'angular-auth-oidc-client';

@NgModule({
imports: [
AuthModule.forRoot({
export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
config: {
/* Your config here */
},
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
};
```

### Using multiple configs

You can pass an array of configs into the `forRoot()` method. Each config will get an `configId` automatically if you do not set it for yourself.
You can pass an array of configs into the `provideAuth()` method. Each config will get an `configId` automatically if you do not set it for yourself.

```ts
@NgModule({
imports: [
AuthModule.forRoot({
import { ApplicationConfig } from '@angular/core';
import { provideAuth } from 'angular-auth-oidc-client';

export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
config: [
{
// config1...
Expand All @@ -51,9 +52,7 @@ You can pass an array of configs into the `forRoot()` method. Each config will g
],
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
};
```

### Getting static config from a service (sync)
Expand All @@ -75,27 +74,25 @@ const authFactory = (configService: ConfigService) => {
return new StsConfigStaticLoader(config);
};

@NgModule({
imports: [
AuthModule.forRoot({
export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
loader: {
provide: StsConfigLoader,
useFactory: authFactory,
deps: [ConfigService],
},
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
};
```

## Load config from HTTP (async)

If you want to load the config from HTTP and then map it to the interface the library provides you can use the `StsConfigHttpLoader` and pass it with the `loader` property.

```ts
import { AuthModule, StsConfigHttpLoader, StsConfigLoader } from 'angular-auth-oidc-client';
import { provideAuth, StsConfigHttpLoader, StsConfigLoader } from 'angular-auth-oidc-client';

export const httpLoaderFactory = (httpClient: HttpClient) => {
const config$ = httpClient.get<any>(`https://...`).pipe(
Expand All @@ -110,27 +107,25 @@ export const httpLoaderFactory = (httpClient: HttpClient) => {
return new StsConfigHttpLoader(config$);
};

@NgModule({
imports: [
AuthModule.forRoot({
export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
loader: {
provide: StsConfigLoader,
useFactory: httpLoaderFactory,
deps: [HttpClient],
},
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
};
```

### Using multiple HTTP configs

The HTTP loader also supports multiple configs.

```ts
import { AuthModule, StsConfigHttpLoader, StsConfigLoader } from 'angular-auth-oidc-client';
import { provideAuth, StsConfigHttpLoader, StsConfigLoader } from 'angular-auth-oidc-client';

export const httpLoaderFactory = (httpClient: HttpClient) => {
const config1$ = httpClient.get<any>(`https://...`).pipe(
Expand All @@ -154,57 +149,26 @@ export const httpLoaderFactory = (httpClient: HttpClient) => {
return new StsConfigHttpLoader([config1$, config2$]);
};

@NgModule({
imports: [
AuthModule.forRoot({
export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
loader: {
provide: StsConfigLoader,
useFactory: httpLoaderFactory,
deps: [HttpClient],
},
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
};
```

### Using localstorage instead of default sessionstorage

The angular-auth-oidc-client uses session storage by default that gets cleared whenever you open the website in a new tab, if you want to change it to localstorage then need to provide a different AbstractSecurityStorage.

```ts
import { NgModule } from '@angular/core';
import { AuthModule, DefaultLocalStorageService, AbstractSecurityStorage } from 'angular-auth-oidc-client';

@NgModule({
imports: [
AuthModule.forRoot({
config: {
/* Your config here */
},
}),
],
exports: [AuthModule],
providers: [
{
provide: AbstractSecurityStorage,
useClass: DefaultLocalStorageService,
},
],
})
export class AuthConfigModule {}
```

## Configure with standalone config

To configure the auth module by using the standalone API, you can use the `provideAuth` method
The angular-auth-oidc-client uses session storage by default that gets cleared whenever you open the website in a new tab, if you want to change it to local storage then need to provide a different `AbstractSecurityStorage`.

```ts
import { ApplicationConfig } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideAuth } from 'angular-auth-oidc-client';
import { AppComponent } from './app/app.component';
import { provideAuth, DefaultLocalStorageService, AbstractSecurityStorage } from 'angular-auth-oidc-client';

export const appConfig: ApplicationConfig = {
providers: [
Expand All @@ -213,20 +177,22 @@ export const appConfig: ApplicationConfig = {
/* Your config here */
},
}),
{
provide: AbstractSecurityStorage,
useClass: DefaultLocalStorageService,
},
],
};

bootstrapApplication(AppComponent, appConfig);
```

Additionally, you can use the feature function `withAppInitializerAuthCheck`
to handle OAuth callbacks during app initialization phase. This replaces the
need to manually call `OidcSecurityService.checkAuth(...)` or
`OidcSecurityService.checkAuthMultiple(...)`.
## OAuth Callbacks during Initialization

Additionally, you can use the feature function `withAppInitializerAuthCheck` to handle OAuth callbacks during app initialization phase. This replaces the need to manually call `OidcSecurityService.checkAuth(...)` or `OidcSecurityService.checkAuthMultiple(...)`.

```ts
import { ApplicationConfig } from '@angular/core';
import { provideAuth, withAppInitializerAuthCheck } from 'angular-auth-oidc-client';

export const appConfig: ApplicationConfig = {
providers: [
provideAuth(
Expand All @@ -241,27 +207,41 @@ export const appConfig: ApplicationConfig = {
};
```

If you prefer to manually check OAuth callback state, you can omit
`withAppInitializerAuthCheck`. However, you then need to call
`OidcSecurityService.checkAuth(...)` or
`OidcSecurityService.checkAuthMultiple(...)` manually in your
`app.component.ts` (or a similar code path that is called early in your app).
If you prefer to manually check OAuth callback state, you can omit `withAppInitializerAuthCheck`. However, you then need to call `OidcSecurityService.checkAuth(...)` or `OidcSecurityService.checkAuthMultiple(...)` manually in your `app.component.ts` (or a similar code path that is called early in your app).

```ts
// Shortened for brevity
...
@Component()
export class AppComponent implements OnInit {
private readonly oidcSecurityService = inject(OidcSecurityService);

ngOnInit(): void {
this.oidcSecurityService
.checkAuth()
.subscribe(({ isAuthenticated, accessToken }) => {
console.log('app authenticated', isAuthenticated);
console.log(`Current access token is '${accessToken}'`);
});
this.oidcSecurityService.checkAuth().subscribe(({ isAuthenticated, accessToken }) => {
console.log('app authenticated', isAuthenticated);
console.log(`Current access token is '${accessToken}'`);
});
}
...
}
```

## Configure with NgModule

To configure the auth module by using `NgModule`, you can use the `AuthModule.forRoot()` method

```ts
import { NgModule } from '@angular/core';
import { AuthModule } from 'angular-auth-oidc-client';

@NgModule({
imports: [
AuthModule.forRoot({
config: {
/* Your config here */
},
}),
],
exports: [AuthModule],
})
export class AuthConfigModule {}
```

## Config Values
Expand Down
Loading