APIs

To see all APIs available, refer to APIs section for each Modules.

All actions performed by IDEA web interface can also be triggered via HTTP APIs. APIs cover all modules such as creating IDEA users, submit a job or control virtual desktops.

IDEA provides a Swagger documentation available on the IDEA web interface under "Module Name" > "Settings" (example below for "eVDI" > "Settings")

API Spec and Swagger link available for each module

User Authorization

TO be rewritten

API Authorization is available in 4 categories:

• Public - As long as client has network access to the endpoint.

• Authenticated User - The calling user must send a valid JWT token issued by the cluster’s Cognito User Pool

• Manager - The user must be part of the managers Cognito User Group.

• Administrator - The user must be part of the administrators Cognito User Group, in addition to the Sudoers LDAP Group.

API Samples

Auth.InitiateAuth (Using Username/Password)

InitiateAuth is a public API, that is used to authenticate the cluster user. The API may return the authentication result or challenges such as FORCE_RESET_PASSWORD, MFA challenge based configuration.

POST <CLUSTER_ALB_ENDPOINT>/cluster-manager/api/v1 HTTP/1.1
Content-Type: application/json

Username/Password Auth: Request Payload

{
    "header": {
        "namespace": "Auth.InitiateAuth"
    },
    "payload": {
        "auth_flow": "USER_PASSWORD_AUTH",
        "username": "<username>",
        "password": "<password>"
    }
}

Username/Password Auth: Response Payload

{
    "header": {
        "namespace": "Auth.InitiateAuth",
        "request_id": "defc4408-922a-401c-a004-6be6f00718ee"
    },
    "success": true,
    "payload": {
        "auth": {
            "access_token": "eyJra.eyJzd...",
            "id_token": "eyJraWQiOi....",
            "refresh_token": "eyJ...",
            "expires_in": 3600,
            "token_type": "Bearer"
        }
    }
}

RefreshToken Auth: Request Payload

{
    "header": {
        "namespace": "Auth.InitiateAuth",
        "request_id": "defc4408-922a-401c-a004-6be6f00718ee"
    },
    "payload": {
        "auth_flow": "REFRESH_TOKEN_AUTH",
        "username": "<username>",
        "refresh_token": "<refresh_token>"
    }
}

Username/Password Auth: Response Payload

{
    "header": {
        "namespace": "Auth.InitiateAuth",
        "request_id": "defc4408-922a-401c-a004-6be6f00718ee"
    },
    "success": true,
    "payload": {
        "auth": {
            "access_token": "eyJra.eyJzd...",
            "id_token": "eyJraWQiOi....",
            "expires_in": 3600,
            "token_type": "Bearer"
        }
    }
}

Authenticated API Invocations

To invoke authenticated APIs, set the Authorization HTTP Header with: Bearer <access_token>and invoke applicable APIs.

Examples

cURL

 curl -s -k -L -X POST "CLUSTER_ALB_ENDPOINT/cluster-manager/api/v1" \
     --header "Authorization: Bearer $BEARER" \
     --header "Content-Type: application/json" \
     --data-raw '{
            "header": {
                "namespace": "Accounts.CreateUser"
            },
            "payload": {
                "user": {
                    "username": "newuser",
                    "password": "password",
                    "email": "email",
                    "additional_groups": ["managers-cluster-group"]
                },
                "email_verified": true
            }
}'

Python (full example - get access token and query API)

Accounts.CreateUser namespace requires elevated access. Make sure to test this API with a user that belong to manager or cluster-admin groups (e.g: clusteradmin)

import requests
import json
import sys
IDEA_ENDPOINT = "HTTPS://<DNS>"
IDEA_USER = "USER_WITH_ADMIN_PRIVILEGES"
IDEA_PASSWORD = "PASSWORD"

# Initiate Auth and retrieve Access Token

## Prepare Payload
get_auth_data = {
    "header": {
        "namespace": "Auth.InitiateAuth"
    },
    "payload": {
        "auth_flow": "USER_PASSWORD_AUTH",
        "username": IDEA_USER,
        "password": IDEA_PASSWORD
    }
}

## Prepare Header
get_auth_headers = {'Content-Type': 'application/json'}

## Submit request and retrieve access token 
get_auth_request = requests.post(f"{IDEA_ENDPOINT}/cluster-manager/api/v1",
                                 headers=get_auth_headers,
                                 data=json.dumps(get_auth_data),
                                 verify=False # in case you are using self-signed cert
                                 ).json()
if get_auth_request['success']:
    access_token = get_auth_request['payload']['auth']['access_token']
else:
    sys.exit(1)

# Query API requiring elevated permissions (Create new user account)

## Prepare Payload
create_user_data = {
            "header": {
                "namespace": "Accounts.CreateUser"
            },
            "payload": {
                "user": {
                    "username": "testuser1",
                    "password": "p@sswordTest123",
                    "email": "[email protected]",
                    "sudo": False
                },
                "email_verified": True
}}

## Prepare Headers
create_user_headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
}

## Submit request
create_user_request = requests.post(f'{IDEA_ENDPOINT}/cluster-manager/api/v1',
                                    data=json.dumps(create_user_data),
                                    headers=create_user_headers,
                                    verify=False # in case you are using self-signed cert
                                 ).json()

print(create_user_request)

Response:

{
	'header': {
		'namespace': 'Accounts.CreateUser',
		'request_id': '550145c7-93c0-4f3a-96f5-c8b17095c1c0'
	},
	'success': True,
	'payload': {
		'user': {
			'username': 'testuser1',
			'email': '[email protected]',
			'uid': 5004,
			'gid': 5012,
			'group_name': 'testuser1-user-group',
			'login_shell': '/bin/bash',
			'home_dir': '/data/home/testuser1',
			'sudo': False,
			'status': 'CONFIRMED',
			'enabled': True,
			'created_on': '2022-11-01T15:45:27.244000+00:00',
			'updated_on': '2022-11-01T15:45:27.244000+00:00'
		}
	}
}