Project

Profile

Help

Using the Redmine REST API with OAuth2 at Planio » History » Sprint/Milestone 8

Jan Schulz-Hofen, 08/19/2020 02:46 PM

1 1 Jens Krämer
# Using the Redmine REST API with OAuth2 at Planio
2
3
As you might know, Planio comes with a powerful [REST API](https://plan.io/api)
4
which covers almost all aspects of Planio. If you were working with the API
5
before, you know that in order to use it, you had to generate an API key and
6
use that to make authorized API calls.
7
8 7 Jan Schulz-Hofen
{{>toc}}
9
10 1 Jens Krämer
This approach, while relatively easy to work with, has a few drawbacks:
11
12
- Each API key is tied to a single user account, meaning that your application
13
  will always act as this user when interacting with Planio.
14
- There is no way to restrict what an application can do - an API key always
15
  grants it's user the same set of permissions that the user it belongs to has.
16
17
**OAuth 2** introduces a mechanism to restrict applications to a certain
18
*scope*. Further, users need to explicitly grant access to an application
19
before it may act on their behalf. When doing so, they will be informed about
20
the scope, that is, what data the application is going to have access to. In
21
the same way, a user may later decide to revert this decision and revoke access
22
for an application at any time.
23
24
Let's look a minimal example for you to try out.
25
26 8 Jan Schulz-Hofen
## Create an OAuth Application in your Planio Account
27 1 Jens Krämer
28
In order to use OAuth with Planio, you have to create an **Application** first.
29
This will generate a unique identifier for your API client, as well as a
30
secret. Both will be used to authenticate your application when it's
31
communicating with Planio.
32
33
Go to *Your Avatar* → **Administration** → **Applications** and click **New
34
Application**.
35
36 3 Jan Schulz-Hofen
{{figure(Creating a new OAuth application)
37 1 Jens Krämer
![Creating a new OAuth application](new_application%402x.png)
38 3 Jan Schulz-Hofen
}}
39 1 Jens Krämer
40
You may enter any descriptive **Name** for your application. This will be shown later to users when they are about to authorize your app.
41
42
The **Redirect URI** is the location where Planio will redirect a user's
43
browser to after they granted access to your application. The redirect will
44
carry a `code` query parameter which holds an authorization code that's needed
45
to retrieve the actuall access token later.
46
47
For now, enter `urn:ietf:wg:oauth:2.0:oob` as the **Redirect URI**. This
48
special value tells Planio that this application is not reachable over the
49
web. Instead, the authorization code will be simply displayed to the user for
50
manual transfer to the client application requesting access.
51
52
Below, in the **Scopes** section, you decide what your application will be
53
allowed to do. Don't be too generous here, and restrict the set of granted
54
permissions to the minimum necessary. For now, just select the
55
**Add issues** permission and hit **Save** below.
56
57
You will be redirected to a page that lists the details you just entered, along
58
with the application's **Application Id** and **Secret**.
59
60 8 Jan Schulz-Hofen
## Build the OAuth 2 client
61 1 Jens Krämer
62
We'll be using the [Ruby language](https://www.ruby-lang.org/en/) and the [OAuth2 Gem](https://rubygems.org/gems/oauth2) for this.
63
64
Of the various *OAuth Flows* that exist, Planio currently supports the most commonly used *Authorization Code* flow. Please refer to [the OAuth 2 spec](http://tools.ietf.org/html/rfc6749#section-4.1) for more technical details. Any applications you create are considered *confidential* in the sense of the spec, which means that the application secret may not be disclosed. If you require support for a *public* application (for example a mobile app or an application running exclusively in the browser), please contact us.
65
66 8 Jan Schulz-Hofen
### Set up the client
67 1 Jens Krämer
68
~~~ruby
69
require 'oauth2'
70
71
client_id     = '...' # your application id
72
client_secret = '...' # your application's secret
73
redirect_uri  = '...' # your application's redirect uri
74
site          = "https://your-domain.plan.io/" # your planio account's URL
75
76
client = OAuth2::Client.new(client_id, client_secret, site: site)
77
~~~
78
79
80 8 Jan Schulz-Hofen
### Authorize the Application
81 1 Jens Krämer
82
If you were building a real application, you would now send your user to some
83
URL where they are prompted to grant access. Usually you don't have to
84
construct these URLs yourself, but your OAuth 2 client library will do it for
85
you:
86
87
~~~ruby
88
client.auth_code.authorize_url(redirect_uri: redirect_uri, scope: 'add_issues')
89
# => https://your-domain.plan.io/oauth/authorize?response_type=code&client_id=...&redirect_uri=...
90
~~~
91
92
As `scope`, list all permissions you are planning to use. You cannot request
93
any permissions that have not been selected when the application was registered in Planio, but
94
you can choose to select less. Here, we only request the `add_issues` permission in order to be able to add issues.
95
96
Open this URL in your browser and you will be prompted for authorization,
97
listing the permissions you are applying for. 
98
99 4 Jan Schulz-Hofen
{{figure(Authorizing an OAuth 2 Application)
100 1 Jens Krämer
![Authorizing an OAuth 2 Application](authorize_app%402x.png)
101 4 Jan Schulz-Hofen
}}
102 1 Jens Krämer
103
Click **Authorize**, and take
104
note of the **Authorization code**. If you had entered a real **Redirect URI**
105
earlier, you would have been redirected to that URI now, with the authorization
106
code as query parameter.
107
108
109
110 8 Jan Schulz-Hofen
### Retrieve an Access Token
111 1 Jens Krämer
112
With the authorization code you can now request an access token from your
113
Planio account like this:
114
115
~~~ruby
116
code = '...' # the authorization code from above
117
token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
118
# => <#OAuth2::AccessToken ...>
119
~~~
120
121
If at this point you get an error, it is most likely that the code, which is
122
only valid for a short time, already has expired.
123
124 8 Jan Schulz-Hofen
### Use the Access Token for API requests
125 1 Jens Krämer
126
If everything worked out, you may now use the token to do requests against
127
Planio's REST API.
128
129
~~~ruby
130
JSON.parse token.get('/users/current.json').body
131
~~~
132
133
This will give you some basic information about the user you are acting as. Of
134
course at this point you can stop using the OAuth 2 client and use any other
135
HTTP client to query Planio's API. Let's try with
136
[RestClient](https://github.com/rest-client/rest-client):
137
138
~~~ruby
139
# get the actual token string from the oauth lib
140
token_value = token.token
141
# compile the issue data
142
payload = { issue: { subject: "Hello world" } }
143
# specify the token in the Authorization HTTP header
144
headers = { Authorization: "Bearer #{token_value}"}
145
RestClient.post "https://your-domain.plan.io/projects/some-project/issues.json", payload, headers
146
# => <RestClient::Response 201 "{\"issue\":{\"...">
147
~~~
148
149
And that's it! You successfully created an issue with authorization obtained via OAuth 2.
150
151 8 Jan Schulz-Hofen
## A word on security
152 1 Jens Krämer
153
As the developer of an OAuth 2 client application it is your responsibility to keep the application secret as well as any auth and refresh tokens you obtain safe - any unintended disclosure may lead to unauthorized access to your users' data.
154
155 8 Jan Schulz-Hofen
## Manage your Authorized Applications
156 1 Jens Krämer
157
Click on *Your Avatar* → **My Account** → **Authorized Applications** in order
158
to see the list of applications that currently have access to your account.
159
160 5 Jan Schulz-Hofen
{{figure(List of authorized apps)
161 6 Jan Schulz-Hofen
![List of authorized apps](authorized_apps%402x.png)
162 5 Jan Schulz-Hofen
}}
163 1 Jens Krämer
164
Clicking **Revoke** will invalidate any access or refresh token that the application might still possess and remove it from the list.