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.

Paging

When multiple entries are returned by any endpoint, you have the option to request that the results are paged: that is, rather than returning all the entries in one request you can fetch them in slices.

To prevent denial of service, all entry batches are truncated to 10,000 records: no endpoint will return more than 10,000 records at once. This means you must implement batch handling if you need to deal with more than 10,000 results.

To use paging, specify the following two options in the JSON parameters to the endpoint you are using:

KeyValue TypeValue Description
offsetIntThe offset from which to start the returned records.
limitIntThe maximum number of records to return.

For example, if a query produces 50,000 thousand results, you can fetch the first 10,000 with:

{
    "offset": 0,
    "limit": 10000
}

Then, send another request with the same parameters except the next value of offset:

{
    "offset": 10000,
    "limit": 10000
}

Once a return value contains fewer than limit requests, you have reached the end of the available entries.

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.
5007Token assignment failed for an unspecified reason.
5008Token assignment failed because the token does not exist.
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 Yubikeys; this endpoint works for any token type except OATH/TOTP tokens. For those, there is a special endpoint; see below.

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.

Assign an OATH Token

Overview

This endpoint assigns OATH/TOTP tokens (e.g. an Authenticator token) to users.

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

Parameters and Return Value

The parameters and return value for this endpoint are identical in structure to those of the endpoint above ("Assign a Token"); however, the "publicname" specified in the records should be the identifier for an OATH/TOTP token already present in the system (i.e. visible in the List Tokens tab of the web administration console).

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 / Status

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.

Return Value

The return value will be a map with three main elements of interest: records_with_mappings, records_without_mappings, and records_invalid. Each of these elements is a struct with a count element and a records element. The records element will be an empty list or non-existent if there are no records in the given group; otherwise it will be a map. Depending on the parameters provided, this map will have either the usernames or token names as keys, and the mappings for that user or token as the value.

If the search parameters are such that the returned values are tokens, then each token struct will contain a list of user mappings; if the search parameters cause a token list to be returned, then its struct will contain a list of token mappings. In either case, the mappings will be added as a user_mappings element on each returned record.

Token structs are of the following form:

ParameterTypeDescription
token_idStringThe public ID of the token.
token_typeStringThe type of token, e.g. "Yubikey" or "OATH-TOTP"

User structs contain the following elements:

ParameterTypeDescription
userStringThe username, in user@domain format.

Whichever are the mapping structs (not the returned records) will also contain the following information for each mapping:

ParameterTypeDescription
statusStringThe token status (either "Enabled" or "Disabled").
assigned_onIntThe date that the token was assigned to the user, in Unix epoch format.

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

List Block/Unblock Status

Overview

This endpoint returns the blocking status of users, supporting various filter configurations.

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

Parameters

If no JSON data is supplied, then the request returns the blocking status of every user across all domains. Otherwise, a JSON map can be used containing one or more of the following filters:

ParameterTypeDescription
usersListA list of users, in user@domain format.
patternStringA pattern string, in user@domain format. A ".*" expression can be provided to match some part of the username, e.g. "user.*@test" will match all users in domain test whose username starts with user. A domain cannot be partially specified and partially filled by the regex; either the whole domain must be supplied, or the regex must match the whole domain.
stateListContains either or both of "blocked", "unblocked". Matches only the users in that state.

Return Value

The return value on success will be a JSON map containing one entry for each user matching the pattern, plus an additional entry with the key "Reporting Time Zone", which lists the timezone in which GreenRADIUS is executing. This must be taken into account when converting UNIX timestamps into date/time structures.

For each of the users, their username (in user@domain format) will be the key for their entry in the map; the value will be a structure containing the following elements:

KeyTypeDescription
statusString"blocked" or "unblocked".
last_failed_attempt_atIntegerThis entry is only present is status is blocked. If it is present, it contains the UNIX timestamp of the last failed login.

Unblock Users

Overview

This endpoint unblocks users who have previously been blocked by exceeding the threshold for consecutive failed login attempts.

Request Type: PUT
Endpoint Path: /gras-api/v2/mgmt/unblock-users

Parameters

The parameter should be a JSON map containing a single entry users. The value of this entry should be an array of usernames, in user@domain format; each user in this array will be unblocked.

{
	"users":[
        "user1@greenradius.demo",
        "user2@greenradius.demo"
    ]
}

Return Value

A JSON map will be returned containing three sub-maps: records-unblocked,records-skipped, and records_not_found. Records in records_skipped are those which were specified in the parameters, but which were already unblocked (unblocking them would be a no-op.) Each of these categories is in the following format:

KeyTypeDescription
countNumberThe number of records in this category
recordsList of stringsThe users in this category, in user@domain format.

Enable Token Assignment

Overview

This endpoint enables a set of given user/token mappings.

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

Parameters

The parameter should be a JSON map containing a single entry token_assignments. The value of this entry should be an array of maps, each providing one mapping to enable. Each map must provide at least one of the following elements (if it is necessary to specify among many mappings for the user or token, both should be provided).

KeyTypeDescription
token_idStringThe public ID of a token mapped to the user.
usernameStringThe username of the user with the mapping, in user@domain format.

NOTE: The token_id parameter currently supports only YubiKey OTP and Authenticator app tokens

Disable Token Assignment

Overview

This endpoint disables a set of given user/token mappings.

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

Parameters

The parameter should be a JSON map containing a single entry token_assignments. The value of this entry should be an array of maps, each providing one mapping to disable. Each map must provide at least one of the following elements (if it is necessary to specify among many mappings for the user or token, both should be provided).

KeyTypeDescription
token_idStringThe public ID of a token mapped to the user.
usernameStringThe username of the user with the mapping, in user@domain format.

NOTE: The token_id parameter currently supports only YubiKey OTP and Authenticator app tokens

Add a Temporary Token

Overview

This endpoint adds temporary tokens for the specified users.

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

Parameters

This endpoint takes a JSON map containing a single entry temporary_tokens, which is a list of records representing temporary tokens to add. Each record is a map in the following form:

KeyTypeRequiredDescription
usernameStringYesThe user to add the token to, in user@domain format.
expiry_dateIntYesThe expiration date for the token in Unix epoch time.
temporary_tokenStringYesThe token that the user will use. Its length must match what is specified in Global Configuration, and the last six characters cannot be numeric.
count_of_max_authIntNoThe maximum number of times the user will be allowed to authenticate with this token. Set this to 9999 for unlimited authentications. This defaults to 5 if not specified

Return Value

The response will be a map containing three batch results: records_created, records_invalid, and records_skipped.

Update a Temporary Token

Overview

Updates the parameters of one or more already-existing temporary tokens.

Request Type: PUT
Endpoint Path: /gras-api/v2/mgmt/temporary-tokens

Parameters & Return Value

The parameters and return values for updating temporary tokens are identical to the parameters for creating a temporary token; however, expiry_date and temporary_token are optional. If unspecified, these parameters will remain unmodified. Otherwise, the new values overwrite the old ones for that user's temporary token.

Delete a Temporary Token

Overview

Delete the temporary tokens of one or more users.

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

Parameters

This endpoint takes a JSON map containing a single entry, usernames, which should be a list of users whose temporary tokens should be deleted. The usernames should be in user@domain format.

Return Values

This returns a three batches: records_deleted, records_invalid, and records_skipped, consistent with other endpoints.

Get Temporary Token Information

Overview

Get the details associated with the temporary tokens of one or more users.

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

Parameters

This endpoint takes a JSON map containing a single entry, usernames, which should be a list of users to get the temporary token information for. The usernames should be in user@domain format.

Return Values

The return value is three batches: records_found, records_invalid, records_skipped. The records_found entries will be maps representing a user-token mapping; these will be in the same form as the parameters to the Add a Temporary Token endpoint.

Web Analytics Made Easy -
StatCounter

Updated 2023-10-31
© 2024 Green Rocket Security Inc. All rights reserved.