Introduction:
DRACOON API access authorization can in addition to the X-Sds-Auth-Token also be done via an OAuth Access Token.
For information about OAuth, see: https://oauth.net/2, https://tools.ietf.org/html/rfc6749
Before you can start to use OAuth you have to create an OAuth client. Article OAuth 2.0 Client Registration describes how to create an OAuth client.
OAuth Endpoints:
- Authorization endpoint: | https:/[host]/oauth/authorize |
- Token endpoint: | https://[host]/oauth/token |
Example:
The following example uses the Authorization Code grant. (See: https://tools.ietf.org/html/rfc6749#section-4.1)
1. Create/build authorization URL
Following parameters must be added to the authorization URL:
- response_type=code
- client_id=example-client (Your client ID.)
- redirect_uri=https://app.example.com/oauth/cb (Your registered redirect URI.)
- state=xyz (A string which you can use to map authorization request and callback.)
Result:
https://dracoon.team/oauth/authorize?response_type=code&
client_id=example-client&
state=xyz &
redirect_uri=https%3A%2F%2Fapp%2Eexample%2Ecom%2Foauth%2Fcb
2. Open authorization URL in browser
To allow a user to authorize your app, he/she must be send to the authorization server. (The URL should be opened in the system's browser. A integrated web view is not recommended.)
3. Receive authorization callback and extract code
After the user has authorized your app, you receive a callback to the registered redirect URI which contains the authorization code. It might look like:
- Web App: https://app.example.com/oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
(- Mobile App: app-example://oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz)
4. Exchange code for tokens
To get an access and refresh token you must use the token endpoint.
Request:
(You must use your client ID and client secret to authenticate. See: https://en.wikipedia.org/wiki/Basic_access_authentication)
POST /oauth/token HTTP/1.1
Host: dracoon.team
Authorization: Basic ZXhhbXBsZS1jbGllbnQ6ZXhhbXBsZS1zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
client_id=example-client&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2Fapp%2Eexample%2Ecom%2Foauth%2Fcb
Response:
Status: 200 OK
Content-Type: application/json
{
"access_token": "b1b735fe-4767-3299-9b37-594f512cf553",
"token_type": "bearer",
"refresh_token": "2f3a47a6-b5f4-4761-e99f-badf7011425b",
"expires_in": 3599,
"scope": "all"
}
5. Call API
After you have received the access token you can call a API. The access token must be supplied in the authorization header.
Request:
GET /api/v4/nodes HTTP/1.1
Host: dracoon.team
Authorization: Bearer b1b735fe-4767-3299-9b37-594f512cf553
Comments
0 comments
Please sign in to leave a comment.