API v2: External authentication¶

Data structures¶

`ExternalAuthenticationModel`¶
Parameter	Type	Required	Description
id	string	yes	Read-only object Identifier
type	string {cerb, radius, ldap, ad}	yes	Immutable
address	string	yes
port	number {from `1` to `65535`}	yes
bindto	string	no	Bind address. Include labels like ‘fudo:label:test’ or ip address
cerb	ExternalAuthentication-CerbModel	If `type` == `cerb`	Cerb object definiton
radius	ExternalAuthentication-RadiusModel	If `type` == `radius`	Radius object definiton
ldap	ExternalAuthentication-LdapModel	If `type` == `ldap`	LDAP object definiton
ad	ExternalAuthentication-AdModel	If `type` == `ad`	Active Directory object definiton
tls_enabled	boolean	no	Enable TLS protocol
tls_certificate	string	If `tls_enabled` == `true`
second_factor_type	string {duo, oath, sms}	no
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

`ExternalAuthenticationCerbModel`¶
Parameter	Type	Description
secret	string	Password to cerb provider; required; write-only
radius_nasid	string	Correct value of NAS id of Cerb provider

`ExternalAuthenticationRadiusModel`¶
Parameter	Type	Description
secret	string	Password to cerb provider; required; write-only
radius_nasid	string	Correct value of NAS id of Radius provider

`ExternalAuthenticationLdapModel`¶
Parameter	Type	Description
ldap_binddn	string	Bind domain to LDAP provider; required

`ExternalAuthenticationAdModel`¶
Parameter	Type	Description
login	string
secret	string	Password to cerb provider; required; write-only
ad_domain	string	Bind domain to AD provider; required

Request for retrieving available attributes of the ExternalAuthenticationModel

Method	GET
Path	/api/v2/objspec/external_authentication

Allowed methods

`GET`	for reading data of an existing object; no request body is required
`POST`	for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
`PATCH`	for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
`DELETE`	for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

fields - for including the object fields in the query,

filter - narrows out the result with available additions:

in - include possible field values (separated with comma),

match - include a sequence of characters to be searched in field values,

eq - equal,

ne - not equal,

lt - less than,

le - less or equal,

gt - greater than,

ge - greater than or equal

blocked - filter blocked objects,

!blocked - filter unblocked objects,

isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

order,

offset,

limit,

debug - for showing statistics, database errors, etc,

total_count,

reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count

Possible responses

Code	Status
`200`	success	`OK`
`201`	success	`CREATED`
`400`	failure	`BAD REQUEST`; message examples: `Unrecognized endpoint`, `Request body is not allowed for this endpoint`
`401`	failure	`UNAUTHORIZED`
`404`	failure	`BAD REQUEST`; message example: `Object not found`

The next chapter describes procedures for creating separate requests.

Refer to the Batch operations topic to create nested requests for operating on the External Authentication objects.

Retrieving external authentication methods list¶

Request

Method	GET
Path	/api/v2/external_authentication

Example request

Sending GET https://10.0.0.0/api/v2/external_authentication

Response

    {
"result": "success",
"external_authentication": [
    {
        "id": "1234538875067072557",
        "type": "ad",
        "port": 636,
        "ad_domain": "jdoe.local",
        "created_at": "2021-08-09 19:40:05.171853+02",
        "modified_at": "2021-08-09 19:40:05.171853+02",
        "address": "10.0.139.100",
        "tls_enabled": true,
        "tls_certificate": "-----BEGIN CERTIFICATE-----\r\nMIIFrTCCBJWgAwIBAg...ic=\r\n-----END CERTIFICATE-----\r\n"
    },
    {
        "id": "12345138875067072517",
        "type": "ldap",
        "port": 389,
        "ldap_binddn": "dc=qa-ldap,dc=null",
        "created_at": "2021-03-03 14:11:52.245683+01",
        "modified_at": "2021-03-03 14:14:46.052855+01",
        "address": "10.0.235.1",
        "tls_enabled": false,
        "tls_certificate": ""
    },
    {
        "id": "12345067072573",
        "type": "cerb",
        "port": 1812,
        "created_at": "2022-10-19 10:23:11.29545+02",
        "modified_at": "2022-10-19 10:58:12.325396+02",
        "address": "10.0.234.21",
        "radius_nasid": "",
        "tls_enabled": false,
        "tls_certificate": ""
    },
    {
        "id": "3234566775067072572",
        "type": "radius",
        "port": 1812,
        "created_at": "2022-10-19 10:08:23.160433+02",
        "modified_at": "2022-10-19 10:19:50.525671+02",
        "second_factor_type": "oath",
        "address": "10.0.0.1",
        "radius_nasid": "abcdeg",
        "tls_enabled": true,
        "tls_certificate": "-----BEGIN CERTIFICATE-----\r\nMIIG5jC...2MOXV1x+eQAm0Vy\r\n-----END CERTIFICATE-----\r\n"
    }]}

Modifying external authentication method¶

Request

Method	PATCH
Path	/api/v2/external_authentication/<id>
Headers	Content-Type: Application/JSON
Body	ExternalAuthenticationModel

Example request: Adding SMS authentication for second factor to AD authentication

Sending PATCH https://10.0.0.0/api/v2/external_authentication/1234538875067072557

{"second_factor_type": "sms"}

Response

{ "result": "success"}

Creating an external authentication method¶

Request

Method	POST
Path	/api/v2/external_authentication
Headers	Content-Type: Application/JSON
Body	ExternalAuthenticationModel

Example request: Creating Cerb definition with second factor OATH authentication

Sending POST https://10.0.0.0/api/v2/external_authentication

{ "type": "cerb",
"port": 1812,
"address": "10.0.234.21",
"radius_nasid": "abcds",
"secret": "my-password",
"tls_enabled": false,
 "second_factor_type": "oath" }

Response

    { "result": "success",
"external_authentication": {
    "id": "123456819172646913" }}

Deleting an external authentication method¶

Request

Method	DELETE
Path	/api/v2/external_authentication/<id>