OAuth2 Administration

An OAuth2 API client and a resource owner are both, underneath, an ordinary RBAC user — Bondy just forces membership in a reserved group when creating one: api_clients for a client, resource_owners for a resource owner. There is no separate storage or entity type; bondy.oauth2.client.add, for instance, is bondy.user.add with the api_clients group appended to whatever groups you passed. The result, and the username/groups/meta fields you can set on it, are exactly the user type.

This page covers the bondy.oauth2.* procedures that manage these identities and their refresh tokens administratively. The client-facing token issuance and revocation flow — the /oauth/token and /oauth/revoke HTTP endpoints a resource owner's application actually calls — is covered in OAuth2 Token.

Procedures

Name	URI
Add an API client	bondy.oauth2.client.add
Update an API client	bondy.oauth2.client.update
Delete an API client	bondy.oauth2.client.delete
Add a resource owner	bondy.oauth2.resource_owner.add
Update a resource owner	bondy.oauth2.resource_owner.update
Delete a resource owner	bondy.oauth2.resource_owner.delete
Revoke a refresh token	bondy.oauth2.token.revoke
Revoke every refresh token for a resource owner	bondy.oauth2.token.revoke_all

Add an API client

bondy.oauth2.client.add(realm_uri, data) -> user

Creates an API client: an RBAC user in the api_clients group, authenticated with a client_id/client_secret pair instead of a human password.

Call

Positional Args

0uri

The URI of the realm to add the client to.

1dict

The client data — see below.

data:

client_idstring

The client identifier. Becomes the underlying user's username.

client_secretstring

Required. Becomes the underlying user's password.

groupsarray[undefined]

Additional group names to also add the user to. api_clients is always added regardless of what is passed here; defaults to [].

Keyword Args

None.

Result

Positional Results

0user

The new client, as a user object.

Keyword Results

None.

Errors

• bondy.error.already_exists: when client_id is already in use.
• bondy.error.missing_required_value: when client_secret is not provided.

Update an API client

bondy.oauth2.client.update(realm_uri, client_id, info) -> user

Updates an existing API client.

Call

Positional Args

0uri

The URI of the realm the client belongs to.

1string

The client's client_id (its username).

2dict

The fields to update. client_secret (the password) and groups are both optional here; when groups is given, api_clients is re-added to it regardless of what is passed, the same as on creation. Omitting groups entirely leaves the client's current groups untouched.

Keyword Args

None.

Result

Positional Results

0user

The updated client, as a user object.

Keyword Results

None.

Errors

• wamp.error.no_such_principal: when client_id does not exist.

Delete an API client

bondy.oauth2.client.delete(realm_uri, client_id) -> ok

Deletes an API client.

Call

Positional Args

0uri

The URI of the realm the client belongs to.

1string

The client's client_id (its username).

Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

• wamp.error.no_such_principal: when no user with the given name exists in the realm.

Add a resource owner

bondy.oauth2.resource_owner.add(realm_uri, data) -> user

Creates a resource owner: an RBAC user in the resource_owners group, representing the end-user (or system account) an OAuth2 token is issued on behalf of.

Call

Positional Args

0uri

The URI of the realm to add the resource owner to.

1dict

The resource owner data. Beyond groups (optional, defaults to [] — resource_owners is always added regardless of what is passed), this accepts the same fields as bondy.user.add, e.g. username and password.

Keyword Args

None.

Result

Positional Results

0user

The new resource owner, as a user object.

Keyword Results

None.

Errors

• bondy.error.already_exists: when the username is already in use.
• bondy.error.missing_required_value: when a required value is not provided.

Update a resource owner

bondy.oauth2.resource_owner.update(realm_uri, username, info) -> user

Updates an existing resource owner.

Call

Positional Args

0uri

The URI of the realm the resource owner belongs to.

1string

The resource owner's username.

2dict

The fields to update. groups is optional; when given, resource_owners is re-added to it regardless of what is passed. Omitting groups entirely leaves the current groups untouched.

Keyword Args

None.

Result

Positional Results

0user

The updated resource owner, as a user object.

Keyword Results

None.

Errors

• wamp.error.no_such_principal: when username does not exist.

Delete a resource owner

bondy.oauth2.resource_owner.delete(realm_uri, username) -> ok

Deletes a resource owner.

Call

Positional Args

0uri

The URI of the realm the resource owner belongs to.

1string

The resource owner's username.

Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

• wamp.error.no_such_principal: when no user with the given name exists in the realm.

Revoke a refresh token

bondy.oauth2.token.revoke(realm_uri, client_id, refresh_token) -> ok

Revokes one refresh token by its value.

client_id is accepted but not used

The client_id argument is validated for presence (spec-shape compatibility) but does not scope the revocation — only refresh_token identifies which token is revoked.

Call

Positional Args

0uri

The URI of the realm the token belongs to.

1string

Accepted but not used — see the tip above.

2string

The refresh token to revoke.

Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

None documented. The call succeeds even when refresh_token does not exist — there is nothing to revoke, which is treated the same as having revoked it.

Revoke every refresh token for a resource owner

bondy.oauth2.token.revoke_all(realm_uri, client_id, authid) -> ok

Revokes every refresh token issued to authid on the realm.

client_id is accepted but not used

As with bondy.oauth2.token.revoke, client_id doesn't scope the revocation to tokens issued to that particular client — every token belonging to authid, issued through any client, is revoked.

Call

Positional Args

0uri

The URI of the realm the tokens belong to.

1string

Accepted but not used — see the tip above.

2string

The resource owner's username (authid) whose tokens are revoked.

Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

None documented. The call succeeds even when authid has no outstanding tokens.

Not implemented

These reserved bondy.oauth2.* URIs do not perform an operation:

• bondy.oauth2.client.get, bondy.oauth2.client.list — deprecated; they raise bondy.error.deprecated_procedure. List API clients as users in the api_clients group instead.
• bondy.oauth2.resource_owner.get, bondy.oauth2.resource_owners.list — deprecated in the same way, for resource owners (note the plural owners in the list URI).
• bondy.oauth2.token.lookup — deprecated; raises bondy.error.deprecated_procedure.

Client/resource owner lifecycle topics are reserved, not published

bondy.oauth2.client.added/.deleted/.updated and bondy.oauth2.resource_owner.added/.deleted/.updated are reserved URIs that Bondy never actually publishes to. Since a client or resource owner is an RBAC user, subscribe to bondy.user.added/.updated/.deleted instead if you need to observe these changes.

See also

• OAuth2 Token — the HTTP-side token issuance and revocation flow these identities authenticate against.
• User — the underlying entity, and the full external user shape.
• Group — the api_clients and resource_owners groups these identities are forced into.