Page MenuHomePhabricator

Define "Create app" flow
Closed, ResolvedPublic


The create app flow allow users to register a client with the API Portal.

Status: Getting feedback on proposed form

Screen Shot 2020-05-19 at 7.26.20 AM.png (755×619 px, 44 KB)
Screen Shot 2020-05-15 at 2.05.06 PM.png (814×1 px, 74 KB)
  • User must be logged in to the API Portal with a Wikimedia account
  • User must have the mwoauthproposeconsumer right (Automatically granted to all users)
  • User must have a confirmed email address
Form fields

All fields are required.

  • App name
  • App description
  • Account type
    • Selecting "Developer account" unchecks the owner-only client option and submits "authorization_code", "refresh_token", and "client_credentials" as the grant types
    • Selecting "Bot account" checks the owner-only client option and removed the "Return URL" field
  • Return URL (only required for developer accounts)
  • Permissions
    • Read: applies basic, highvolume, viewdeleted, and oversight grants
    • Read/Write: applies basic, highvolume, viewdeleted, oversight, and createeditmovepage grants
  • "Client is confidential" checkbox
  • User agreement checkbox
Map between rights used by the MediaWiki REST API and grant types
RightGrant Type(s)Handler(s)
editeditpage, createeditmovepage, and othersCreationHandler/UpdateHandler
Map between fields on Meta and fields in the API Portal
FieldRequiredValDBDefaultAPI Portal
NameYesnameoarc_namenoneUser-entered, required
DescriptionYesdescriptionoarc_descriptionnoneUser-entered, required
Owner-only client checkbox“This consumer is for use only by [Username]”User-entered, required
Callback URLYescallbackUrloarc_callback_urlnoneUser-entered, not required for owner-only clients
Confidential checkboxNooauth2IsConfidentialoarc_oauth2_is_confidentialYesUser-entered, required
OAuth2 Grant TypesNooauth2GrantTypesoarc_oauth2_allowed_grants[“authorization_code”,”refresh_token”]User-entered, either:auth code flow ( "authorization_code", "refresh_token") or client credentials flow: ("client_credentials")
GrantsYesgrantsoarc_grants(some basic permissions)User-entered. Read: basic, highvolume, viewdeleted, oversight. Read/Write: basic, highvolume, viewdeleted, oversight, createeditmovepage
AgreementYesdeveloperAgreementoarc_developer_agreementNone (user must agree)User-entered, include as-is
EmailYesemailoarc_emailWiki emailOmit and revert to default
WikiYeswikioarc_wiki*Omit and revert to default
Grant Type“Types of grants being requested:”YesgranttypeN/AnormalOmit and default to “Request authorization for specific permissions.”
VersionYesversionoarc_version1.0Omit and revert to default
Allowed IP rangesOmit and revert to default
OAuth versionOmit, always 2.0
Callback prefix checkboxYes“Allow consumer to specify a callback in requests and use "callback" URL above as a required prefix.”Omit and revert to checked. Doesn’t apply to OAuth 2.0.

Event Timeline

Currently, new Wikimedia accounts are not automatically placed into the mwoauthproposeconsumer group. How should we handle this? Do users have to be in this group on Meta specifically?

See: T142317: Creating an owner-only consumer should not require an autoconfirmed account/T213760: Rethink autoconfirmed requirement for OAuth

Are you sure this is right? I see on that 'Users' (anyone with a registered account) has the mwoauthproposeconsumer right, there is no mwoauthproposeconsumer group.

As per this config in CentralAuth

	// Create some local accounts as soon as the global registration happens
	$wgCentralAuthAutoCreateWikis = [ 'loginwiki', 'metawiki' ];

Anyone creating a SUL account anywhere should be automatically created an account on meta, and therefore, they can create OAuth consumers etc

I note T213760: Rethink autoconfirmed requirement for OAuth was only recently resolved, so was this documented elsewhere against something that is now out of date?

Screenshot 2020-04-09 at 02.58.34.png (1×1 px, 323 KB)

apaskulin updated the task description. (Show Details)

Thanks, @Reedy! This is super helpful. I've updated the task with this info.

Thanks, @Reedy! This is super helpful. I've updated the task with this info.

Cool! Just when I had read the task and wanted to confirm I wasn't missing something obvious, or as seems to be the case, something that had already been resolved recently and just got overlooked :)

Aha, I just noticed the link to (that you just removed) which shows that page is out of date. Will fix it

apaskulin triaged this task as Medium priority.Apr 9 2020, 4:22 PM
apaskulin renamed this task from Create app to Define "Create app" flow.Apr 17 2020, 10:49 PM

Per discussion outside this task, it is desirable for the API Portal to present a simplified set of Grant Type choices to developers registering OAuth clients. However, because OAuth clients created from the API Portal are indistinguishable in the database from clients created via the OAuth extension, it is necessary to map this simplified list to the full list presented at

Clients are assigned grant types, which map to individual rights. The available grant types, and associated rights, are listed at

For more info on how these are configured, see, see:$wgGrantPermissionGroups$wgGrantPermissions

And note that grant permission configuration is distinct from group permissions:$wgGroupPermissions

Regarding grant types, assigned to clients, I found the following rights in use by existing endpoints:

RightGrant Type(s)Handler(s)
editeditpage, createeditmovepage, and othersCreationHandler/UpdateHandler

Some of these rights are not requirements for the endpoint to provide data. For example, the PageHistoryCountHandler and PageHistoryHandler will still provide data even if the requesting OAuth client does not have any grant type beyond "basic". However, they will provide less data than the web interface for users that have expanded rights on their wiki account. This is because the effective rights seen by a handler are the minimal intersection of the OAuth client rights and the wiki user rights.

It is possible that returned data is affected by additional rights that I did not find. For example, if a handler calls function foo(), which calls function bar(), which calls function baz(), which checks for a right, my investigation would not have uncovered that.

It was proposed (outside this task) to offer two options when registering an OAuth client:

  • Read
  • Read/Write

If we offer only those two options, and we do not want to restrict users accessing wikis via OAuth clients to a smaller dataset than they see in the web interface, the mappings would be:

  • Read: basic, highvolume, viewdeleted, oversight
  • Read/Write: all the above, plus something that includes the "edit" right (createeditmovepage seems like a good choice, and allows for expansion to API endpoints that we're likely to create).

If we don't want all OAuth clients to be capable of more powerful grant types like "oversight", we could define additional choices (but still fewer than available on meta). Again, note that just because an OAuth client has a grant type allowing it to do something, that doesn't mean any user of that client can do that thing. The user must also have a wiki account with that right.

Thanks, @BPirkle! The rights you suggested sound good to me. @eprodromou and @CCicalese_WMF, how does this look to you?

apaskulin updated the task description. (Show Details)

Looks good to me. Thanks for the analysis, @BPirkle.