Berca Gate Documentation

Integrate Berca Gate to add secure, standards-compliant authentication to your applications.

Standards Compliant

Berca Gate implements OAuth 2.0 and OpenID Connect (OIDC) protocols. You can use any standard OIDC library to integrate.

Quick Start

To get started, you need to register a generic "Application" in your dashboard to get a client_id.

Step 1: Configuration

Configure your OIDC client with the following settings:

Parameter	Value
Issuer URL	https://auth.pt-bks.com
Authorization Endpoint	/api/oauth/authorize
Token Endpoint	/api/oauth/token
UserInfo Endpoint	/api/oauth/userinfo

Authorization Code Flow

Recommended for server-side applications. It involves exchanging an authorization code for an access token.

GET /api/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK_URL
  &scope=openid profile email
  &state=RANDOM_STRING

Public Clients & PKCE

For Single Page Apps (SPA) and Mobile Apps, you must use Proof Key for Code Exchange (PKCE).

1. Generate a random code_verifier.
2. Hash it with SHA-256 to get code_challenge.
3. Send the challenge in the Authorization Request.

GET /api/oauth/authorize?
  ...
  &code_challenge=BASE64_URL_ENCODED_HASH
  &code_challenge_method=S256

External Auth Delegation

Seamlessly migrate from legacy systems by delegating authentication.

If you have an existing user database or legacy authentication endpoint, you can configure your Client to delegate login requests to that external URL. When users log in:

The SSO system forwards credentials to your External Login URL.
If successful, the user is automatically synced/created in the SSO database.
The full JSON response from your legacy system is stored securely.
You can retrieve this data using the external_data scope.

Configuration:

Go to Developer Dashboard → select your Client → External Auth Delegation card.

GET

/api/oauth/authorize

Starts the authentication flow.

Parameters

client_id (required): Your app's Client ID.
redirect_uri (required): Must match one of the registered URIs.
response_type (required): Must be code.
scope: Space-separated scopes (e.g. openid email external_data).
prompt (optional): Control the authentication experience.
- login — Force the user to sign in again (e.g. for "Switch Account").
- consent — Force the consent screen to appear even if already granted.
- none — Return error if interaction is required (silent auth).

POST

/api/oauth/token

Exchanges the authorization code for an access token.

curl -X POST https://auth.pt-bks.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_CALLBACK_URL" \
  -d "code_verifier=YOUR_VERIFIER" (if PKCE)

GET

/api/oauth/userinfo

Retrieves information about the authenticated user.

Requires Authorization: Bearer ACCESS_TOKEN header.

Available Scopes

openid: Returns sub.
email: Returns email, email_verified.
profile: Returns name, picture.
external_data: Returns legacy JSON data if one exists.

Response Example (with external_data)

{
  "sub": "user_id_uuid",
  "name": "Ahmad Rizal",
  "email": "ahmad.rizal@pt-bks.com",
  "external_data": {
    "employee_id": "130",
    "department": "IT",
    "legacy_token": "..."
  }
}