Extension:CentralAuth/API

From mediawiki.org

Tokens[edit]

CentralAuth introduces three new tokens:

  • centralauthtoken
  • setglobalaccountstatus
  • 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.


api.php?action=centralauthtoken [try in ApiSandbox]
Result
{
    "centralauthtoken": {
        "centralauthtoken": "138aa2df87605832076ac89c207f37ed1c3b01b"
    }
}

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.

api.php?action=query&meta=userinfo&centralauthtoken=138aa2df87605832076ac89c207f37ed1c3b01b [try in ApiSandbox]


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)

Enumerate all global users.

Parameters:
agufrom

The username to start enumerating from.

aguto

The username 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): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
aguexcludegroup

Exclude users in given global groups.

Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, 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): existslocally, groups, lockinfo
agulimit

How many total usernames to return.

Type: integer or max
The value must be between 1 and 500.
Default: 10
Examples:
List global users
api.php?action=query&list=globalallusers [open in sandbox]
Show some information for global users starting from "ABC"
api.php?action=query&list=globalallusers&agufrom=ABC&aguprop=lockinfo|groups|existslocally [open in sandbox]

list=globalgroups (ggp)

(main | query | globalgroups)

Enumerate all global groups.

Parameter:
ggpprop

What pieces of information to include.

Values (separate with | or alternative): rights
Examples:
List global groups
api.php?action=query&list=globalgroups [open in sandbox]
Show global groups with the rights they grant
api.php?action=query&list=globalgroups&ggpprop=rights [open in sandbox]

meta=globaluserinfo (gui)

(main | query | globaluserinfo)

Show information about a global user.

Parameters:
guiuser

User to get information about. If guiuser and guiid both are omitted, it defaults to the current user.

Type: user, by any of username and interwiki name (e.g. "prefix>ExampleName")
guiid

Global user ID to get information about. If guiuser and guiid both are omitted, it defaults to the current user.

Type: integer
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): editcount, groups, merged, rights, unattached
Examples:
Get information about the current global user
api.php?action=query&meta=globaluserinfo [open in sandbox]
Get information about global user Example
api.php?action=query&meta=globaluserinfo&guiuser=Example&guiprop=groups|merged|unattached [open in sandbox]

action=centralauthtoken

(main | centralauthtoken)

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-or-later

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.
Example:
Delete the global account for User:Example
api.php?action=deleteglobalaccount&user=Example&reason=Because+I+can [open in sandbox]

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-or-later

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 the global users list, 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 <userid>:<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.
Examples:
Lock the global account for User:Example with reason "Spam"
api.php?action=setglobalaccountstatus&user=Example&locked=lock&hidden=&reason=Spam [open in sandbox]
Unlock and suppress the global account for User:Example with reason "I can"
api.php?action=setglobalaccountstatus&user=Example&locked=unlock&hidden=suppressed&reason=I%20can [open in sandbox]

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-or-later

Add/remove a user to/from global groups.

Parameters:
user

Global username.

Type: user, by any of username and user ID (e.g. "#12345")
userid
Deprecated.

Global user ID.

Type: integer
add

Add the user to these global groups.

Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
expiry

Expiry timestamps. May be relative (e.g. 5 months or 2 weeks) or absolute (e.g. 2014-09-18T12:34:56Z). If only one timestamp is set, it will be used for all groups passed to the add parameter. Use infinite, indefinite, infinity, or never for a never-expiring user group.

Separate values with | or alternative.
Maximum number of values is 50 (500 for clients that are allowed higher limits).
Default: infinite
remove

Remove the user from these global groups.

Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, 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): possible vandalism, repeating characters
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]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:CentralAuth/API&oldid=5820306"