Bondy Connect

Appearance

OAuth2 Token ​

OAuth2 tokens in Bondy are JWT (JSON Web Tokens) that can be used to authenticate HTTP API requests via the HTTP API Gateway.

Description ​

OAuth2-based authentication allows clients to present an authentication token when making HTTP requests to Bondy's HTTP API Gateway. A token itself is issued, refreshed, and revoked through the HTTP endpoints below, not a WAMP procedure. The identities behind these tokens — API clients and resource owners — and administrative revocation of their refresh tokens are managed through WAMP procedures instead; see OAuth2 Administration.

Important Considerations ​

Requires HTTP API Gateway ​

OAuth2 tokens are obtained and used exclusively through Bondy's HTTP API Gateway. If you are primarily using WAMP for communication, consider using Ticket authentication instead, which works natively with WAMP.

Requires Base Authentication Method ​

A token request authenticates the resource owner, and the API client, with the password method. When defining Sources for a user who obtains tokens, add two rules:

  1. One for oauth2, used when the token is presented
  2. One for password, used when the token is requested

Every token, refresh and revoke request also carries the API client's credentials as Authorization: Basic, and a revoke request names the token type in token_type_hint. See Protecting an HTTP API with OAuth2 for complete requests.

HTTP Endpoints ​

OAuth2 tokens are managed through the following HTTP endpoints:

Token Endpoint ​

  • Default Path: /oauth/token
  • Purpose: Obtain or refresh an OAuth2 token
  • Methods: POST
  • Grant Types Supported:
    • password - Resource Owner Password Credentials flow
    • client_credentials - Client Credentials flow
    • refresh_token - Token refresh flow

Revoke Endpoint ​

  • Default Path: /oauth/revoke
  • Purpose: Revoke an existing OAuth2 refresh token
  • Methods: POST

The endpoint revokes refresh tokens only. A request with token_type_hint=access_token gets a 200 response and revokes nothing. An access token stays valid until it expires.

Configuration ​

OAuth2 authentication is configured in the HTTP API Gateway Specification for each API. The token and revoke endpoints can be customized if needed.

Example configuration:

json
{
  "oauth2": {
    "flow": "resource_owner_password_credentials",
    "token_path": "/oauth/token",
    "revoke_token_path": "/oauth/revoke",
    "type": "oauth2"
  }
}

Usage Example ​

Obtaining a Token ​

bash
curl --location --request POST 'http://localhost:18080/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic <base64_encoded_client_credentials>' \
  --data-urlencode 'username=myuser' \
  --data-urlencode 'password=mypassword' \
  --data-urlencode 'grant_type=password'

Using the Token ​

Once obtained, the token can be used in the Authorization header for subsequent API requests:

bash
curl --location --request GET 'http://localhost:18080/api/resource' \
  --header 'Authorization: Bearer <access_token>'

Refreshing a Token ​

bash
curl --location --request POST 'http://localhost:18080/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic <base64_encoded_client_credentials>' \
  --data-urlencode 'refresh_token=<refresh_token>' \
  --data-urlencode 'grant_type=refresh_token'

Revoking a Token ​

bash
curl --location --request POST 'http://localhost:18080/oauth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic <base64_encoded_client_credentials>' \
  --data-urlencode 'token=<refresh_token>' \
  --data-urlencode 'token_type_hint=refresh_token'

Token Structure ​

OAuth2 tokens in Bondy are JWTs (JSON Web Tokens) that contain:

  • Standard JWT claims: iss, sub, aud, exp, iat
  • Bondy-specific claims: User identity, realm information, and authorization scopes

The tokens are cryptographically signed and can be verified by the HTTP API Gateway.

Security Considerations ​

  1. Transport Security: Always use HTTPS in production to protect tokens in transit
  2. Token Storage: Store tokens securely on the client side
  3. Token Expiration: Tokens have a configurable expiration time; implement token refresh logic
  4. Token Revocation: Implement token revocation for logout and security incidents

See Also ​