Linode Login Client

The LinodeLoginClient is the primary interface to the login.linode.com OAuth service, and only needs to be used if writing an OAuth application. For an example OAuth application, see Install on Linode, and for a more comprehensive overview of OAuth, read our OAuth guide.

LinodeLoginClient class

Your interface to Linode’s OAuth authentication server.

class linode_api4.LinodeLoginClient(client_id, client_secret, base_url='https://login.linode.com', ca_path=None)

__init__(client_id, client_secret, base_url='https://login.linode.com', ca_path=None)

Create a new LinodeLoginClient. These clients do not make any requests on creation, and can safely be created and thrown away as needed.

For complete usage information, see the OAuth guide.

Parameters:

• client_id (str) – The OAuth Client ID for this client.
• client_secret (str) – The OAuth Client Secret for this client.
• base_url (str) – The URL for Linode’s OAuth server. This should not be changed.
• ca_path (str) – The path to the CA file to use for requests run by this client.

expire_token(token)

Given a token, makes a request to the authentication server to expire it immediately. This is considered a responsible way to log out a user. If you simply remove the session your application has for the user without expiring their token, the user is not _really_ logged out.

Parameters:token (str) – The OAuth token you wish to expire Returns:If the expiration attempt succeeded. Return type:bool Raises:ApiError – If the expiration attempt failed.

finish_oauth(code)

Given an OAuth Exchange Code, completes the OAuth exchange with the authentication server. This should be called once the user has already been directed to the login_uri, and has been sent back after successfully authenticating. For example, in Flask, this might be implemented as a route like this:

@app.route("/oauth-redirect")
def oauth_redirect():
    exchange_code = request.args.get("code")
    login_client = LinodeLoginClient(client_id, client_secret)

    token, scopes = login_client.finish_oauth(exchange_code)

    # store the user's OAuth token in their session for later use
    # and mark that they are logged in.

    return redirect("/")

Parameters:code (str) – The OAuth Exchange Code returned from the authentication server in the query string. Returns:The new OAuth token, and a list of scopes the token has, when the token expires, and a refresh token that can generate a new valid token when this one is expired. Return type:tuple(str, list) Raises:ApiError – If the OAuth exchange fails.

generate_login_url(scopes=None, redirect_uri=None)

Generates a url to send users so that they may authenticate to this application. This url is suitable for redirecting a user to. For example, in Flask, a login route might be implemented like this:

@app.route("/login")
def begin_oauth_login():
    login_client = LinodeLoginClient(client_id, client_secret)
    return redirect(login_client.generate_login_url())

Parameters:

• scopes (list) – The OAuth scopes to request for this login.
• redirect_uri (str) – The requested redirect uri. The login service enforces that this is under the registered redirect path.

Returns:

The uri to send users to for this login attempt.

Return type:

str

refresh_oauth_token(refresh_token)

Some tokens are generated with refresh tokens (namely tokens generated through an OAuth Exchange). These tokens may be renewed, or “refreshed”, with the auth server, generating a new OAuth Token with a new (later) expiry. This method handles refreshing an OAuth Token using the refresh token that was generated at the time of its issuance, and returns a new OAuth token and refresh token for the same client and user.

Parameters:refresh_token (str) – The refresh token returned for the OAuth Token we are renewing. Returns:The new OAuth token, and a list of scopes the token has, when the token expires, and a refresh token that can generate a new valid token when this one is expired. Return type:tuple(str, list) Raises:ApiError – If the refresh fails..

OAuth Scopes

When requesting authorization to a user’s account, OAuth Scopes allow you to specify the level of access you are requesting.

class linode_api4.login_client.OAuthScopes

Represents the OAuth Scopes available to an application. In general, an application should request no more scopes than it requires. This class should be treated like a Enum, and used as follows:

required_scopes = [OAuthScopes.Linodes.all, OAuthScopes.Domains.read_only]

Lists of OAuth Scopes are accepted when calling the generate_login_url method of the LinodeLoginClient.

All contained enumerations of OAuth Scopes have two levels, “read_only” and “read_write”. “read_only” access grants you the ability to get resources and of that type, but not to change, create, or delete them. “read_write” access allows to full access to resources of the requested type. In the above example, you are requesting access to view, modify, create, and delete Linodes, and to view Domains.

class Account

Access to the user’s account, including billing information, tokens management, user management, etc.

class Clients

An enumeration.

class Domains

Access to Domains

class Events

Access to a user’s Events

class Firewalls

Access to Firewalls

class IPs

Access to IPs and networking managements

class LKE

Access to LKE Endpoint

class Linodes

Access to Linodes

class Longview

Access to Longview

class NodeBalancers

Access to NodeBalancers

class ObjectStorage

Access to Object Storage

class StackScripts

Access to private StackScripts

class Tickets

Access to view, open, and respond to Support Tickets

class Tokens

An enumeration.

class Users

An enumeration.

class Volumes

Access to Block Storage Volumes

all = *

If necessary, an application may request all scopes by using OAuthScopes.all