Extension:CentralAuth/API

From MediaWiki.org
Jump to: navigation, search

Tokens[edit]

CentralAuth introduces three new tokens, centralauthtoken, setglobalaccountstatus and deleteglobalaccount.

centralauthtoken[edit]

CentralAuth allows your code to authenticate on the foreign wiki as the user currently logged in on the local wiki using a central authentication token (centralauthtoken). Using those, one can make API calls to any wiki participating in the same single sign-on system, guaranteeing that the same associated account will be used for actions on both wikis even if the user is not logged in on the foreign wiki (doesn't have a session cookie for that domain).

First, acquire a token using action=centralauthtoken request to the local wiki. A token is only valid for a single request, and will become invalid after 10 seconds.

Then, pass the token to any CORS request to the foreign wiki via the centralauthtoken parameter. When making a POST CORS request, the parameter must be part of the preflight request and thus it must be in the URL, not the POST data. You can use the mediawiki.ForeignApi ResourceLoader module to handle this for you.

setglobalaccountstatus[edit]

The preferred method to obtain a setglobalaccountstatus token depends on the MediaWiki version:

deleteglobalaccount[edit]

The preferred method to obtain a deleteglobalaccount token depends on the MediaWiki version:




list=globalallusers (agu)

(main | query | globalallusers)
  • This module requires read rights.
  • Source: CentralAuth
  • License: GPL-2.0

Enumerate all global users.

Parameters:
agufrom

The user name to start enumerating from.

aguto

The user name to stop enumerating at.

aguprefix

Search for all users that begin with this value.

agudir

Direction to sort in.

One of the following values: ascending, descending
Default: ascending
agugroup

Limit users to given global groups.

Values (separate with | or alternative): OTRS-member, abusefilter-helper, apihighlimits-requestor, captcha-exempt, delete-global, founder, global-bot, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombudsman, recursive-export, staff, steward, sysadmin, wmf-ops-monitoring, wmf-researcher
aguexcludegroup

Exclude users in given global groups.

Values (separate with | or alternative): OTRS-member, abusefilter-helper, apihighlimits-requestor, captcha-exempt, delete-global, founder, global-bot, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombudsman, recursive-export, staff, steward, sysadmin, wmf-ops-monitoring, wmf-researcher
aguprop

What pieces of information to include:

lockinfo
Whether the user account is locked.
groups
Lists global groups that the user is in. This uses more server resources and may return fewer results than the limit.
existslocally
Adds the information if the user exists locally.
Values (separate with | or alternative): lockinfo, groups, existslocally
agulimit

How many total user names to return.

No more than 500 (5,000 for bots) allowed.
Type: integer or max
Default: 10



list=globalgroups (ggp)

(main | query | globalgroups)
  • This module requires read rights.
  • Source: CentralAuth
  • License: GPL-2.0

Enumerate all global groups.

Parameter:
ggpprop

What pieces of information to include.

Values (separate with | or alternative): rights



meta=globaluserinfo (gui)

(main | query | globaluserinfo)
  • This module requires read rights.
  • Source: CentralAuth
  • License: GPL-2.0

Show information about a global user.

Parameters:
guiuser

User to get information about. Defaults to the current user.

Type: user name
guiprop

Which properties to get:

groups
Get a list of global groups this user belongs to.
rights
Get a list of global rights this user has.
merged
Get a list of merged accounts.
unattached
Get a list of unattached accounts.
editcount
Get the user's global edit count.
Values (separate with | or alternative): groups, rights, merged, unattached, editcount



action=centralauthtoken

(main | centralauthtoken)
  • This module requires read rights.
  • Source: CentralAuth
  • License: GPL-2.0

Fetch a centralauthtoken for making an authenticated request to an attached wiki.


Example:
Fetch a centralauthtoken
api.php?action=centralauthtoken [open in sandbox]



action=deleteglobalaccount

(main | deleteglobalaccount)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: CentralAuth
  • License: GPL-2.0

Delete a global user.

Parameters:
user

User to delete.

This parameter is required.
reason

Reason for deleting the user.

token

A "deleteglobalaccount" token retrieved from action=query&meta=tokens

This parameter is required.



action=setglobalaccountstatus

(main | setglobalaccountstatus)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: CentralAuth
  • License: GPL-2.0

Set a global user's status.

Parameters:
user

User to change the status of.

This parameter is required.
locked

Change whether this user is locked or not.

One of the following values: Can be empty, or lock, unlock
hidden

Change whether this user is not hidden, hidden from lists, or suppressed.

One of the following values: Can be empty, or lists, suppressed
reason

Reason for changing the user's status.

statecheck

Optional MD5 of the expected current <username>:<hidden>:<locked>, to detect edit conflicts. Set <locked> to 1 for locked, 0 for unlocked.

token

A "setglobalaccountstatus" token retrieved from action=query&meta=tokens

This parameter is required.



action=globaluserrights

(main | globaluserrights)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: CentralAuth
  • License: GPL-2.0

Add/remove a user to/from global groups.

Parameters:
user

Global user name.

Type: user name
userid

Global user ID.

Type: integer
add

Add the user to these global groups.

Values (separate with | or alternative): OTRS-member, abusefilter-helper, apihighlimits-requestor, captcha-exempt, delete-global, founder, global-bot, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombudsman, recursive-export, staff, steward, sysadmin, wmf-ops-monitoring, wmf-researcher
remove

Remove the user from these global groups.

Values (separate with | or alternative): OTRS-member, abusefilter-helper, apihighlimits-requestor, captcha-exempt, delete-global, founder, global-bot, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombudsman, recursive-export, staff, steward, sysadmin, wmf-ops-monitoring, wmf-researcher
reason

Reason for the change.

Default: (empty)
token

A "userrights" token retrieved from action=query&meta=tokens

For compatibility, the token used in the web UI is also accepted.

This parameter is required.
tags

This parameter is currently unused.

Values (separate with | or alternative):
Examples:
Add user FooBot to global group "bot", and remove from global groups "sysop" and "bureaucrat"
api.php?action=userrights&user=FooBot&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]
Add the global user with ID 123 to global group "bot", and remove from global groups "sysop" and "bureaucrat"
api.php?action=userrights&userid=123&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]