cups-oauth(1)

Name

cups-oauth - interact with an oauth/openid authorization server

Synopsis

cups-oauth --help
cups-oauth --version
cups-oauth [ -a OAUTH-URI ] [ -s SCOPE(S) ] authorize [RESOURCE]
cups-oauth [ -a OAUTH-URI ] clear [RESOURCE]
cups-oauth [ -a OAUTH-URI ] get-access-token [RESOURCE]
cups-oauth [ -a OAUTH-URI ] get-client-id
cups-oauth [ -a OAUTH-URI ] [ -s SCOPE(S) ] get-device-grant [RESOURCE]
cups-oauth [ -a OAUTH-URI ] get-device-token [RESOURCE] DEVICE-CODE
cups-oauth [ -a OAUTH-URI ] get-metadata [NAME]
cups-oauth [ -a OAUTH-URI ] get-user-id [RESOURCE] [NAME]
cups-oauth [ -a OAUTH-URI ] set-access-token [RESOURCE] TOKEN
cups-oauth [ -a OAUTH-URI ] set-client-data CLIENT-ID CLIENT-SECRET

Description

The cups-oauth utility interacts with an OAuth/OpenID authorization server. Authorizations are often linked to a resource (a printer URI, web page URL, etc.)

Options

The following options are recognized by cups-oauth:

--help
Show program usage.

--version
Show the CUPS version.

-a OAUTH-URI
Specifies the OAuth/OpenID authorization server URL.

-s SCOPE(S)
Specifies a space-delimited list of scope names to use when authorizing access. The default is to request authorization for all supported OpenID scopes.

Sub-Commands

authorize [RESOURCE]
Starts an authorization workflow with the default web browser. If a resource URI is specified, the authorization is specific to that resource. The access token is send to the standard output on success.

clear [RESOURCE]
Clears any authorization for the specified resource or for all resources if no resource URI is supplied.

get-access-token [RESOURCE]
Output the current, unexpired access token, if any, to the standard output.

get-client-id
Output the client ID string, if any, to the standard output.

get-device-grant [RESOURCE]
Gets a device authorization grant and outputs the device code, user code, and web page to the standard output.

get-device-token [RESOURCE] DEVICE-CODE
Waits for device authorization to complete and outputs the device access token to the standard output.

get-metadata [NAME]
Get the OAuth/OpenID authorization server metadata and send it to the standard output. If NAME is specified, the output is just the value for the named metadata.

get-user-id [RESOURCE] [NAME]
Get the OpenID user ID information and send it to the standard output. If NAME is specified, the output is just the named claim from the user ID.

set-access-token [RESOURCE] TOKEN
Set the access token (which is sometimes also called an API key) for the specified resource or for all resources.

set-client-data CLIENT-ID CLIENT-SECRET
Set the client ID string and secret for an OAuth/OpenID authorization server.

Environment Variables

The CUPS_OAUTH_URI environment variable sets the default OAuth/OpenID authorization server URL.

The CUPS_OAUTH_SCOPES environment variable sets the default OAuth/OpenID scopes as a space-delimited list.

Notes

CUPS uses a redirect URI of "http://127.0.0.1/" for all authorization on the local system.

Examples

Register a client ID and secret for the OAuth server at "https://oauth.example.com/":

     cups-oauth -a https://oauth.example.com/ set-client-data CLIENT-ID CLIENT-SECRET

Save an access token (sometimes called an application or API key) for the OAuth server at "https://oauth.example.com/":

     cups-oauth -a https://oauth.example.com/ set-access-token TOKEN

Authorize against the OAuth server at "https://oauth.example.com/" using your web browser:

     cups-oauth -a https://oauth.example.com/ authorize

See Also

cups(1)

Copyright

Copyright © 2025 by OpenPrinting.