Skip to main content

OAuthProvider

@webda/auth

Abstract Class: OAuthProvider<T, E>

Defined in: packages/auth/src/oauth/oauth.service.ts:283

Base of the OAuth 2.0 / OpenID Connect login providers

Exposes, under url (default /auth/<providerName>):

  • GET <url>{?redirect}: starts a login with a random state, a PKCE (S256) verifier and an OpenID nonce, kept in a dedicated encrypted cookie (10 min, HttpOnly, SameSite=Lax, path url), then redirects to the provider; redirect must match authorized_uris
  • GET <url>/callback: consumes that cookie, checks the state, exchanges the code (handleCallback) and hands the identity to Authentication.complete(); never throws, failures go to redirects.failure?reason=<CODE>
  • operation Auth.<Provider>.Token (POST auth/<providerName>/token, JSON body { token } or { tokens }) for non-browser clients; it never links an identity to the session user

Subclasses implement providerName, getAuthorizationUrl, handleCallback and handleToken; the provider of the returned identities is always forced to providerName.

Extends​

  • Service<T, E>

Type Parameters​

T​

T extends OAuthProviderParameters = OAuthProviderParameters

E​

E extends AsyncEventUnknown = { }

Implements​

Constructors​

Constructor​

new OAuthProvider<T, E>(name, params): OAuthProvider<T, E>

Defined in: packages/core/lib/services/service.d.ts:72

Service

Parameters​

name​

string

The name of the service

params​

T

The parameters block define in the configuration file

Returns​

OAuthProvider<T, E>

Inherited from​

Service<T, E>.constructor

Properties​

_compiledCapabilities​

protected _compiledCapabilities: Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:39

Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.

Populated during Service.resolve by reading the service's entry in webda.module.json. Each key is a capability name (e.g., "request-filter"), and the value is an empty object {} by default. Override getCapabilities to provide capability-specific configuration or to conditionally disable capabilities.

See​

getCapabilities

Implementation of​

AuthProvider._compiledCapabilities

Inherited from​

Service._compiledCapabilities

[WEBDA_EVENTS]​

[WEBDA_EVENTS]: E

Defined in: packages/core/lib/services/service.d.ts:50

Set the Webda events here

Implementation of​

AuthProvider.[WEBDA_EVENTS]

Inherited from​

Service.[WEBDA_EVENTS]

logger​

protected logger: Logger

Defined in: packages/core/lib/services/service.d.ts:59

Logger with class context

Implementation of​

AuthProvider.logger

Inherited from​

Service.logger

metrics?​

protected optional metrics?: object

Defined in: packages/core/lib/services/service.d.ts:63

Get metrics

Implementation of​

AuthProvider.metrics

Inherited from​

Service.metrics

name​

readonly name: string

Defined in: packages/core/lib/services/iservice.d.ts:19

Implementation of​

AuthProvider.name

Inherited from​

Service.name

parameters​

readonly parameters: T

Defined in: packages/core/lib/services/iservice.d.ts:20

Implementation of​

AuthProvider.parameters

Inherited from​

Service.parameters

providerName​

abstract readonly providerName: string

Defined in: packages/auth/src/oauth/oauth.service.ts:293

Unique provider name, used in ident keys ("google")

Implementation of​

AuthProvider.providerName

createConfiguration?​

static optional createConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:24

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.createConfiguration

filterConfiguration?​

static optional filterConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:28

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.filterConfiguration

Parameters​

static Parameters: typeof OAuthProviderParameters = OAuthProviderParameters

Defined in: packages/auth/src/oauth/oauth.service.ts:290

Service parameters

Overrides​

Service.Parameters

Methods​

__clean()​

abstract __clean(): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:215

Clean the service data, can only be used in test mode

Returns​

Promise<void>

Implementation of​

AuthProvider.__clean

Inherited from​

Service.__clean

addListener()​

addListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:80

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void | Promise<void>

the event listener

Returns​

this

this for chaining

See​

EventEmitter.addListener

Implementation of​

AuthProvider.addListener

Inherited from​

Service.addListener

addRoute()​

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/lib/services/service.d.ts:177

Add a route dynamicaly

Parameters​

url​

string

of the route can contains dynamic part like {uuid}

methods​

HttpMethodType[]

the HTTP methods

executer​

Function

Method to execute for this route

openapi?​

OpenAPIWebdaDefinition

the OpenAPI specification

override?​

boolean

whether to override existing

Returns​

void

Implementation of​

AuthProvider.addRoute

Inherited from​

Service.addRoute

allowedRedirect()​

protected allowedRedirect(redirect): string

Defined in: packages/auth/src/oauth/oauth.service.ts:513

Check a post-login target against authorized_uris: same origin, and the listed path or below it; an encoded slash or backslash in the path is refused

Parameters​

redirect​

unknown

candidate

Returns​

string

the normalised url, undefined when not allowed

authorizeClientEvent()​

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/lib/services/service.d.ts:153

Authorize a public event subscription

Parameters​

_event​

string

the event name

_context​

OperationContext

the execution context

Returns​

boolean

true if the condition is met

Implementation of​

AuthProvider.authorizeClientEvent

Inherited from​

Service.authorizeClientEvent

callback()​

callback(ctx): Promise<void>

Defined in: packages/auth/src/oauth/oauth.service.ts:671

Provider callback: verify the state, exchange the code, complete the login and redirect; never throws

Parameters​

ctx​

WebContext

web context

Returns​

Promise<void>

checkIdentity()​

protected checkIdentity(identity): ResolvedIdentity

Defined in: packages/auth/src/oauth/oauth.service.ts:488

Parameters​

identity​

ResolvedIdentity

identity returned by the subclass

Returns​

ResolvedIdentity

the identity

Throws​

TokenInvalid when it has no subject

computeParameters()​

computeParameters(): void

Defined in: packages/core/lib/services/service.d.ts:77

Used to compute or derivate input parameter to attribute

Returns​

void

Deprecated​

Implementation of​

AuthProvider.computeParameters

Inherited from​

Service.computeParameters

consumePending()​

protected consumePending(ctx): Promise<PendingLogin>

Defined in: packages/auth/src/oauth/oauth.service.ts:571

Read and clear the pending login cookie

Parameters​

ctx​

WebContext

web context

Returns​

Promise<PendingLogin>

the pending login, undefined when absent, invalid, expired or of another provider

emit()​

emit<Key>(event, data): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:204

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

event​

Key

the event name

data​

E[Key]

the data to process

Returns​

Promise<void>

Implementation of​

AuthProvider.emit

Inherited from​

Service.emit

fail()​

protected fail(ctx, reason): void

Defined in: packages/auth/src/oauth/oauth.service.ts:609

Parameters​

ctx​

WebContext

web context

reason​

string

failure code

Returns​

void

getAuthorizationUrl()​

abstract getAuthorizationUrl(request): string | Promise<string>

Defined in: packages/auth/src/oauth/oauth.service.ts:300

Build the authorization url of the provider, sending the PKCE challenge and the nonce

Parameters​

request​

OAuthAuthorizationRequest

authorization request

Returns​

string | Promise<string>

the url to redirect the browser to

getCapabilities()​

getCapabilities(): Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:61

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns​

Record<string, any>

the result

Webda Capability-tagged​

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
  const caps = super.getCapabilities();
  if (!this.parameters.enabled) delete caps["request-filter"];
  return caps;
}

Implementation of​

AuthProvider.getCapabilities

Inherited from​

Service.getCapabilities

getClientEvents()​

getClientEvents(): string[]

Defined in: packages/core/lib/services/service.d.ts:144

Return the events that an external system can subscribe to

Returns​

string[]

the list of results

Implementation of​

AuthProvider.getClientEvents

Inherited from​

Service.getClientEvents

getCookieName()​

protected getCookieName(): string

Defined in: packages/auth/src/oauth/oauth.service.ts:345

Returns​

string

the name of the pending login cookie

getMaxListeners()​

getMaxListeners(): number

Defined in: packages/core/lib/events/asynceventemitter.d.ts:84

Returns​

number

Implementation of​

AuthProvider.getMaxListeners

Inherited from​

Service.getMaxListeners

getMetric()​

getMetric<T>(type, configuration): T

Defined in: packages/core/lib/services/service.d.ts:138

Add service name label

Type Parameters​

T​

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters​

type​

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration​

MetricConfiguration<T>

the configuration

Returns​

T

the result

Implementation of​

AuthProvider.getMetric

Inherited from​

Service.getMetric

getName()​

getName(): string

Defined in: packages/core/lib/services/service.d.ts:209

Get service name

Returns​

string

the result string

Implementation of​

AuthProvider.getName

Inherited from​

Service.getName

getOpenApiReplacements()​

getOpenApiReplacements(): any

Defined in: packages/core/lib/services/service.d.ts:182

Return variables for replacement in openapi

Returns​

any

the result

Implementation of​

AuthProvider.getOpenApiReplacements

Inherited from​

Service.getOpenApiReplacements

getOperationId()​

getOperationId(id): string

Defined in: packages/core/lib/services/service.d.ts:167

If undefined is returned it cancel the operation registration

Parameters​

id​

string

the identifier

Returns​

string

the result

Implementation of​

AuthProvider.getOperationId

Inherited from​

Service.getOperationId

getParameters()​

getParameters(): T

Defined in: packages/core/lib/services/service.d.ts:82

Get the service parameters

Returns​

T

the result

Implementation of​

AuthProvider.getParameters

Inherited from​

Service.getParameters

getPublicInfo()​

getPublicInfo(): ProviderInfo

Defined in: packages/auth/src/oauth/oauth.service.ts:404

Returns​

ProviderInfo

public info

Implementation of​

AuthProvider.getPublicInfo

getRedirectUri()​

protected getRedirectUri(ctx): string

Defined in: packages/auth/src/oauth/oauth.service.ts:534

Parameters​

ctx​

WebContext

web context

Returns​

string

the callback url sent to the provider

getService()​

getService<T>(name): ServicesMap[T]

Defined in: packages/core/lib/services/service.d.ts:131

Get a service by name

Type Parameters​

T​

T extends keyof ServicesMap

Parameters​

name​

T

the name to use

Returns​

ServicesMap[T]

the result map

Deprecated​

Use useService, might reconsider

Implementation of​

AuthProvider.getService

Inherited from​

Service.getService

getState()​

getState(): ServiceStates

Defined in: packages/core/lib/services/service.d.ts:55

Get the current state

Returns​

ServiceStates

the result

Implementation of​

AuthProvider.getState

Inherited from​

Service.getState

getUrl()​

getUrl(url, _methods): string

Defined in: packages/core/lib/services/service.d.ts:161

Return the full path url based on parameters

Parameters​

url​

string

relative url to service

_methods​

HttpMethodType[]

in case we need filtering (like Store)

Returns​

string

absolute url or undefined if need to skip the Route

Implementation of​

AuthProvider.getUrl

Inherited from​

Service.getUrl

handleCallback()​

abstract handleCallback(request): Promise<ResolvedIdentity>

Defined in: packages/auth/src/oauth/oauth.service.ts:309

Exchange an authorization code (with the PKCE verifier) and verify the result, including the nonce of an ID token

Parameters​

request​

OAuthCallbackRequest

code exchange

Returns​

Promise<ResolvedIdentity>

the identity proven by the provider

Throws​

an HttpError (for example TokenInvalid) whose code is used as the failure reason

handleToken()​

abstract handleToken(request): Promise<ResolvedIdentity>

Defined in: packages/auth/src/oauth/oauth.service.ts:317

Verify a token presented by a non-browser client

Parameters​

request​

OAuthTokenRequest

token and/or tokens (at least one is present)

Returns​

Promise<ResolvedIdentity>

the identity proven by the provider

Throws​

TokenInvalid when the token cannot be verified

init()​

init(): Promise<OAuthProvider<T, E>>

Defined in: packages/auth/src/oauth/oauth.service.ts:357

Returns​

Promise<OAuthProvider<T, E>>

Implementation of​

AuthProvider.init

Overrides​

Service.init

initMetrics()​

initMetrics(): void

Defined in: packages/core/lib/services/service.d.ts:124

Init the metrics

Returns​

void

Implementation of​

AuthProvider.initMetrics

Inherited from​

Service.initMetrics

initOperations()​

initOperations(): void

Defined in: packages/auth/src/oauth/oauth.service.ts:385

Register Auth.<Provider>.Token: its id and path depend on the provider name

Returns​

void

Implementation of​

AuthProvider.initOperations

Overrides​

Service.initOperations

leaveForeignSession()​

protected leaveForeignSession(ctx, identity): Promise<void>

Defined in: packages/auth/src/oauth/oauth.service.ts:469

The token operation never links: with a logged-in session, an identity owned by another user is refused and a new or unowned one starts a fresh session

Parameters​

ctx​

any

operation context

identity​

ResolvedIdentity

verified identity

Returns​

Promise<void>

Throws​

IdentLinkedElsewhere when the identity belongs to another user than the session one

listeners()​

listeners(eventName): Function[]

Defined in: packages/core/lib/events/asynceventemitter.d.ts:139

Get all listeners for an event

Parameters​

eventName​

keyof E

the event name

Returns​

Function[]

the list of results

Implementation of​

AuthProvider.listeners

Inherited from​

Service.listeners

loadCapabilities()​

protected loadCapabilities(): void

Defined in: packages/core/lib/services/service.d.ts:120

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns​

void

Example​

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See​

getCapabilities

Implementation of​

AuthProvider.loadCapabilities

Inherited from​

Service.loadCapabilities

log()​

log(level, ...args): void

Defined in: packages/core/lib/services/service.d.ts:226

Parameters​

level​

WorkerLogLevel

to log

args​

...any[]

additional arguments

Returns​

void

Implementation of​

AuthProvider.log

Inherited from​

Service.log

login()​

login(ctx): Promise<void>

Defined in: packages/auth/src/oauth/oauth.service.ts:624

Start a login: redirect the browser to the provider

Parameters​

ctx​

WebContext

web context

Returns​

Promise<void>

off()​

off<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:116

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.off

Implementation of​

AuthProvider.off

Inherited from​

Service.off

on()​

on<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:102

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Implementation of​

AuthProvider.on

Inherited from​

Service.on

onAuthenticated()​

protected onAuthenticated(_identity, _result, _source, _request?): Promise<void>

Defined in: packages/auth/src/oauth/oauth.service.ts:326

Called after a successful Authentication.complete() (status ok or mfa_required)

Parameters​

_identity​

ResolvedIdentity

the identity

_result​

AuthResult

the result

_source​

"callback" | "token"

browser callback or token operation

_request?​

OAuthTokenRequest

the token operation request (token operation only)

Returns​

Promise<void>

once()​

once<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:95

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Implementation of​

AuthProvider.once

Inherited from​

Service.once

ownIdentity()​

protected ownIdentity(identity): ResolvedIdentity

Defined in: packages/auth/src/oauth/oauth.service.ts:499

Parameters​

identity​

ResolvedIdentity

identity returned by the subclass

Returns​

ResolvedIdentity

the identity, always attributed to this provider

redirect()​

protected redirect(ctx, url): void

Defined in: packages/auth/src/oauth/oauth.service.ts:600

Redirect without caching

Parameters​

ctx​

WebContext

web context

url​

string

target

Returns​

void

removeAllListeners()​

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:122

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName?​

Key

the event name

Returns​

this

this for chaining

See​

EventEmitter.removeAllListeners

Implementation of​

AuthProvider.removeAllListeners

Inherited from​

Service.removeAllListeners

removeListener()​

removeListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:109

Type Parameters​

Key​

Key extends string | number | symbol

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.removeListener

Implementation of​

AuthProvider.removeListener

Inherited from​

Service.removeListener

requireJson()​

protected requireJson(ctx): void

Defined in: packages/auth/src/oauth/oauth.service.ts:453

Refuse a request that is not JSON: cross-site requests can only send form or text/plain bodies without a preflight

Parameters​

ctx​

any

operation context

Returns​

void

Throws​

UnsupportedMediaType when the HTTP request is not application/json

requiresClientSecret()​

protected requiresClientSecret(): boolean

Defined in: packages/auth/src/oauth/oauth.service.ts:338

Returns​

boolean

false when the provider works without client secret (public clients)

resolve()​

resolve(): this

Defined in: packages/auth/src/oauth/oauth.service.ts:350

Returns​

this

Implementation of​

AuthProvider.resolve

Overrides​

Service.resolve

sendPendingCookie()​

protected sendPendingCookie(ctx, redirectUri, value?): void

Defined in: packages/auth/src/oauth/oauth.service.ts:545

Set (or clear, without value) the pending login cookie, scoped to the callback path: the path of the effective redirect_uri, which includes any deployment prefix (API Gateway stage, path-stripping proxy) the routes do not see

Parameters​

ctx​

WebContext

web context

redirectUri​

string

callback url

value?​

string

encrypted pending login

Returns​

void

setMaxListeners()​

setMaxListeners(n): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:88

Parameters​

n​

number

Returns​

this

Implementation of​

AuthProvider.setMaxListeners

Inherited from​

Service.setMaxListeners

stop()​

stop(): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:86

Shutdown the current service if action need to be taken

Returns​

Promise<void>

Implementation of​

AuthProvider.stop

Inherited from​

Service.stop

toJSON()​

toJSON(): string

Defined in: packages/core/lib/services/service.d.ts:191

Prevent service to be serialized

Returns​

string

the result

Implementation of​

AuthProvider.toJSON

Inherited from​

Service.toJSON

token()​

token(token?, tokens?): Promise<AuthResult>

Defined in: packages/auth/src/oauth/oauth.service.ts:418

Log in with a token obtained by the client from the provider

Requires a JSON request (a cross-site form or text/plain POST is refused). A request carrying a logged-in session never links the identity to that user: an identity owned by another user is refused (IDENT_LINKED_ELSEWHERE), a new or unowned one gets a fresh session.

Parameters​

token?​

string

token (an ID token for OpenID Connect providers)

tokens?​

OAuthTokens

credentials obtained from the provider (v3 body)

Returns​

Promise<AuthResult>

the auth result

toString()​

toString(): string

Defined in: packages/core/lib/services/service.d.ts:91

Return service representation

Returns​

string

the result

Implementation of​

AuthProvider.toString

Inherited from​

Service.toString