Jump to content

Extension:CentralAuth/API

From mediawiki.org

Authentication

[edit]

CentralAuth has no login or signup API of its own (the standard clientlogin and signup APIs can be used for that, with the same parameters as MediaWiki core login), but it 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:

  • When using the action API, via the centralauthtoken parameter. When making a POST CORS request to the action API, the parameter must be part of the preflight request and thus it must be in the URL, not the POST data.
  • When using the REST API, via a Authorization: CentralAuthToken <token> header.

You can use the mediawiki.ForeignApi ResourceLoader module to handle this for you.

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


action=centralauthtoken

(main | centralauthtoken)

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

Returns a token that can be use to authenticate API requests on other wikis. For action API requests, put it in the centralauthtoken GET parameter. For REST API requests, add an Authorization: CentralAuthToken {token} header. In MediaWiki frontend logic, you can use the mediawiki.ForeignApi ResourceLoader module.


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


User management

[edit]

list=globalallusers (agu)

(main | query | globalallusers)

Enumerate all global users.

Specific parameters:
Other general parameters are available.
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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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
aguexcludenamed

Exclude users of named accounts.

Type: boolean (details)
aguexcludetemp

Exclude users of temporary accounts.

Type: boolean (details)
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]



meta=globaluserinfo (gui)

(main | query | globaluserinfo)

Show information about a global user.

Specific parameters:
Other general parameters are available.
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, Temporary user 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=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.

Specific parameters:
Other general parameters are available.
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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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): AWB, convenient-discussions
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]



action=createlocalaccount

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

Forcibly create a local account. The central account must exist.

Specific parameters:
Other general parameters are available.
username

User to create the local account for.

This parameter is required.
reason

Reason for creating the local account.

token

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

This parameter is required.
Example:
Forcibly create a local account for User:Example.
api.php?action=createlocalaccount&username=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

Hide or lock (or unhide or unlock) a global user account.

Specific parameters:
Other general parameters are available.
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. This is used to detect edit conflicts. The value of hidden must be an empty string if not hidden or the strings lists or suppressed. The value of locked must be 1 for locked, 0 for unlocked. Examples: 2128506:LeeSmith::0; 3839611:VandalGoblin:suppressed:1.

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]



meta=globalrenamestatus (grs)

(main | query | globalrenamestatus)

Show information about global renames that are in progress.

Specific parameter:
Other general parameters are available.
grsuser

User that is being renamed. Can be either their old name or new name.

Type: user, by any of username, IP, Temporary user, IP range and interwiki name (e.g. "prefix>ExampleName")
Example:
Get information about the current global user
api.php?action=query&meta=globalrenamestatus [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.

Specific parameters:
Other general parameters are available.
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]


Group management

[edit]

list=globalgroups (ggp)

(main | query | globalgroups)

Enumerate all global groups.

Specific parameter:
Other general parameters are available.
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]



list=wikisets (ws)

(main | query | wikisets)

Enumerate all wiki sets.

Specific parameters:
Other general parameters are available.
wsfrom

The name of the wiki set to start from.

wsprop

What pieces of information to include:

type
Opt-in based (includes only specified wikis) or opt-out based (includes all wikis except specified).
wikisincluded
The wikis that are included in this wiki set.
wikisnotincluded
The wikis that are not included in this wiki set.
Values (separate with | or alternative): type, wikisincluded, wikisnotincluded
wslimit

How many wiki sets to return.

Type: integer or max
The value must be between 1 and 500.
Default: 10
wsorderbyname

Order results by name.

Type: boolean (details)
Examples:
List wiki sets
api.php?action=query&list=wikisets [open in sandbox]
Show wiki sets with types
api.php?action=query&list=wikisets&wsprop=type&wslimit=200 [open in sandbox]


Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:CentralAuth/API&oldid=6154328"