Getting Started with Secure Access Cloud Management API

book

Article ID: 174912

calendar_today

Updated On:

Products

Secure Access Cloud

Issue/Introduction

Getting Started with Secure Access Cloud (SAC) Management API

Environment

Secure Access Cloud

Resolution

Overview

This blog post will introduce you to the SAC API v2 to automate your business flows. Documentation can be found here

All examples below are performed on the tenant called ‘acme.luminatesec.com’.

Conditions

  • Must have administrator privileges on your SAC tenant.
  • Must be comfortable with curl.

Starting with Authentication

Authentication is done using OAuth2 with the Bearer authentication scheme.

First, you need to generate an API client using the SAC Admin portal (usually at admin.acme.luminatesec.com/#/settings/api-clients) and make sure to assign the ‘Allow access to Luminate management API’ permission.

new_api_client_3.png

Then copy the ‘Client Id’ and the ‘Client Secret’ so they can be used for OAuth authentication:

new_api_client_2.png

 

Now you can get your API access token

curl -X POST \

https://api.acme.luminatesec.com/v1/oauth/token \

-H "Authorization: Basic $(echo -n yourApiClientId:yourApiClientSecret | base64)"

that returns the following JSON

{     "access_token":"edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX",   "expires_in":86400,   "scope":"luminate-scope",   "token_type":"Bearer",   "error":"",   "error_description":""}

All further API calls should include the ‘Authorization’ header with value “Bearer yourApiAccessToken”

Creating your first application

Let’s create a Web application by calling

curl -X POST \

  https://api.acme.luminatesec.com/v2/applications/ \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json' \

  -d '{

            "name": "myCnnWebApplication",

            "description": "expose CNN securely",

            "type": "HTTP",

            "connectionSettings": {

                "internalAddress": "https://www.cnn.com"

            },

            "sshSettings": {

                "userAccounts": []

            }

        }'

that returns the application JSON that includes its external address

 

NOTE:

You can retrieve this application by listing applications with filter

curl -X GET \

  'https://api.acme.luminatesec.com/v2/applications/?filter=myappcnn' \

  -H 'Accept: application/json;charset=UTF-8' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

or directly by application id

curl -X GET \

  https://api.acme.luminatesec.com/v2/applications/yourApplicationId \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

Assigning this application to a site

You must assign this application to a site with configured connectors to be able to access it through its external address

List the sites to retrieve the site ID

curl -X GET \

  https://api.acme.luminatesec.com/v2/sites/ \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

that returns a list of sites.

Now assign your application to the desired site

curl -X PUT \

  https://api.acme.luminatesec.com/v2/applications/yourApplicationId/site-binding/yourSiteId \

  -H 'Accept: application/json;charset=UTF-8' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXXX' \

 -H 'Content-Type: application/json'

 

 

NOTE:

You can retrieve the site with for assigned application

curl -X GET \

  'https://api.acme.luminatesec.com/v2/sites/?app_id=yourApplicationId' \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

You can retrieve the site’s status

curl -X GET \

  https://api.acme.luminatesec.com/v2/sites/yourSiteId/status \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

Assigning directory entities to access your application

SAC allows three types of entities (user, group and api client) to be assigned to an application’s authorization policy to allow access to the application.

Users and groups usually belong to an Identity Provider (such as Okta or Azure AD) which you can integrate with SAC (although you can also use SAC local accounts), while api clients are created locally, within your SAC tenant (similar to local accounts)

Local users and groups are defined within the ‘local’ idp

 

List your directory entities with filter

curl -X GET \

  'https://api.acme.luminatesec.com/v2/identities/local/users/?filter=myFilter' \

  -H 'Accept: application/json' \

  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \

  -H 'Content-Type: application/json'

 that returns a page of directory entities

Assign this user to your application

curl -X PUT \  https://api.acme.luminatesite.com/v2/applications/yourApplicationId/directory-entity-bindings/ \  -H 'Accept: application/json;charset=UTF-8' \  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \  -H 'Content-Type: application/json' \  -d '{"directoryEntity":{    "type":"User",    "identifierInProvider":"auth0|5b3bc3bb4b506079caf1a8a5",    "identityProviderId":"local"},"securityRole":{    "id":"",    "sshUserAccountStrategy":"Specific",    "customSshUserAccounts":[]}}'

that returns the binding

{   "directoryEntity": {        "id": "6ce6872d-c62d-443f-b315-3f08d12094e4",        "type": "User",        "identityProviderType": "local",        "identifierInProvider": "auth0|5b3bc3bb4b506079caf1a8a5",        "identityProviderId": "local",        "displayName": "[email protected]"    },    "securityRole": {        "id": "6cfef1d8-562e-4883-aa96-6350e9cf4d3e",        "sshUserAccountStrategy": "Specific",        "isSshKeyAuthenticationMethodEnabled": true,        "isTransparentAgentForwardingEnabled": false,        "customSshUserAccounts": []    }}

 

NOTE:

You can retrieve the assigned directory entities to the application

curl -X GET \  https://api.acme.luminatesec.com/v2/applications/yourApplicationId /directory-entity-bindings/ \  -H 'Accept: application/json;charset=UTF-8' \  -H 'Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX' \  -H 'Content-Type: application/json'

Summary

In this post, we went over the basic API calls for authorization and application management (creation, site assignment and user assignment)

Attachments