Introduction

The DRACOON API is protected by OAuth. 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

 

Authorization code flow example

This flow is for applications where users don't want to share their credentials with an application. Instead of requesting authorization directly, the application directs the user to an authorization server where the user authorizes the application. Afterward, the user is redirected back to the application with an authorization code that can be used to retrieve an access/refresh token.

See: https://tools.ietf.org/html/rfc6749#section-4.1

1Create/build authorization URL

The 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 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

2Open authorization URL in the browser

To allow a user to authorize your app, he/she must be sent to the authorization server. (The URL should be opened in the system browser. An integrated web view is not recommended.)

3Receive 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 this:

- Web app: https://app.example.com/oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

(- Mobile app: app-example://oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz)

4Exchange code for tokens

To get an access/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&
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"
}

5Call API

After you have received the access token, you can call a DRACOON API. The access token must be supplied in the authorization header. (The refresh token can be used to retrieve a new access token. See: https://tools.ietf.org/html/rfc6749#section-6)

Request:

GET /api/v4/nodes HTTP/1.1
Host: dracoon.team
Authorization: Bearer b1b735fe-4767-3299-9b37-594f512cf553

 

Password flow example

This flow is for application/scripts where there is a high degree of trust. It allows the application/script to directly get access/refresh tokens with the user's credentials.

Notice: Neither RADIUS nor OpenID Connect credentials can be used here. Furthermore, this flow does not work if two-step authentication is used.

See: https://tools.ietf.org/html/rfc6749#section-4.1

1Retrieve tokens

To get an access/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=password&
username=example-username&
password=example-password

Response:

Status: 200 OK
Content-Type: application/json

{
  "access_token": "35feb1b7-47b3-6799-3297-f55942cf5153",
  "token_type": "bearer",
  "refresh_token": "47a2f3a6-f4b5-7641-9fe9-ba011df7425b",
  "expires_in": 3599,
  "scope": "all"
}

2Call API

After you have received the access token, you can call a DRACOON API. The access token must be supplied in the authorization header. (The refresh token can be used to retrieve a new access token. See: https://tools.ietf.org/html/rfc6749#section-6)

Request:

GET /api/v4/nodes HTTP/1.1 
Host: dracoon.team Authorization: Bearer 35feb1b7-47b3-6799-3297-f55942cf5153

If you are looking for further examples, this blog post shows you how to use the password flow with PowerShell, Java, and cURL.