Management APIs

Customers may make use of HTTPS management APIs for specific administrative operations in GreenRADIUS. These allow customers to write their own frontend software to administer their GreenRADIUS instance.

This document lists the endpoints for these APIs and provides examples of how to call each one.

All of these APIs require that the management API password be configured. You can do this by executing the following command from the shell on your GreenRADIUS instance:

sudo docker exec -it GRVA-MAIN changepassword grsapiusr

All requests require parameters to be supplied in the request body as a JSON structure. The Content-Type of the request must be set to application/json. Authentication is required for each request in the form of BasicAuth username/password tokens.

For example, to call the API from Python, you could use the following:

import requests

HOST = 'greenradius.example.com'

requests.post(
    'https://'+HOST+'/gras-api/v2/mgmt/import_token/yubikey',
	auth = ('grsapiusr', 'GreenRocket!23'),
	json = {
    	"yubikeys" : [
            {
                "make": "Yubico OTP",
                "serialno": 3014781,
                "publicname": "ddvcuttiuejt",
                "internalname": "8b428d0f016f",
                "aeskey": "a55adb9c4da2ad57c529737fd4d5ecd0"
            }
        ]
    }
)

The APIs are:

Reporting Batch Results

Many of the endpoints allow one to send multiple entries as part of a single request. For example, the YubiKey Import endpoint enables you to send several YubiKey token entries with one request. When this happens, it is possible for some of the assignment requests to succeed and some to fail. Therefore, these endpoints use result batches to report the results of individual logins, rather than reporting the entire batch as a single success or failure.

A result batch is a JSON structure with the following entries:

{
    "count": 2,
    "records": {...}
}

The count is either an integer or a string (callers must expect either.) It indicates the number of results in this batch. The records entry is a JSON structure, unless count is 0, in which case it is the empty list []. It will contain count key-value pairs, each of which represents the result of one of the entries in the initial request. The value will vary depending on which type of batch and which endpoint; the key is always a string (not an int) of the index, starting from 1, of the request in the initial list passed to the endpoint.

For example: say a fictional endpoint square, which computes N2, is called with five individual entries:

{
    "numbers": [
        5,
        2,
        "invalid input",
        6
    ]
}

The result might be two result batches, one containing successes and one containing failures:

{
    "numbers_squared": {
        "count": 3,
        "records": {
            "1": 25,
            "2": 4,
            "4": 36
        }
    },
    "numbers_invalid": {
        "count": 1,
        "records": {
            "3": {...}
        }
    }
}

numbers_invalid["records"]["3"] would be an error structure, as described below.

Error Reporting

Error Structure

Errors are reported as a structure with the following entries.

KeyValue TypeValue Description
codeIntAn integer numerical code describing the error.
shortStringA short, non-user-friendly description of the error.
descriptionStringA longer, more user-friendly description of the error.

Table of Error Codes

CodeError
4000The Content-Type of the request is not application/json.
4001One of the input parameters is invalid.
4002A required input parameter is missing.
5000No user found.
5001The user already has the maximum number of tokens allowed.
5002The token is already assigned to the user.
5003Assigning a token to a user failed.
5004The requested YubiKey token is not present.
5005The maximum number of users has been exceeded.
5006The token could not be assigned because user-level authentication failed due to invalid credentials.
5026The requested assignment was not found.
5051The YubiKey token is already present.

Import a YubiKey Token

Overview

This endpoint imports a new YubiKey token. The token will not be assigned to any user, but it will be added to the GreenRADIUS database.

Request Type: POST
Endpoint Path: /gras-api/v2/mgmt/import_token/yubikey

Parameters

{
    "yubikeys" : [...]
}

Each item in the provided list of YubiKeys must be a JSON structure with the following elements:

AttributeTypeDescription
makeStringThe make of this particular token. Should always be set to "Yubico OTP".
serialnoIntThe serial number of the YubiKey.
publicnameStringThe key's public ID.
internalnameStringThe key's private ID.
aeskeyStringThe secret AES-128 key associated with the YubiKey.

Return Values

If the request parameter is valid and adheres to the specified format, the endpoint will return a JSON structure similar to the following:

{
    "records_imported": {...},
    "records_invalid": {...},
    "records_skipped": {...}
}

Each of records_imported, records_invalid, and records_skipped will contain a request batch structure. Within this records_imported structure, each record in the batch will be a structure with keys status, make, serialno, and publicname. The latter three elements are the same ones that were passed in; the status attribute is always set to "success".

For failed requests (this includes both records_invalid and records_skipped), the value will be an error entry. Attempting to import a key that is already present in the database is considered an error; that key will be counted in records_skipped.

For an error which makes it impossible to parse the key import requests (such as, for example, the yubikeys parameter is missing entirely or is the wrong type) then the request value will simply be an error structure.

Delete a YubiKey

Overview

This endpoint deletes a YubiKey from the database.

Request Type: DELETE
Endpoint Path: /gras-api/v2/mgmt/delete_token/yubikey

Parameters

{
    "deletealways": false,
    "yubikeys": [...]
}
ParameterTypeDescription
deletealwaysBoolIf true, the YubiKeys will be deleted even if they are currently assigned to users. If false, those requests will instead produce error entries. This parameter is optional and defaults to false.
yubikeysListA list of YubiKeys to delete. Each YubiKey is a JSON structure with a single entry publicname, which is the Public ID of the YubiKey.

Return Values

If the request is validly formed, the response will be a JSON structure of the form:

{
    "records_deleted": {...},
    "records_invalid": {...},
    "records_skipped": {...}
}

Each of these is a batch structure; records_invalid and records_skipped contain an error structure for each failed deletion. records_deleted contains a batch structure, whose individual entries are of the following form:

{
    "status": "success",
    "publicname": "..."
}

publicname will be the public name of the deleted key.

If the request is not validly formed, the response will be an error structure.

Assign a Token

Overview

The endpoint assigns tokens to users. Unlike the YubiKey import endpoint, it is not restricted to any particular type of token.

Request Type: POST
Endpoint Path: /gras-api/v2/mgmt/mappings

Parameters

{
    "assignments" : [
        {...}
    ]
}

Each assignment entry should be a structure with the following elements:

AttributeTypeDescription
usernameStringThe target user to assign the key to. This must be supplied in user@domain format.
publicnameStringThe public ID of the token to assign to the user.

Return Values

Like the other endpoints, this returns a single error structure if the input is invalid. However, it does not return regular batch structures on success. Instead, the output is in the following format:

{
    "assignments": [...]
}

Each item in the assignments list corresponds to one of the entries in the original request. These are structures with two entries, input and output. The input attribute is the input that was submitted for this entry (i.e. a structure with username and publicname attributes). The output attribute is a structure. This structure is always guaranteed to have one attribute status, whose value will be either "success" or "failed". If the assignment failed, the structure will also be an error structure, with code,short,and description attributes. If the assignment succeeded, the structure will contain a msg attribute with a success message.

Remarks

If the token is already assigned to a user - even if they are the same as the target of the assignment request - the request will fail.

Unassign a Token

Overview

This endpoint un-assigns tokens that are currently assigned to users.

Request Type: DELETE
Endpoint Path: /gras-api/v2/mgmt/mappings

Parameters

{
    "users": [
        {...}
    ]
}

Each entry to unassign should be a structure with either of the two following keys (you need not supply both):

AttributeTypeDescription
usernameStringThe username to un-assign from, in user@domain format.
publicnameStringThe public ID of the token to un-assign.

Remember, for each unassignment, you only need to supply either the user or the token!

Return Value

Like the Assign a Token endpoint, this endpoint returns a structure in this format:

{
    "users": [...]
}

Each item in the users list corresponds to one of the input entries. These entries are structures with input and output attributes, with input again holding the input value for this entry. The output value is either an error structure, if the given entry failed to unassign, or a structure in one of two formats.

If the entry unassigned by username, its corresponding output struct will have the following attributes:

AttributeTypeDescription
statusStringFor successful unassignments, holds "success".
usernameStringThe input username.
tokens_unassignedList of stringsA list of all tokens unassigned from the user.

If the entry unassigned by token ID, its output struct will look like this instead:

AttributeTypeDescription
statusStringFor successful unassignments, holds "success".
publicnameStringThe input public ID of the token.
users_unassignedList of stringsA list of all users the token was unassigned from.

Request Token Assignments

Overview

This endpoint returns a list of user-token mappings matching the given criteria.

Request Type: GET
Endpoint Path: /gras-api/v2/mgmt/tokenassignment

Parameters

All parameters are optional. You may supply one, more than one, or none. Supplying no parameters will match all assignments.

ParameterTypeDescription
token_idList of stringsA list of Token IDs to match against.
usernameList of stringsA list of user names to match against. These must be provided in user@domain format.
token_typeList of stringsA list of token types to match against. The following values are accepted: yubikey, oath-totp, oath-hotp, u2f, and m2f. Multiple values may be supplied.
assigned_beforeIntA "latest date" for any assignment. Matches only assignments earlier than this date. Provided as a number of seconds since 00:00:00 on 1 Jan 1970 in the server's timezone.
assigned_afterIntAn "earliest date" for any assignment, in the same format as assigned_before.

Request Authentication Records

Overview

This endpoint returns a log the of authentications against the GreenRADIUS server, filtered according to provided criteria.

Request Type: GET
Endpoint Path: /gras-api/v2/mgmt/gras-authentication-request-records

Parameters

{
    "authentication_result": //List of strings.
    "token_type": //List of strings. 
    "username": //List of strings
    "token_id": //List of strings
    "authentication_agent": //List of strings
    "authentication_endpoint": //List of strings
    "sort_by": //String
    "sort_order": //String
    "from_timestamp": //String. "Earliest date" for authentication requests, in seconds since 
    				//00:00:00 on 1 January 1970 in the server's timezone
    "to_timestamp": //String. "Latest date" for authentication requests, in the same format as above.
}
ParameterPossible Values (more than one may be supplied)
authentication_resultSUCCESS_2FA, SUCCESS_SF,SUCCESS_TEMP,FAILED
token_typeALL,YUBIKEY,OATH,U2F,MOBILE
sort_byAUTHENTICATION_TIME,USERNAME,TOKEN_ID
sort_orderASC,DESC
Updated 2021-07-02
© 2021 Green Rocket Security Inc. All rights reserved.