@oneplatform/plugin-sdk

@oneplatform/plugin-sdk / AuthProvider

Interface: AuthProvider¶

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:82

Methods¶

getAuthorizationUrl()¶

getAuthorizationUrl(state, options): string

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:95

Build the authorization URL that the browser navigates to. This method is synchronous — it should not make network calls.

Parameters¶

state¶

string

An opaque, cryptographically random string generated by the Auth Service. Include this in the authorization URL as the state query parameter. The Auth Service will verify it matches when the callback arrives.

options¶

AuthOptions

Platform-provided callback configuration.

Returns¶

string

The full authorization URL to redirect the browser to.

handleCallback()¶

handleCallback(params, context): Promise\<AuthResult>

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:107

Handle the OAuth callback. Exchange the authorization code for tokens.

The Auth Service has already verified the state parameter (CSRF check) before calling this method. The plugin should exchange the code for tokens and return an AuthResult. Never call external token validation URLs from this method — the platform considers the tokens valid if they arrive in the provider's callback.

Parameters¶

params¶

CallbackParams

context¶

AuthContext

Returns¶

Promise\<AuthResult>

Throws¶

PluginAuthError if the code exchange fails (e.g., expired code, bad credentials).

mapClaimsToRoles()¶

mapClaimsToRoles(claims): string[]

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:140

Map external identity provider claims to OnePlatform RBAC role names. Called during login and on every token refresh to keep role assignments current.

Returns an array of platform role name strings. Roles that do not exist in the platform are ignored. An empty array means the user has no roles (they can still log in but will have no permissions).

This method is synchronous and must not make network calls.

Parameters¶

claims¶

Record\<string, unknown>

Returns¶

string[]

metadata()¶

metadata(): AuthProviderMetadata

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:83

Returns¶

AuthProviderMetadata

refreshToken()?¶

optional refreshToken(refreshToken, context): Promise\<TokenPair>

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:128

Exchange a refresh token for a new access token. Only implement if AuthProviderMetadata.supportsTokenRefresh is true.

Use context.cache.lock() to prevent concurrent refreshes for the same user.

Parameters¶

refreshToken¶

string

context¶

AuthContext

Returns¶

Promise\<TokenPair>

Throws¶

PluginAuthError if the refresh token is expired or revoked.

validateToken()?¶

optional validateToken(token, context): Promise\<TokenValidation>

Defined in: packages/plugin-sdk/src/types/auth-provider.ts:118

Validate an access token with the external provider. Only implement if AuthProviderMetadata.supportsTokenValidation is true. Called on API requests to verify the token has not been revoked externally.

Parameters¶

token¶

string

context¶

AuthContext

Returns¶

Promise\<TokenValidation>

TokenValidation with valid=false if the token is expired or revoked. Do not throw for invalid tokens — return valid=false.

Throws¶

PluginAuthError only for unrecoverable errors (e.g., provider unreachable).