OAuth tokens: disabled users, client binding, refresh token lifetime and token sources (6.0.15)
From 6.0.15 on, the OAuth layer of the REST API (/api/... and the token endpoint POST /api/auth/v1/oauth/token)
checks a token's user, ends refresh tokens after a lifetime, and no longer takes an access token from the address.
What changes
- Disabled and locked users. An access token, an authorization code and a refresh token work only while their
user is enabled and not locked by failed logins (
eZUser::isEnabledAfterFailedLogin()), the rule personal API keys and password sign-in already apply. Before, a user disabled in the administration kept full REST access with a token issued earlier, and kept getting fresh access tokens with the refresh token. A resource request with such a token gets401; the token endpoint answersinvalid_grantwith the description it gives for a code or refresh token of another client, so the answer does not tell the token holder that the account is disabled or locked. - Client binding. A code or refresh token is redeemed only by the client it was issued to. The client identifiers are compared as strings in constant time, and an empty identifier never matches.
- Refresh token lifetime. A refresh token used to be valid for ever. It now lasts
RefreshTokenTTL(30 days by default) from the refresh that issued it; an expired one is deleted and the request answersinvalid_grant, so the application sends the user throughoauth/authorizeagain.ezprest_tokenstores one expiry per row, the access token's, and no issue time. The issue time is derived asexpirytime - TokenTTL, so there is no schema change. ChangingTokenTTLtherefore shifts the deadline of refresh tokens issued before by the difference.- Every refresh issues a new refresh token, so the lifetime slides from the last refresh; an absolute limit from the first authorization would need a new column.
- A row stored without an expiry (
expirytime=0) is refused whileRefreshTokenTTLis set.
- Token sources. The
Authorizationheader (Bearer <token>orOAuth <token>) is always read. Theoauth_tokenparameter of a POST form body (RFC 6750, section 2.2) is read unlessAllowTokenInBody=disabled. Theoauth_tokenquery parameter (?oauth_token=..., RFC 6750, section 2.3) is no longer read unlessAllowTokenInQuery=enabled: a token in the address ends up in web server and proxy access logs, the browser history andRefererheaders. - Missing parameters. The token endpoint names every missing parameter ("Missing grant_type, client_id
parameters."). Before, only a missing last parameter was refused, and a request without
client_idwent on to look up a clientnullwith "Undefined array key" warnings. A parameter posted as a list (client_id[]=...) is refused asinvalid_request("Invalid client_id parameter.") instead of reaching the database layer as an array. - Diagnosis. A request whose token comes only in the address while
AllowTokenInQueryis off writes a notice to the debug output ("An OAuth token in the query string (oauth_token) was ignored ..."). - Not changed. The REST API, SOAP, WebDAV and
expservicesare not guarded by two-factor sign-in by default; this change adds no second factor to the token endpoint or to resource requests. The second factor is asked where the user signs in on the web form, whichoauth/authorizeuses.
Settings
rest.ini [OAuthSettings]:
| Setting | Default | Meaning |
|---|---|---|
RefreshTokenTTL | 2592000 | lifetime of a refresh token in seconds, from the refresh that issued it; 0 = no expiry, as before |
AllowTokenInQuery | disabled | enabled also takes ?oauth_token= from the address, as before |
AllowTokenInBody | enabled | take oauth_token from a POST form body when there is no Authorization header |
What to do when you upgrade
- A client that sends the token in the address (
?oauth_token=...) now gets401. Change it to sendAuthorization: Bearer <token>. Where that cannot be done at once, setAllowTokenInQuery=enabledinsettings/override/rest.ini.append.phpfor the time it takes. The command line sample clientphp_ezrestcallof theezprestapipackage sends the token in the address for some calls and needs the header too. - An application that kept a refresh token for longer than 30 days without using it has to send its user through
oauth/authorizeagain. SetRefreshTokenTTL=0to keep the earlier behaviour. - Nothing changes for active users of applications that refresh within the lifetime.
Code and tests
ezpOauthUtility(kernel/private/rest/classes/oauth/utility.php):userMayUseToken(),clientMatches(),refreshTokenExpired(),tokenSources();ezpOauthFilter::run()(oauth_filter.php);ezpRestOauthTokenController::missingParams()andinvalidParams()(controllers/oauth_token.php).tests/tests/kernel/private/oauth/ezpOauthGrantChecksTest.phpandtests/tests/kernel/classes/rest/ezpOauthUtilityTokenTest.php(no database).