API Explorer

OAuth Standards and OBP

OAuth Standards and OBP

OAuth decides how an application gets a token. It leaves the access rules inside an API to the API itself. So OBP's Roles, Entitlements and Scopes are OBP's own, and they work alongside these standards:

Standard What it covers How OBP uses it
OAuth 2.0, client credentials grant (RFC 6749, section 4.4) An application gets a token for itself, with no user. An application acting as itself uses this grant. OBP-API then checks its Consumer's Scopes.
Dynamic Client Registration (RFC 7591) Standard fields for a client, including grant_types, scope and token_endpoint_auth_method. A Consumer's grant types use the standard's field and values. See here.
JWT access tokens (RFC 9068) In a token an application got for itself, sub is the application's own client id. OBP-API recognises such a token when sub equals the client id (azp).
Client authentication with a private key (RFC 7523) and with a certificate (RFC 8705) An application proves who it is with a signed key or a client certificate, instead of a shared secret. A Consumer can hold a JWKS URI and a client certificate for this.
OAuth security best practice (RFC 9700) and OAuth 2.1 PKCE for every login, and no password grant. DirectLogin sends a username and password, much like the password grant. Prefer an OAuth2 login for people, and client credentials for applications.
Token exchange (RFC 8693) Says explicitly that one party acts on behalf of another (the act claim). OBP does not use it today.

Permissions for people and permissions for applications

Identity providers usually keep two kinds of permission apart. Microsoft Entra ID, for example, calls them delegated permissions and application permissions:

  • A delegated permission says what an application may do for a person who is logged in.
  • An application permission says what an application may do as itself. An administrator grants it.

In OBP, a person's Role comes from their Entitlement. An application acting as itself uses its Consumer's Scopes. With require_scopes_for_all_roles or require_scopes_for_listed_roles, a Consumer's Scope also limits which Roles people can use through that application.

OBP Scopes and OAuth scopes

In standard OAuth, the identity provider writes the granted scopes into the token, and the API reads them there. OBP-API instead looks up a Consumer's Scopes in its own records. OAuth allows this, and it lets OBP work with any identity provider. So an OBP Scope is not the same thing as the scope in a token, although they share a name.

One setting connects the two. With oauth2.keycloak.source_of_truth=true, OBP-API copies the roles in a Keycloak token into the Consumer's Scopes.