Pre-requisites
Developers will need an access token to call any API. The APIs are secured with OAuth and administrator should use the API Access panel to manage access/permissions. The “Getting started with IBM Cloud Identity REST APIs” article helps you through the requisite steps in setting up an API Client and obtaining an access token. In this article we will demonstrate to create the access policy to restrict the application access from certain IP range.
Note: In order to use APIs related to access policy developer need access token generated using API client having “Manage access policies” access enabled.
API Documentation
The API documentation for your tenant is located here:
https://mytenant.ice.ibmcloud.com/developer/explorer/#/Access_Policy_Management
Note: Replace mytenant.ice.ibmcloud.com with your tenant and in the rest of the examples below.
Create Access Policy
In order to create a new access policy for having rule to restrict access from some IP range, developer can use below API with the example payload:
curl -X POST \
https://mytenant.ice.ibmcloud.com/v1.0/policyvault/accesspolicy \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Your access token>' \
-H 'Content-Type: application/json' \
-d '{
"name":"Restrict IP",
"description":"Restrict IP",
"format":"json",
"rules":[{
"id":"1568268977977",
"name":"A IP rule",
"conditions": {
"ipAddress": {
"opCode":"MATCH",
"values":["192.168.250.1-192.168.250.254"]
}
},
"result": {
"action": {
"allowAccess":false,
"requireFactor":false
},
"authnMethods":["urn:ibm:security:authentication:asf:macotp"]
}
},
{
"id":"1568268911087",
"name":"Default rule",
"conditions":{},
"result":{
"action":{
"allowAccess":true,
"requireFactor":false
},
"authnMethods":["urn:ibm:security:authentication:asf:macotp"]
}
}
],
"schemaVersion":"urn:access:policy:3.0:schema"
}'
In above example in “conditions” block we are defining rule as to “MATCH” ipAddress within values "192.168.250.1-192.168.250.254" and if matched "action" is to block access defined as "allowAccess":false. The “Default rule” is set as to "allowAccess":true
The successful execution of above API will return code as 201 for policy getting created. Developer can look at “location” response header to fetch the Id of newly created access policy. Example location header will be https:// mytenant.ice.ibmcloud.com /v1.0/policyvault/accesspolicy/XXXXX where XXXXX is the Id of the newly created access policy
Get Access Policy
In order to get fetch details of the policy created above, use the below API
curl -X GET \
https://mytenant.ice.ibmcloud.com/v1.0/policyvault/accesspolicy/XXXXX \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Your access token>'
The successful call for GET API will return response code as 200 and example payload as below:
{
"schemaVersion":"urn:access:policy:3.0:schema",
"name":"Restrict IP",
"format":"json",
"description":"Restrict IP",
"rules":[
{
"result":{
"action":{
"allowAccess":false,
"requireFactor":false
},
"authnMethods":[
"urn:ibm:security:authentication:asf:macotp"
]
},
"name":"A IP rule",
"id":"1568268977977",
"conditions":{
"ipAddress":{
"values":[
"192.168.250.1-192.168.250.254"
],
"opCode":"MATCH"
}
}
},
{
"result":{
"action":{
"allowAccess":true,
"requireFactor":false
},
"authnMethods":[
"urn:ibm:security:authentication:asf:macotp"
]
},
"name":"Default rule",
"id":"1568268911087",
"conditions":{
}
}
],
"id":"110976",
"validations":{
"subscriptionsNeeded":[
"conditional.access",
"mfa.authn"
]
},
"version":1,
"predefined":false
}
Note that the “version” returned in response. This version number is required to update the access policy
Update Access Policy
In order to update the existing access policy (may be to change the rule) developer can use below API to modify the existing access policy:
curl -X PUT \
https://mytenant.ice.ibmcloud.com/v1.0/policyvault/accesspolicy/XXXXX \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Your access token>\
-H 'Content-Type: application/json' \
-H 'If-Match: 1' \
-d '{
"name":"Restrict IP Updated",
"description":"Restrict IP updated",
"format":"json",
"rules":[{
"id":"1568268977977",
"name":"A IP rule",
"conditions": {
"ipAddress": {
"opCode":"MATCH",
"values":["192.106.250.1-192.106.250.254"]
}
},
"result": {
"action": {
"allowAccess":false,
"requireFactor":false
},
"authnMethods":["urn:ibm:security:authentication:asf:macotp"]
}
},
{
"id":"1568268911087",
"name":"Default rule",
"conditions":{},
"result":{
"action":{
"allowAccess":true,
"requireFactor":false
},
"authnMethods":["urn:ibm:security:authentication:asf:macotp"]
}
} ],
"schemaVersion":"urn:access:policy:3.0:schema"
}'
Watch for the 'If-Match' header which need to be passed as current version of the policy. Any mismatch with current version will not update the policy and API will give error.
In above payload we have updated the restricted IP address to new range as "192.106.250.1-192.106.250.254"
Successful execution of API will return the response code as 204
Delete Access Policy
In order to delete any existing access policy developer can use below API:
curl -X DELETE \
https://mytenant.ice.ibmcloud.com/v1.0/policyvault/accesspolicy/XXXXX \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <Your access token>'
Successful execution of above API will return the response code as 204 and the policy will get permanently removed from the system
Note: Below are the cases when access policy can not be deleted:
- System defined access policy
- When the custom access policy is assigned to any application
- When the custom access policy is used as policy for Administration console access
- When the custom access policy is used as policy for Home page access