OAuth Service

The OAuth Service enables developers to integrate third-party authentication providers and to expose a standard OAuth 2.0 interface for their own applications. This service facilitates federated login, allowing users to sign in with accounts from providers like Google, GitHub, Apple, and Twitter, and also allows your Blocklet Service to function as a centralized authentication authority for other applications.

This guide is intended for developers and covers the technical details of configuring and using the OAuth Service APIs. For administrative configuration through the UI, please refer to the OAuth Apps section in the User Guide.

Overview#

The OAuth Service has a dual role:

1. OAuth Client: It acts as a client to external OAuth providers. When a user chooses to log in with a third-party service, the Blocklet Service handles the redirects, token exchanges, and profile retrieval required to authenticate the user.
2. OAuth Server: It functions as a fully-featured OAuth 2.0 and OpenID Connect (OIDC) provider. This allows external or third-party applications to delegate authentication to your service, providing a secure method for them to access user data with proper consent.

Authentication Flow (Authorization Code Grant)#

The service primarily uses the OAuth 2.0 Authorization Code Grant flow, which is a secure and widely adopted standard for web applications. The process involves the user, the client application (your blocklet or a third-party app), the authorization server (this OAuth Service), and the resource server.

The following diagram illustrates the sequence of interactions in this flow:

Integrating Third-Party Providers (Client)#

You can enable users to log in to your application using their existing accounts from various providers.

Configuration#

Configuration for each provider is managed within the blocklet's settings. You will need to obtain credentials (e.g., Client ID and Client Secret) from the developer console of each provider you wish to integrate.

The following providers are supported:

Client-Side API Flow#

The client-side flow for initiating a third-party login and handling the callback is as follows:

1. Initiate Login: Redirect the user to the login endpoint for the desired provider.
2. Handle Callback: After the user authenticates with the third-party provider, they are redirected back to your application. The callback URL will contain an authorization code.
3. Finalize Login: Your application sends this code to the backend API to exchange it for a session token.

GET /.well-known/service/oauth/login/:provider#

Redirects the user to the selected provider's authentication page. The referrer header is required and must match a trusted domain configured in the service.

Parameters

POST /.well-known/service/api/oauth/login#

After the user is redirected back from the provider, use this endpoint to exchange the authorization code for a session token.

Parameters

Returns

User Profile Data#

When a user authenticates, the service retrieves their profile from the provider. The structure of this profile is normalized but may contain provider-specific data in an extraData field.

Standard Profile Structure#

Acting as an OAuth 2.0 Provider (Server)#

The Blocklet Service can also function as a standard OAuth 2.0 and OIDC provider, allowing third-party applications to authenticate your users and access protected resources on their behalf.

Standard Endpoints#

The service exposes the following standard endpoints, all prefixed with /.well-known/service/oauth.

Endpoint	Path	Description
Authorization	/authorize	Starts the authorization process by redirecting the user for login and consent.
Token	/token	Exchanges authorization codes or refresh tokens for access tokens.
Client Registration	/register	Allows dynamic registration of new client applications.
User Info	/userinfo	Retrieves profile information for the authenticated user using an access token.
Token Revocation	/revoke	Invalidates an access or refresh token.
JSON Web Key Set	/jwks.json	Provides the public keys used to verify JWT signatures.

API Details#

Authorization Endpoint#

GET /.well-known/service/oauth/authorize

This endpoint initiates the login and consent flow.

Query Parameters

Token Endpoint#

POST /.well-known/service/oauth/token

This endpoint is used to exchange an authorization code or refresh token for an access token.

Request Body (Authorization Code Grant)

Request Body (Refresh Token Grant)

Successful Response

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "scope": "profile:read",
  "expires_in": 3600
}

UserInfo Endpoint#

GET /.well-known/service/oauth/userinfo

Retrieves the authenticated user's profile information. Requires a valid access_token in the Authorization header.

Successful Response

{
  "sub": "z2...",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "picture": "https://example.com/avatar.png",
  "preferred_username": "John Doe",
  "email_verified": true
}

Summary#

The OAuth Service is a powerful component for managing user authentication. By supporting both client integrations with major identity providers and acting as a standard OAuth 2.0 server, it provides a flexible and secure foundation for identity management in your applications.

For more information on the underlying protocols, please refer to the official documentation:

• OAuth 2.0 Authorization Framework
• OpenID Connect Core 1.0