Introduction

This Document explains about the procedure to authenticate using oAuth and use the tokens for API operations such as GET, POST, PUT, Delete. Versa Director and Concerto listen on port numbers 9182 and 9183 for REST API queries.

Requirement

Customers require using REST API oAUTH client using “client_ID” and “client_ secret” based token for authentication of API responses.

Procedure for creating oAuth client

1. Create oAuth client on the Director/Director’s.

Navigate to Director ------->Administration ------------>system ----------->Authorized users------ >Clients

“Click on Add +”

2. Configure the oAuth client values, here important fields are name of the client, description, and grant types.

“Click on ok”

3. Oauth client details will be shown in the pop-up screen, after you click “ok”. Now, these values have to retained till the time token refresh is not needed.

4. Optional- recovering the client secret key

Navigate to Director ------->Administration ------------>system ----------->Authorized users------ >Clients

“Select the client’s name checkbox, and click on “refresh client secret””

REST API procedure using oauth client-id & client-secret

1. API call for creating a “TOKEN”, we use the generated client-id, client-secret + username and password of the Director with “ProviderDatacenterSystemAdmin” or ProviderDatacenterAdmin”

Snippet of the code sample

curl -i -k -X POST 'https://10.163.105.103/portalapi/v1/auth/token' -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "client_id": "ABDFD15E2SFFS16D0EE4F972AC19D2011C", "client_secret": "85d642bdd3a8398712724bc720c5b31a","username": "apitester", "password":"Versa@1234", "grant_type": "password"}'

2. This step will generate a token key, which shall be used for our future API requests.

successful Output:

HTTP/2 201

cache-control: no-cache, no-store, max-age=0, must-revalidate

content-security-policy: default-src 'self';font-src 'self' data: https://fonts.googleapis.com/ https://fonts.gstatic.com; script-src 'self' 'unsafe-eval' 'unsafe-inline' https://maps.googleapis.com/maps/api/geocode/json https://maps.googleapis.com/ https://*.tile.openstreetmap.org https://export.highcharts.com/ https://code.highcharts.com/; img-src 'self' blob: data: https://maps.googleapis.com/maps/api/geocode/json https://maps.gstatic.com/ https://maps.googleapis.com/ https://*.tile.openstreetmap.org https://lipis.github.io https://chart.apis.google.com/ https://export.highcharts.com/ https://purecatamphetamine.github.io/; style-src 'self' 'unsafe-inline' data: https://maps.googleapis.com/maps/api/geocode/json https://*.tile.openstreetmap.org https://fonts.googleapis.com/ https://export.highcharts.com/ https://code.highcharts.com/;form-action 'self'; connect-src 'self' wss://self:6080 data: https://maps.googleapis.com https://*.tile.openstreetmap.org/ https://ipapi.co;

content-type: application/json;charset=UTF-8 date: Mon, 10 Jul 2023 10:17:25 GMT

expires: 0 pragma: no-cache

set-cookie: USER_SESSION_RSA_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgl8ST9QPIXTYKOmLe5JwcSIC48mWnwFGTCG8S7AU7Os9qQu667Xdcv0JLW5wxvLA

rAtA083gRZLIIwG38Ulibgzol11YYhJeF3j9Ka370grHG3AH+RNzkGjPOibGaVfQUpA2ST1SLoFIi7GKacmNxHpZXmCEWMCHss+59kmEnqzUGcjAI0I5uu27Id1/rhv/YGwHE1kw jgfwccEFOkyEgV4zl1U7XLIOp4PDGERw3DlKpIPTi1zAhXWgjGImn/oc+HZiJ8oy1IENMox4kO0Xo5nsErCsDRMScyZPoXMg+eedReELD3XJtyfT/oRPBEJXpr13N3zYPpHaX633 YHPpbQIDAQAB; Path=/; Secure

strict-transport-security: max-age=31536000 ; includeSubDomains

trace-id: d664a756e0a9bce3a9a7fffdb5f13db6 vary: Origin

vary: Access-Control-Request-Method vary: Access-Control-Request-Headers x-content-security-policy: self

x-content-type-options: nosniff x-frame-options: SAMEORIGIN

x-xss-protection: 1; mode=block

{"access_token":"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI2ODg3OGQ5ZWY3OWY5YmY3MTcxNjc4MjE2ZmIxOGU5MzNhN2E0NWZkODFkYzhiZDlmMDUzMmZmYzBhYjE2ZTNiIi wiaWF0IjoxNjg4OTg4NzQ2LCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJleHAiOjE2ODg5OTc3NDZ9.a3FIcxl4pIbPJBzT8wxkVoxmluvngIARJ0k- P6L27Zc”

,"issued_at":"2023-07- 10T10:16:15.749Z","expires_in":"900","token_type":"Bearer","refresh_token":"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI1YjVmZjQ3OWVkOWE1Y2NlN2U4MjJ iZTY2NjhiYjgxZDdlNTRjY2NjM2I0M2EzYzcxODk1MmM0NTNmMzIzY2NjIiwiaWF0IjoxNjg4OTg0MTc1LCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJ leHAiOjE2ODg5ODUwNzV9.flejdFtlmXx48iIYLhBLSYcIP- nMu3fUbA9wixP5RnI","user":{"name":"apitester","firstname":"APITESTER","lastname":"OAUTH","email":vivek.s@versa- networks.com,"is_external_user":false,"enable_two_factor":false,"idle_time_out":30,"roles":["Service Provider Administrator"],"primaryrole":"SERVICE_PROVIDER_ADMIN","primaryRoleName":"Service Provider Administrator"},"auth_context":{"isAuthInSlaveNode":false},"defaultPassword":false,"isDefaultPassword":false}

3. Use the token key for API operation to the Concerto.

Sample-1 API (check list of tenants summary)

admin@DC-DIRECTOR:~$ curl -i -k https://10.163.105.103/portalapi/v1/tenants/summary?hierarchical=true'

-X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI2ODg3OGQ5ZWY3OWY5YmY3MTcxNjc4MjE2ZmIxOGU5MzNhN2E0NWZkODFkYzhiZDlmMDUzM mZmYzBhYjE2ZTNiIiwiaWF0IjoxNjg4OTg4NzQ2LCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJleHAiOjE 2ODg5OTc3NDZ9.a3FIcxl4pIbPJBzT8wxkVoxmluvngIARJ0k-P6L27Zc"

Response

HTTP/2 200

cache-control: no-cache, no-store, max-age=0, must-revalidate

content-security-policy: default-src 'self';font-src 'self' data: https://fonts.googleapis.com/ https://fonts.gstatic.com; script-src 'self' 'unsafe-eval' 'unsafe- inline' https://maps.googleapis.com/maps/api/geocode/json https://maps.googleapis.com/ https://*.tile.openstreetmap.org https://export.highcharts.com/ https://code.highcharts.com/; img-src 'self' blob: data: https://maps.googleapis.com/maps/api/geocode/json https://maps.gstatic.com/ https://maps.googleapis.com/ https://*.tile.openstreetmap.org https://lipis.github.io https://chart.apis.google.com/ https://export.highcharts.com/ https://purecatamphetamine.github.io/; style- src 'self' 'unsafe-inline' data: https://maps.googleapis.com/maps/api/geocode/json https://*.tile.openstreetmap.org https://fonts.googleapis.com/ https://export.highcharts.com/ https://code.highcharts.com/;form-action 'self'; connect-src 'self' wss://self:6080 data: https://maps.googleapis.com https://*.tile.openstreetmap.org/ https://ipapi.co;

content-type: application/json;charset=UTF-8 date: Mon, 10 Jul 2023 13:42:05 GMT

expires: 0

pragma: no-cache set-cookie:

USER_SESSION_RSA_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgl8ST9QPIXTYKOmLe5JwcSIC48mWnwFGTCG8S7AU7Os9qQu667Xdcv0JLW5wxvLArAtA083gRZLIIwG38Ulibgzol11Y

YhJeF3j9Ka370grHG3AH+RNzkGjPOibGaVfQUpA2ST1SLoFIi7GKacmNxHpZXmCEWMCHss+59kmEnqzUGcjAI0I5uu27Id1/rhv/YGwHE1kwjgfwccEFOkyEgV4zl1U7XLIOp4PDGERw3DlKpIPTi1zAhXWgjGImn/oc

+HZiJ8oy1IENMox4kO0Xo5nsErCsDRMScyZPoXMg+eedReELD3XJtyfT/oRPBEJXpr13N3zYPpHaX633YHPpbQIDAQAB; Path=/; Secure

set-cookie: ECP-CSRF-TOKEN=42c8ebac7ef873f4aa0c41c4ce3fe277683e05652bf1f4af42a54e53d03da720; Path=/; Secure set-cookie: EECP-CSRF-

TOKEN=BF7D1411A1791818E4CA705D22DADABA10405448371399A829832379C0817A867DECCC59EE71E626CD82325DBBD457B9542B5B281F6239D34CBDEE9EFA1D2DDD382FFFF363311BC80E4E823CB72A48

90; Path=/; Secure; HttpOnly

strict-transport-security: max-age=31536000 ; includeSubDomains trace-id: 9a152104d883ad7f135222ef6319ce27

vary: Origin

vary: Access-Control-Request-Method vary: Access-Control-Request-Headers x-content-security-policy: self

x-content-type-options: nosniff x-frame-options: SAMEORIGIN

x-xss-protection: 1; mode=block

{"size":3,"nextWindowNumber":0,"data":[{"subTenants":[{"subTenants":[],"accessPermission":true,"editable":true,"uuid":"c764e00f-10fc-4a38-9cb0- b267dfc60580","name":"ACREED-Industries","parentTenant":"CUSTOMER-LOR-1","activeStatus":true,"publishStatus":"PUBLISHED","taskID":"4f58d156-2788-486a-8537-

cc5544b000fb","roles":[{"uuid":"f07c4b7f-3112-4c0b-99d3-c002c6b6b130","value":"Service Provider Operator"},{"uuid":"544fc9fb-e08a-4f14-a99d- 06fd87f6cc67","value":"ANALYTICS_USER"},{"uuid":"1bbf2073-5de0-4f18-908f-c0df333037c4","value":"southadmin"},{"uuid":"c2c9c823-5b1d-43f5-a9bd- 327f90e80c4b","value":"Enterprise Administrator"},{"uuid":"0386d6c6-8735-4443-8348-950eff34e435","value":"Enterprise Operator"},{"uuid":"9bf8d54d-a8b1-432c-8138- 2628609f1d0b","value":"Service Provider Administrator"}],"logoDataUrl":null,"globalId":12,"saseEnabled":true,"sdwanEnabled":true},{"subTenants":[],"accessPermission":true,"editable":true,"uuid":"4817577f- 3938-488d-8a84-5e6cbebaeccd","name":"CUSTOMER-HOTD","parentTenant":"CUSTOMER-LOR-1","activeStatus":true,"publishStatus":"PUBLISHED","taskID":"303568d1-7dfc-495d- bfe8-54734dbf45ce","roles":[{"uuid":"f07c4b7f-3112-4c0b-99d3-c002c6b6b130","value":"Service Provider Operator"},{"uuid":"9bf8d54d-a8b1-432c-8138- 2628609f1d0b","value":"Service Provider Administrator"},{"uuid":"c2c9c823-5b1d-43f5-a9bd-327f90e80c4b","value":"Enterprise Administrator"},{"uuid":"0386d6c6-8735- 4443-8348-950eff34e435","value":"Enterprise Operator"}],"logoDataUrl":null,"globalId":11,"saseEnabled":true,"sdwanEnabled":true}],"accessPermission":true,"editable":true,"uuid":"6be8751c-2de8-4170-8de8- b1c9cb075a0d","name":"CUSTOMER-LOR-1","parentTenant":null,"activeStatus":true,"publishStatus":"PUBLISHED","taskID":"a6496bfd-6b3c-46a9-9e88- aed2dc9df654","roles":[{"uuid":"9bf8d54d-a8b1-432c-8138-2628609f1d0b","value":"Service Provider Administrator"},{"uuid":"0386d6c6-8735-4443-8348- 950eff34e435","value":"Enterprise Operator"},{"uuid":"c2c9c823-5b1d-43f5-a9bd-327f90e80c4b","value":"Enterprise Administrator"},{"uuid":"f07c4b7f-3112-4c0b-99d3- c002c6b6b130","value":"Service Provider Operator"}],"logoDataUrl":null,"globalId":1,"saseEnabled":false,"sdwanEnabled":true}]}admin@DC-DIRECTOR:~$

Sample-2 API (check list of tenants summary)

admin@DC-DIRECTOR:~$ curl -i -k https://10.163.105.103/portalapi/v1/ v1/tenants/audit/logs' -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI2ODg3OGQ5ZWY3OWY5YmY3MTcxNjc4MjE2ZmIxOGU5MzNhN2E0NWZkODFkYzhiZDlmMDUzM mZmYzBhYjE2ZTNiIiwiaWF0IjoxNjg4OTg4NzQ2LCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJleHAiOjE 2ODg5OTc3NDZ9.a3FIcxl4pIbPJBzT8wxkVoxmluvngIARJ0k-P6L27Zc"

Response

HTTP/2 200

cache-control: no-cache, no-store, max-age=0, must-revalidate

content-type: application/json;charset=UTF-8 date: Mon, 10 Jul 2023 14:02:03 GMT

expires: 0 pragma: no-cache

set-cookie: USER_SESSION_RSA_PUBLIC_KEY=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgl8ST9QPIXTYKOmLe5JwcSIC48mWnwFGTCG8S7AU7Os9qQu667Xdcv0JLW5wxvLA

set-cookie: ECP-CSRF-TOKEN=35469fa54e93521612237c0dc307a70256eccae5653ab2e8ffe3ce06ecbbb249; Path=/; Secure set-cookie: EECP-CSRF-

TOKEN=5FF1886E3DA606B2DED87BB17A42D56C2298EAF4D948F916D984FDA0A9C7A0B94052E6FC58B2B37D77C6A8038CAEABEC92EFD3DAFD1C203AEB30F89561DCA01A19 462F32D0FD7CC749FCBA12D1A1E685; Path=/; Secure; HttpOnly

strict-transport-security: max-age=31536000 ; includeSubDomains trace-id: 312d541507fadf915a9d09369f61c460

vary: Origin

vary: Access-Control-Request-Method vary: Access-Control-Request-Headers x-content-security-policy: self

x-content-type-options: nosniff x-frame-options: SAMEORIGIN

x-xss-protection: 1; mode=block

{"size":5830,"nextWindowNumber":1,"data":[{"uiSession":"","userName":"apitester","sourceIp":"10.163.105.5","traceId":"75bd5731d762034216 db9455ae5d6aab","resource":"POST

/portalapi/v1/auth/token","resourceGroup":"OAuthController","operation":"getAccessToken","payload":"{\"grant_type\":\"password\",\"clien t_id\":\"***\",\"client_secret\":\"***\",\"username\":\"apitester\",\"password\":\"***\"}","status":"SUCCESSFUL","statusCode":"201","ten antName":"Concerto- Internal","durationMilSec":2470,"createDate":1688997581088,"auditID":106031},{"sourceIp":"10.163.105.5","traceId":"b2906b68c0e441e53623e b3013a40a8c","resource":"GET

/portalapi/v1/tenants/audit/logs","changeSet":"eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkYjYwNTM2ODhlMTE2NzRhYjQ3OTg3YzdlNDNlZmM2OWJkZjEzNWZmMGRk ZGU4OGI5NDY2MDQ1NjY0Y2UwNjkzIiwiaWF0IjoxNjg4OTg0MTc1LCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJleHAiOjE2ODg5ODUwNzV9.v11V8Fi k5fxUybXlzmspXi7_oqWDsrdMNHoGW43QrwQ is expired.","status":"CLIENT_ERROR","statusCode":"401","durationMilSec":4,"createDate":1688997522677,"auditID":105515},{"uiSession":"32f98 3a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"585e4500d7fa4169c8556a3f6a87498b","res ource":"POST

/portalapi/v1/auth/token","resourceGroup":"OAuthController","operation":"getAccessTokenSwaggerUI","status":"SERVER_ERROR","statusCode":"

500","durationMilSec":7,"createDate":1688997083576,"auditID":106030},{"uiSession":"32f983a23803678d736c3133680feaf62f83d08976c3143efa90b 5dfe81312e9","sourceIp":"172.19.0.180","traceId":"a5489f6d25c15cd1e9b4ea04e741dd0d","resource":"POST

/portalapi/v1/auth/token","resourceGroup":"OAuthController","operation":"getAccessTokenSwaggerUI","status":"SERVER_ERROR","statusCode":" 500","durationMilSec":13,"createDate":1688997044707,"auditID":106025},{"uiSession":"32f983a23803678d736c3133680feaf62f83d08976c3143efa90 b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"9eeda4f7546c175049e8d559c93814da","resource":"GET /portalapi/webjars/springfox- swagger-ui/fonts/titillium-web-v6-latin- regular.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":5,"createDate":1688997033116,"auditID":106024},{"uiSession":"32 f983a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"c10d1389d6d14d29c74b05cb36087d76"," resource":"GET /portalapi/webjars/springfox-swagger-ui/fonts/titillium-web-v6-latin- 600.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":5,"createDate":1688997023250,"auditID":106023},{"uiSession":"32f983 a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"6b750857b939dc4717bcb9f00bb92484","reso urce":"GET /portalapi/webjars/springfox-swagger-ui/fonts/source-code-pro-v7-latin- 600.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":6,"createDate":1688996910420,"auditID":106022},{"uiSession":"32f983 a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"3154abc7e27272998711b7f9a9ce2f7f","reso urce":"GET /portalapi/webjars/springfox-swagger-ui/fonts/open-sans-v15-latin- regular.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":4,"createDate":1688996906822,"auditID":106019},{"uiSession":"32 f983a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"8bad0e684f521c9c9da13e05da46323f"," resource":"GET /portalapi/webjars/springfox-swagger-ui/fonts/source-code-pro-v7-latin- 300.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":4,"createDate":1688996906822,"auditID":106020},{"uiSession":"32f983 a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"752d72a633008162b8d05f17f32721b5","reso urce":"GET /portalapi/webjars/springfox-swagger-ui/fonts/open-sans-v15-latin- 700.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":6,"createDate":1688996906821,"auditID":106021},{"uiSession":"32f983 a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"e312c928e460ba8ccdb7b688c300de62","reso urce":"GET

/portalapi/csrf","status":"CLIENT_ERROR","statusCode":"404","durationMilSec":3,"createDate":1688996905663,"auditID":106017},{"uiSession"

:"32f983a23803678d736c3133680feaf62f83d08976c3143efa90b5dfe81312e9","sourceIp":"172.19.0.180","traceId":"da241dabd0225a8d0d88f1180995f0b d","resource":"GET /portalapi/webjars/springfox-swagger-ui/fonts/titillium-web-v6-latin- 700.woff2","status":"SUCCESSFUL","statusCode":"200","durationMilSec":4,"createDate":1688996905645,"a

Detailed steps available on https://docs.versa- networks.com/Management_and_Orchestration/Versa_Director/Director_REST_APIs/01_Versa_Director_REST_API_Overview#OAuth_APIs_for_Managing_ OAuth_Tokens

Versa Swagger Navigation

API documentation option page would come up, you can select as per your requirement, but if you are looking for audit logs for e.g. you an select “core Service” and it will navigate to the next page

You can navigate through multiple API lists available on this page

Clicking on the drop-down against each option shows you the available list of API’s.

How to get tenant UUID mapping for pre-tenant API calls

1) Get into the TenantEntity Management menu of Swagger

2) Click on /v1/tenants/summary

2) You can try out the API’s via Concerto Swagger itself to get the complete call

Sample API to fetch tenant’s summary and associated UUID

curl -i -k 'https://10.163.105.103/portalapi/v1/tenants/summary?hierarchical=false&nextWindowNumber=0&windowSize=0' -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI0YjEwMjE0ZDU2YjE3YjhlYzQ5NDQ1MjY4YWNkOTBjZDgyYWIzMWUxZjU4YWQ0NjIwZTQ0NDIzNDU2MzY3MDE2IiwiaWF0IjoxNjg4OTk 3NTEzLCJyb2xlIjoiUHJvdmlkZXJEYXRhQ2VudGVyU3lzdGVtQWRtaW4iLCJleHAiOjE2ODkwMDY1MTN9.Fvk9ffRtqEC76HR768uTCWLrR4tlAdbADDnHjAr5JGU"

Details about Swagger https://docs.versa-

networks.com/Management_and_Orchestration/Versa_Concerto_Orchestrator/02_Common_Configuration/A ccess_Versa_Concerto_REST_APIs_Using_Swagger_UI

Querying REST API using OAuth for Director/Concerto

Introduction

Requirement

Procedure for creating oAuth client

3. Oauth client details will be shown in the pop-up screen, after you click “ok”. Now, these values have to retained till the time token refresh is not needed.

REST API procedure using oauth client-id & client-secret

1. API call for creating a “TOKEN”, we use the generated client-id, client-secret + username and password of the Director with “ProviderDatacenterSystemAdmin” or ProviderDatacenterAdmin”

Snippet of the code sample

2. This step will generate a token key, which shall be used for our future API requests.

successful Output:

3. Use the token key for API operation to the Concerto.

Sample-1 API (check list of tenants summary)

Response

Sample-2 API (check list of tenants summary)

Response

Versa Swagger Navigation

How to get tenant UUID mapping for pre-tenant API calls

1) Get into the TenantEntity Management menu of Swagger

2) You can try out the API’s via Concerto Swagger itself to get the complete call

More articles in Concerto