Authentication Tokens (REST API)

Intro

Please review the information on the Authentication Tokens (Overview) page to get a general idea of what authentication tokens are and how they can be used. This page aims to describe how to create the tokens via the REST API.

Resource

Authentication tokens are created by sending an XML body to the following resource: You’ll need to authenticate via HTTP-Basic authentication with a user that has the ‘Auth token’ role.

  POST /auth_token.xml

You need to include the following header, or else Rails will not convert your posted XML into parameters used by PowerDNS on Rails:

  Content-type: text/xml

It will return a simple XML representation of the token, containing only the token itself, the URL to use and the expiry time.

Request

The body of the request must look something like the following:

<auth_token>
      <domain>name</domain>
      <expires_at>RFC822 timestamp</expires_at>
      <policy>token policy</policy>
      <allow_new>true/false</allow_new>
      <remove>true/false<remove>
      <!-- record tag for each record -->
      <record>...</record>
      <record>...</record>
      <!-- protect_type tag for each type to be protected -->
      <protect_type>...</protect_type>
      <protect_type>...</protect_type>
      <!-- protect tag for each record to protect -->
      <protect>...</protect>
</auth_token>

Tags can be omitted from the request, then the default policies (see Authentication Tokens (Overview)) will be applied.

domain

The name of the domain that the token is for:

<domain>example.com</domain>

expires_at

Defaults to one hour from creation, expects the following format

<expires_at>Wed Feb 18 12:31:29 +0200 2009</expires_at>

policy

Default policy to apply, either deny or allow

<policy>allow</policy>

allow_new

Can new records be added? (false or true)

<allow_new>true</allow_new>

remove

Can existing records be removed? (false or true)

<remove>true</remove>

record (can be added as many times as needed)

Each record tag is a simple colon-delimited string value, indicating the record can be managed by the token. The line format is full record name : record type

<record>example.com:A</record>
<record>www.example.com:A</record>

protect (can be added as many times as needed)

Each protect tag is a simple colon-delimited string value, indicating the record can’t be managed by the token. The line format is full record name : record type, just like the record tag.

<protect>example.com:MX</protect>
<protect>mail.example.com:A</protect>

protect_type (can be added as many times as needed)

Add as many times as needed to protect all records of that type from being changed, added or removed.

<protect_type>MX</protect_type>
<protect_type>SRV</protect_type>

Responses

A successful call to the resource will give back the following results:

<token>
  <url>http://host/token/token-value</url>
  <auth_token>token-value</auth_token>
  <expires>Expiry time</expires>
</token>

Anything else should be a text message indicating the error, and an accompanying HTTP status code.

Using the generated authentication token

In the returned token XML there is a full url to be used for logging in with the token. If the url doesn’t suite your need, you can just send your user to a different base url where PowerDNS on Rails is installed, and append “/token/XYZ” to the base url (where XYZ is the value in the auth_token tag.

Sample tokens

You can generate some sample tokens for review and testing by running the following commands:

rake db:seed
rake tokens

The task will generate sample XML requests in the tmp/ directory and give you some hints on how to use curl to generate authentication tokens. Here is a sample curl line:

curl -X POST --basic -u token:secret -d @tmp/token_read_only.xml. -H "Content-type: text/xml" http://localhost:3000/auth_token.xml

You’ll get the raw XML response back with everything you need.