Bye X-SDS-Auth-Token, hello OAuth 2.0

As most of you know, almost all of the DRACOON API endpoints require authentication before you can make any requests. Currently, there are two ways to authenticate a user and authorize a client:

OAuth 2.0 (open standard)
X-SDS-Auth-Token (proprietary)

With this blog post we would like to inform you that the X-SDS-Auth-Token has been deprecated with the server release 4.13 (and the corresponding API endpoints /auth/login and /user/account/logout) as a way to authenticate requests to the DRACOON API. Support for X-SDS-Auth-Token ends on September 30, 2020. This means that if your company currently uses the X-SDS-Auth-Token in custom applications or scripts developed by you or your partners, we highly encourage you to switch to OAuth 2.0 now in order to ensure that your applications remain fully functional.

Note that this change only affects custom applications; all official Dracoon apps are already OAuth-based with no changes required.

Background Information

DRACOON introduced the X-SDS-Auth-Token in 2014 as a simple and convenient way to make authenticated requests as a user. Since then, many of our customers developed third-party applications and integrations based on DRACOON. To better support our customers with their integration efforts, we added support for OAuth 2.0 in 2016.

OAuth 2.0 is an open standard and widely used authorization protocol. One of the key features of OAuth 2.0 is the support for two different authorization flows:

Three-legged OAuth flow
Two-legged OAuth flow

The three-legged OAuth flow allows a resource owner to give a client access to a resource server without sharing credentials. This interactive flow is particularly important for third-party applications where users don't want to share their credentials with an app. Users are redirected to a trustworthy authentication interface (usually a web page) and the app is only provided with an authentication token that allows using the service (grant types: Authorization Code and Implicit).

The two-legged OAuth is mainly for non-interactive cases where there is no concept of a user (grant type: Password).

DRACOON supports both three-legged and two-legged authorization flows. Please note that for the two-legged flow, authentication is only possible with a local account (login with username/password), active directory, and non-interactive RADIUS. Neither interactive RADIUS nor OpenID Connect can be used because these authentication methods require user interaction and the two-legged OAuth flow is a non-interactive flow. For the three-legged OAuth flow, all authentication methods are available.

Migration from X-SDS-Auth-Token to OAuth 2.0

The following steps will help you to check if you need to update your integration.

First, check if your application uses the X-SDS-Auth-Token. You can do so by verifying whether you call the API endpoint /auth/login to authenticate your users. If that is the case, the following table can help you chose an OAuth flow for your integration:

	Interactive	Non-Interactive
Secure Storage for OAuth Credentials Available (such as Desktop or Mobile Apps)	Three-legged OAuth: Authorization Code Flow	Two-legged OAuth: Password Flow
No Secure Storage Available (such as Client-side Web Applications)	Three-legged OAuth: Implicit Flow	-

To use OAuth for custom applications or scripts, you first need to register a new OAuth app as follows:

Open a browser and login to your DRACOON account (Role Config Manager is required for further configuration steps).
Go to System settings → Apps.
Click the button Add App to create a new OAuth app. For two-legged OAuth, at least the grant type password must be selected. For three-legged OAuth, at least one of the grant types implicit and authorization code must be selected.
Click Save all and note Client ID and Client Secret for your client

If you want to register an OAuth app programmatically, you can find further instructions here: https://support.dracoon.com/hc/de/articles/115003832605-OAuth-2-0-Client-Registration

Next, we will give you some examples how to use the new OAuth app to authenticate with DRACOON.

Examples

Three-legged Authentication Examples

A detailed walkthrough for three-legged OAuth using DRACOON can be found here: https://support.dracoon.com/hc/de/articles/360001329825-OAuth-2-0-Example

Additionally, in our Java SDK you can also find a detailed example of three-legged OAuth using authorization code flow: https://github.com/dracoon/dracoon-java-sdk/blob/master/example/src/main/java/com/dracoon/sdk/example/OAuthExamples.java

Two-legged Authentication Examples

This section shows how to login using two-legged authentication and how to use the access token to call API endpoints that require authentication. This is probably the preferred method to authenticate simple scripts.

cURL

Auth Request to Obtain Access Token

curl -X POST \ https://[DRACOON_HOSTNAME]/oauth/token \ -H 'Authorization: Basic [BASE64_ENCODED [CLIENT_ID]:[CLIENT_SECRET]]' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=password&username=[USER_NAME]&password=[PASSWORD]'

Use of Access Token to Get Account Information

curl -X GET \
  https://[DRACOON_HOSTNAME]/api/v4/user/account \
  -H 'Authorization: Bearer [ACCESS_TOKEN]'
 PowerShellAuth Request to Obtain Access Token
$Uri = "https://[DRACOON_HOSTNAME]/oauth/token"
$Username = "[USER_NAME]"
$Password = "[PASSWORD]"
$ClientId = "[CLIENT_ID]"
$ClientSecret = "[CLIENT_SECRET]"
$Base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $ClientId,$ClientSecret)))
$Body = @{ "grant_type" = "password"; "username" = $Username; "password" = $Password }
$Response = Invoke-WebRequest -URI $Uri -Method Post -ContentType "application/x-www-form-urlencoded" -Body $Body -Headers @{Authorization=("Basic {0}" -f $Base64AuthInfo)}
$Content = ConvertFrom-Json $Response.content
$Token = $Content.access_token
Write-Output $Token
 
Use of Access Token to Get Account Information
$Uri = "https://[DRACOON_HOSTNAME]/api/v4/user/account"
$Token = "[ACCESS_TOKEN]"
$Response = Invoke-WebRequest -URI $Uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Bearer {0}" -f $Token)}
$Content = ConvertFrom-Json $Response.content
Write-Output $Content
 
 
Java (Using OkHttp Library)Auth Request to Obtain Access Token
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=password&username=[USER_NAME]&password=[PASSWORD]");
Request request = new Request.Builder()
  .url("https://[DRACOON_HOSTNAME]/oauth/token")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "Basic [Base64([CLIENT_ID]:[CLIENT_SECRET])]")
  .build();
Response response = client.newCall(request).execute();
 
Use of Access Token to Get Account Information
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
  .url("https://[DRACOON_HOSTNAME]/api/v4/user/account")
  .get()
  .addHeader("Authorization", "Bearer [ACCESS_TOKEN]")
  .build();
Response response = client.newCall(request).execute();
 
 

Need Further Help?

OAuth 2.0 is a widely used open standard protocol and OAuth support libraries are available for almost all programming languages. By making OAuth the only authentication and authorization framework, our developers and integrators greatly benefit from relying on a widely used standard.

If you have existing applications or scripts that still use the X-SDS-Auth-Token, you can find further resources of information below. Additionally, you may join our community for further help.