Class OAuth2

constructor

• new OAuth2(metadata: ValidatedAuthMetadata, context: Context): OAuth2

  Parameters

  • metadata: ValidatedAuthMetadata
  • context: Context

  Returns OAuth2

Readonlycontext

Readonlymetadata

completeAuthorizationCodeGrant

• completeAuthorizationCodeGrant(code: string): Promise<BearerTokenResponse>

  Attempt to exchange authorization code for bearer token.

  Takes the authorization code returned by the OAuth2 Provider via the authorization URL, and makes a request to the Token Endpoint, to obtain the access token, refresh token, etc.

  Parameters

  • code: string

    authorization code as returned by IdP during authorization

  Returns Promise<BearerTokenResponse>

  a validated bearer token response

  Throws

  An Error with message set to an entry in OAuth2Error, when the request fails, or the returned token response is invalid.

generateAuthorizationCodeGrantUrl

• generateAuthorizationCodeGrantUrl(
      state: string,
      responseMode?: "query" | "fragment",
      prompt?: string,
      scope?: string,
  ): Promise<string>

  Generate a URL to attempt authorization with the OP See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-flow

  Parameters

  • state: string

    A unique opaque identifier, like a transaction ID, that will allow the client to maintain state between the authorization request and the callback. The app should use this to key the storage for where the rest of the auth context is saved.

  • responseMode: "query" | "fragment" = "fragment"

    The manner in which the IdP should send the secrets back to the app. Defaults to fragment for privacy.

  • Optionalprompt: string

    Optional prompt parameter to pass to the IdP to signal intent, e.g. create for User registration.

  • Optionalscope: string

    The OAuth2 scope to request, will be generated based on the device ID if omitted.

  Returns Promise<string>

  a Promise with the url as a string

performRefreshTokenGrant

• performRefreshTokenGrant(refreshToken: string): Promise<BearerTokenResponse>

  Refresh the access token using the given refresh token and the refresh token grant

  Parameters

  • refreshToken: string

    the token to use to refresh the access token

  Returns Promise<BearerTokenResponse>

revokeToken

• revokeToken(
      token: string,
      type?: "access_token" | "refresh_token",
  ): Promise<void>

  Revokes the given token

  Parameters

  • token: string

    the token to remove

  • Optionaltype: "access_token" | "refresh_token"

    the type of token, acts as a hint to the IdP

  Returns Promise<void>

startDeviceAuthorizationGrant

• startDeviceAuthorizationGrant(
      scope?: string,
  ): Promise<DeviceAuthorizationResponse>

  Begin OAuth2 device authorization flow.

  Parameters

  • Optionalscope: string

    the scope to request for authorization.

  Returns Promise<DeviceAuthorizationResponse>

  a promise that resolves to a device access token response, or an error response if the user denies authorization or the device code expires.

waitForDeviceAuthorizationGrant

• waitForDeviceAuthorizationGrant(
      session: DeviceAuthorizationResponse,
  ): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>

  Polls the OAuth2 token endpoint until we get a device access token response, or encounter an unrecoverable error.

  Parameters

  • session: DeviceAuthorizationResponse

    The session returned from a previous call to OAuth2.startDeviceAuthorizationGrant.

  Returns Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>

  a promise that resolves to a device access token response, or an error response if the user denies authorization or the device code expires.

StaticregisterClient

• registerClient(
      authMetadata: ValidatedAuthMetadata,
      clientMetadata: OAuthRegistrationRequest,
  ): Promise<string>

  Attempts dynamic registration against the configured registration endpoint. Will ignore any URIs that do not use client_uri as a common base as per the spec.

  Parameters

  • authMetadata: ValidatedAuthMetadata

    Auth config from MatrixClient.getAuthMetadata

  • clientMetadata: OAuthRegistrationRequest

    The metadata for the client which to register, grant_types & response_types & token_endpoint_auth_method will be sanely calculated if omitted.

  Returns Promise<string>

  Promise resolved with registered clientId

  Throws

  when registration is not supported, on failed request or invalid response