open-vault/website/source/docs/auth/radius.html.md

layout	page_title	sidebar_current	description
docs	Auth Backend: RADIUS	docs-auth-radius	The "radius" auth backend allows users to authenticate with Vault using an existing RADIUS server.

Auth Backend: RADIUS

Name: radius

The "radius" auth backend allows users to authenticate with Vault using an existing RADIUS server that accepts the PAP authentication scheme.

The mapping of users to Vault policies is managed by using the users/ path.

Optionally, a configurable set of policies can be granted to all users that can successfully authenticate but are not registered in the users/ path.

Authentication

Via the CLI

$ vault auth -method=userpass -path=radius \
    username=foo \
    password=bar

Via the API

The endpoint for the login is auth/radius/login/<username>.

The password should be sent in the POST body encoded as JSON.

$ curl $VAULT_ADDR/v1/auth/radius/login/mitchellh \
    -d '{ "password": "foo" }'

Alternatively a POST request can be made to auth/radius/login/ with both username and password sent in the POST body encoded as JSON.

The response will be in JSON. For example:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": [
      "admins"
    ],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}

Configuration

First, you must enable the RADIUS auth backend:

$ vault auth-enable radius
Successfully enabled 'radius' at 'radius'!

Now when you run vault auth -methods, the RADIUS backend is available:

Path       Type      Description
token/     token     token based credentials
radius/    radius

To use the radius auth backend, it must first be configured with connection details for your RADIUS server. The configuration options are detailed below in the API docs. Configuration is written to auth/radius/config.

To use the "radius" auth backend, an operator must configure a mapping between users and policies. An example is shown below. Use vault path-help for more details.

$ vault write auth/radius/users/mitchellh \
    policies=admins
...

The above creates a new mapping for user "mitchellh" that will be associated with the "admins" policy.

Alternatively, Vault can assign a configurable set of policies to any user that successfully authenticates with the RADIUS server but has no explicit mapping in the users/ path. This is done through the unregistered_user_policies configuration parameter.

API

/auth/radius/config

POST

Description

Configures the connection parameters and shard secret used to communicate with RADIUS

Method

POST

URL

`/auth/radius/config`

Parameters

• host required The RADIUS server to connect to. Examples: `radius.myorg.com`, `127.0.0.1`
• port optional The UDP port where the RADIUS server is listening on. Defaults is 1812
• secret required The RADIUS shared secret
• unregistered_user_policies optional A Comma-Separated list of policies to be granted to unregistered users
• dial_timeout optional Number of second to wait for a backend connection before timing out. Defaults is 10
• read_timeout optional Number of second to wait for a backend response before timing out. Defaults is 10
• nas_port optional The NAS-Port attribute of the RADIUS request. Defaults is 10

Returns

`204` response code.

/auth/radius/users/[username]

POST

Description

Registers a new user and maps a set of policies to it. This path honors the distinction between the `create` and `update` capabilities inside ACL policies.

Method

POST

URL

`/auth/radius/users/`

Parameters

• username required Username for this user.

• policies optional Comma-separated list of policies. If set to empty string, only the `default` policy will be applicable to the user.

Returns

`204` response code.

GET

Description

Reads the properties of an existing username.

Method

GET

URL

`/auth/radius/users/[username]`

Parameters

None.

Returns

{
        "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6",
        "lease_id": "",
        "lease_duration": 0,
        "renewable": false,
        "data": {
                "policies": "default,dev"
        },
        "warnings": null
}

DELETE

Description

Deletes an existing username from the backend.

Method

DELETE

URL

`/auth/radius/users/[username]`

Parameters

None.

Returns

`204` response code.

/auth/radius/login

/auth/radius/login/[username]

POST

Description

Login with the username and password.

Method

POST

URLS

`/auth/radius/login`

`/auth/radius/login/[username]`

Parameters

• username required Username for the authenticating user.
• password required Password for the authenticating user.

Returns

{
 "lease_id": "",
 "renewable": false,
 "lease_duration": 0,
 "data": null,
 "warnings": null,
 "auth": {
 	"client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344",
 	"accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d",
 	"policies": ["default"],
 	"metadata": {
 		"username": "vishal"
 	},
 	"lease_duration": 7200,
 	"renewable": true
 }
}

/auth/radius/users

LIST

Description

List the users registered with the backend.

Method

LIST/GET

URL

`/auth/radius/users` (LIST) `/auth/radius/users?list=true` (GET)

Parameters

None

Returns

[
     "devuser",
     "produser"
]