You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All scopes for the OAuth security model (defined below) apply to this
40
+
All scopes for the OAuth security model ([defined below](#o-auth)) apply to this
41
41
security model as well.
42
42
43
43
### Authentication
@@ -47,19 +47,49 @@ info:
47
47
| **HTTP Authorization Scheme** | bearer |
48
48
49
49
## OAuth
50
+
If you only need to access the Linode API for personal uses,
51
+
we recommend that you create a [personal access token](#personal-access-token).
52
+
If you're designing an application that can authenticate with an arbitrary Linode user, then
53
+
you should use the OAuth 2.0 workflows presented in this section.
50
54
51
-
The OAuth workflow is a three-step process to authenticate a User before an
52
-
application can start making API calls on the User's behalf. If all you need
53
-
is a Personal Access Token, feel free to skip ahead to the next section.
55
+
For a more detailed example of an OAuth 2.0 implementation, see our guide on [How to Create an OAuth App with the Linode Python API Library](https://www.linode.com/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
54
56
55
-
First, the User visits the application's website and is directed to log with
56
-
Linode. The User is then redirected to Linode's authentication server and
57
-
presented the scope levels the application is requesting. Once the User
58
-
accepts the request for access, we redirect them back to the application's
59
-
specified redirect URI with an access code.
57
+
Before you implement OAuth in your application, you first need to create an OAuth client. You can do this [with the Linode API](https://developers.linode.com/api/v4/account-oauth-clients/#post) or [via the Cloud Manager](https://cloud.linode.com/profile/clients):
60
58
61
-
Once the User has logged in to Linode and you have received an exchange code,
62
-
you will need to exchange that access code for an Authorization token. You
59
+
- When creating the client, you'll supply a `label` and a `redirect_uri` (referred to as the Callback URL in the Cloud Manager).
60
+
- The response from this endpoint will give you a `client_id` and a `secret`.
61
+
- Clients can be public or private, and are private by default. You can choose to make the client public when it is created.
62
+
- A private client is used with applications which can securely store the client secret (that is, the secret returned to you when you first created the client). For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation.
63
+
- A public client is used with applications where the client secret is not guaranteed to be secure. For example, a native app running on a user's computer may not be able to keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public client.
64
+
- Public and private clients follow different workflows, as described below.
65
+
66
+
### OAuth Workflow
67
+
68
+
The OAuth workflow is a series of exchanges between your third-party app and Linode. The workflow is used
69
+
to authenticate a User before an application can start making API calls on the User's behalf.
70
+
71
+
Notes:
72
+
73
+
- With respect to the diagram in [section 1.2 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-1.2), login.linode.com (referred to in this section as the *login server*)
74
+
is the Resource Owner and the Authorization Server; api.linode.com (referred to here as the *api server*) is the Resource Server.
75
+
- The OAuth spec refers to the private and public workflows listed below as the [authorization code flow](https://tools.ietf.org/html/rfc6749#section-1.3.1) and [implicit flow](https://tools.ietf.org/html/rfc6749#section-1.3.2).
76
+
77
+
| PRIVATE WORKFLOW | PUBLIC WORKFLOW |
78
+
|------------------|------------------|
79
+
| 1. The User visits the application's website and is directed to login with Linode. | 1. The User visits the application's website and is directed to login with Linode. |
80
+
| 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. | 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. |
81
+
| 3. The user logs into the login server with their username and password. | 3. The user logs into the login server with their username and password. |
82
+
| 4. The login server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The login server redirects the user back to your application with an OAuth `access_token` embedded in the redirect URL's hash. This is temporary and expires in 2 hours. No `refresh_token` is issued. Therefore, once the `access_token` expires, a new one will need to be issued by having the user log in again. |
83
+
| 5. The application issues a POST request (*see below*) to the login server with the exchange code, `client_id`, and the client application's `client_secret`. | |
84
+
| 6. The login server responds to the client application with a new OAuth `access_token` and `refresh_token`. The `access_token` is set to expire in 2 hours. | |
85
+
| 7. The `refresh_token` can be used by contacting the login server with the `client_id`, `client_secret`, and `refresh_token` to get a new OAuth `access_token` and `refresh_token`. The new `access_token` is good for another 2 hours, and the new `refresh_token`, can be used to extend the session again by this same method. | |
86
+
87
+
### OAuth Private Workflow - Additional Details
88
+
89
+
The following information expands on steps 5 through 7 of the private workflow:
90
+
91
+
Once the User has logged into Linode and you have received an exchange code,
92
+
you will need to trade that exchange code for an `access_token` and `refresh_token`. You
63
93
do this by making an HTTP POST request to the following address:
64
94
65
95
```
@@ -71,11 +101,11 @@ info:
71
101
72
102
| PARAMETER | DESCRIPTION |
73
103
|-----------|-------------|
74
-
| client_id | Your app's client ID |
75
-
| client_secret | Your app's client secret |
76
-
| code | The code you just received from the redirect |
104
+
| client_id | Your app's client ID. |
105
+
| client_secret | Your app's client secret. |
106
+
| code | The code you just received from the redirect. |
77
107
78
-
You'll get a reponse like this:
108
+
You'll get a response like this:
79
109
80
110
```json
81
111
{
@@ -86,18 +116,20 @@ info:
86
116
}
87
117
```
88
118
89
-
Included in the reponse is `access_token`. With this token, you can proceed to make
119
+
Included in the reponse is an `access_token`. With this token, you can proceed to make
90
120
authenticated HTTP requests to the API by adding this header to each request:
| **AuthorizationCode Oauth Flow** | **Authorization URL:** https://login.linode.com/oauth/authorize<br />**Token URL:** https://login.linode.com/oauth/token<br />**Scopes:**<br /><ul><li>`account:read_only` - Allows access to GET information about your Account.</li><li>`account:read_write` - Allows access to all endpoints related to your Account.</li><li>`domains:read_only` - Allows access to GET Domains on your Account.</li><li>`domains:read_write` - Allows access to all Domain endpoints.</li><li>`events:read_only` - Allows access to GET your Events.</li><li>`events:read_write` - Allows access to all endpoints related to your Events.</li><li>`images:read_only` - Allows access to GET your Images.</li><li>`images:read_write` - Allows access to all endpoints related to your Images.</li><li>`ips:read_only` - Allows access to GET your ips.</li><li>`ips:read_write` - Allows access to all endpoints related to your ips.</li><li>`linodes:read_only` - Allows access to GET Linodes on your Account.</li><li>`linodes:read_write` - Allow access to all endpoints related to your Linodes.</li><li>`lke:read_only` - Allows access to GET LKE Clusters on your Account.</li><li>`lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.</li><li>`longview:read_only` - Allows access to GET your Longview Clients.</li><li>`longview:read_write` - Allows access to all endpoints related to your Longview Clients.</li><li>`nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.</li><li>`nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.</li><li>`stackscripts:read_only` - Allows access to GET your StackScripts.</li><li>`stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.</li><li>`volumes:read_only` - Allows access to GET your Volumes.</li><li>`volumes:read_write` - Allows access to all endpoints related to your Volumes.</li></ul><br />|
| **Scopes** | <ul><li>`account:read_only` - Allows access to GET information about your Account.</li><li>`account:read_write` - Allows access to all endpoints related to your Account.</li><li>`domains:read_only` - Allows access to GET Domains on your Account.</li><li>`domains:read_write` - Allows access to all Domain endpoints.</li><li>`events:read_only` - Allows access to GET your Events.</li><li>`events:read_write` - Allows access to all endpoints related to your Events.</li><li>`images:read_only` - Allows access to GET your Images.</li><li>`images:read_write` - Allows access to all endpoints related to your Images.</li><li>`ips:read_only` - Allows access to GET your ips.</li><li>`ips:read_write` - Allows access to all endpoints related to your ips.</li><li>`linodes:read_only` - Allows access to GET Linodes on your Account.</li><li>`linodes:read_write` - Allow access to all endpoints related to your Linodes.</li><li>`lke:read_only` - Allows access to GET LKE Clusters on your Account.</li><li>`lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.</li><li>`longview:read_only` - Allows access to GET your Longview Clients.</li><li>`longview:read_write` - Allows access to all endpoints related to your Longview Clients.</li><li>`nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.</li><li>`nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.</li><li>`stackscripts:read_only` - Allows access to GET your StackScripts.</li><li>`stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.</li><li>`volumes:read_only` - Allows access to GET your Volumes.</li><li>`volumes:read_write` - Allows access to all endpoints related to your Volumes.</li></ul><br />|
0 commit comments