Access Request Conditions APIs

With the release of Resource Centric Access Request in Okta Identity Governance (OIG), creating and managing access requests have been further simplified. Now, these capabilities can be leveraged using the OIG APIs as well. Below we will see how we can use each of these APIs.

Overview

With the new Resource Centric Access Request, OIG provides a more centralized and integrated way of creating and managing Access Requests. The whole flow of creating access requests now requires creation of conditions and sequences. Conditions are the flow in which the various stages of access requests will be defined such as which users will be able to place a request, what kind of access users can request, defining time limitations for the requests, etc. Sequences help to define who can approve a request, how many levels of approvals there can be, etc. It is integrated within Conditions but is defined independently of it. With new OIG Access Requests APIs, organizations can now create Conditions and Sequences using APIs.

Applies To

• OIG Access Request v2 (Resource Centric Access Requests)

Solution

Visit Okta Identity Governance API site for more detailed information on OIG APIs and reference this article, which guides on how to navigate through the API Documentation. As with every API, this document will be describing the API, its HTTP request-type, its payload and expected result.

Managing Request Conditions

Conditions are used to define the different stages of the access request as well as what resources and access levels requesters can request from their resource catalog. Using the new OIG Access Request APIs, users can perform the below operations on Conditions:

Create a Request Condition

Using this API, users can create a new request Condition for any of the given resources. There are various parameters, as shown below in the Payload section below, involved in creating a request Condition, which governs what type of condition is being created. By using different combinations of these parameters different types of request Conditions can be created to fit the requirement.

In this doc, we will be focusing on a single scenario, where a request Condition needs to be created as per the below requirements:

1. Users can request access to a particular group associated with the resource.

2. Everyone in the organization should be able to use this condition to place an access request.

Prerequisites

The create request Condition API provides the below path parameters which can be used to create specific request Conditions. A more comprehensive detail of these parameters is present in the API docs.

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• name

  • The name of the Condition to be created.

• description

  • The description for the Condition to be created.

• resourceId

  • The id of the resource, which is the application, for which this Condition has to be created. The id of the application can be retrieved from the application URL in Okta.

• requesterSettings

  • It defines who all in the org can access and use this request Condition to place an access request.

• approvalSequenceId

  • The id of the request Sequence that is to be used for this Condition. This is a mandatory parameter and it can be found from the URL for the Sequence in Okta.

• accessScopeSettings

  • It specifies the group or entitlements for that particular resource, for which users can place an access request.

• accessDurationSettings

  • It specifies the time duration for the access requested to be valid. Once the time limit has been reached the access will be auto-revoked.

• priority

  • It sets the priority of the request Condition.

• groups id

  • It can be found in the URL for the group in Okta.

Payload

In order to create a request Condition as per the above mentioned requirements, a payload has to be formulated as given below:

{

  "name": "Test Group Access",

  "description": "This is a condition for requesting access to test group within XYZ application",

  "approvalSequenceId": "669a0dbdc2c76f00063a4aeb",

  "requesterSettings": {

    "type": "EVERYONE"

  },

  "accessScopeSettings": {

    "type": "GROUPS",

    "groups": [

    {

    "id": "00gew20ztc1YuosW81d7"

    },

    {

    "id": "00gew2tj1fp2Ew1oj1d7"

    }

  ]

  },

"priority": 0

}

Note: The payload contains only the path parameters required for creating the specified request condition. Depending on the requirements other path parameters can be added or modified to the payload for creating more specific request conditions.

Execution

This API can be executed from any API Platform or using curl or from any code base. Throughout this doc, postman will be used to run the APIs. 

The URL to run this API is as mentioned below, which includes two variables i.e yourOktaDomain and resourceId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{resourceId}/request-conditions

Response

On successful execution of this request, Postman will provide a response of 201 Created along with the below response body. 

NOTE: After the successful creation of request Condition, it stays in Inactive status and has to be set to active state before users can start using it.
 

List all Request Condition

Using this API, users can fetch all the request Conditions present for a specific resource. It provides both active and inactive request Conditions in the results.

Prerequisite

To execute this API, below path parameters are required

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which all the request Conditions has to be fetched.

Payload

Since, this API is a GET operation it does not require any payload. 

Execution

The URL to run this API is as mentioned below, which includes two variables i.e yourOktaDomain and resourceId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions

Response

On successful execution of this request, Postman will provide a response of 200 OK along with the below response body. The response body contains the list of all request Conditions for that resource.

Retrieve a resource request condition

Using this API, users can retrieve the details of a specific request Condition. 

Prerequisites

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which this Condition has to be created.

• requestConditionId

  • The id of the request Condition, of which the details need to be fetched. It can be obtained from the List All Condition API results.

Payload

Since this is a GET operation on the API, it does not require any payload. 

Execution

The URL to run this API is as mentioned below, which includes three variables i.e yourOktaDomain, resourceId and requestConditionId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions/{{requestConditionId}}

Response

On successful execution of this request, Postman will provide a response of 200 OK along with the below response body. The output also provides more information such as Created By, Created On, lastUpdated On and lastUpdated By.

Delete a request condition

Using this API, users can delete a specific request Condition of a specific resource.

Prerequisite

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which this Condition has to be created.

• requestConditionId

  • The id of the request Condition, of which the details need to be fetched. It can be obtained from the List All Condition API results.

• status

  • The status of the request Condition to be deleted should be inactive.

Payload

Since, this is a DELETE operation it does not require any payload. 

Execution

The URL to run this API is as mentioned below, which includes three variables i.e yourOktaDomain, resourceId and requestConditionId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions/{{requestConditionId}}

Response

On successful execution of this request, Postman will provide a response of 204 No Content along with an empty body. 

 
Update a request condition

Using this API, users can update a specific request Condition of a specific resource. The path parameters which can be updated using this API are as below

• requesterSettings

  • It defines who all in the org can access and use this request Condition to place an access request.

• approvalSequenceId

  • The id of the request Sequence that is to be used for this Condition.

• accessScopeSettings

  • It specifies the group or entitlements for that particular resource, for which users can place an access request.

• accessDurationSettings

  • It specifies the time duration for the access requested to be valid. Once the time limit has been reached the access will be auto-revoked.

• priority

  • It sets the priority of the request Condition.

Prerequisite

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which this Condition has to be created.

• requestConditionId

  • The id of the request Condition, of which the details need to be fetched. It can be obtained from the List All Condition API results.

Payload

Since this is an update operation, a payload has to be created as per the requirements. In this example, the request Condition which is created Execution, will be updated with a new group id for that resource. Therefore, the payload only contains the accessScopeSettings with the new group id.

{

    "accessScopeSettings": {

            "type": "GROUPS",

            "groups": [

                {

                    "id": "00gfxkshnlsoo0xuX1d7"

                }

            ]

    }

}

Execution

The URL to run this API is as mentioned below, which includes three variables i.e yourOktaDomain, resourceId and requestConditionId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions/{{requestConditionId}}

Response

On successful execution of this request, Postman will provide a response of 200 OK along with the below response body.

In this example, it can be seen that the accessScopeSettings has been updated to contain just one group which is again different from the previous groups.

Activate the request condition

Using this API, users can activate a request Condition which is in an inactive state.

Prerequisite

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which this Condition has to be created.

• requestConditionId

  • The id of the request Condition, of which the details need to be fetched. It can be obtained from the List All Condition API results.

Payload

Since, this is an operation to activate the request Condition, which does not require any payload.

Execution

The URL to run this API is as mentioned below, which includes three variables i.e yourOktaDomain, resourceId and requestConditionId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions/{{requestConditionId}}/activate

Response

On successful execution of this request, Postman will provide a response of 200 OK along with the below response body, which shows the status of the request Condition as “ACTIVE”

Deactivate the request condition

Using this API, users can deactivate a request Condition which is in active state.

Prerequisite

• yourOktaDomain

  • The url for the organization’s Okta account. For eg: https://acme.okta.com

• resourceId

  • The id of the resource for which this Condition has to be created.

• requestConditionId

  • The id of the request Condition, of which the details need to be fetched. It can be obtained from the List All Condition API results.

Payload

Since, this is a Deactivate operation it does not require any payload. 

Execution

The URL to run this API is as mentioned below, which includes three variables i.e yourOktaDomain, resourceId and requestConditionId. The details about these variables are present in the Prerequisite section.

https://{yourOktaDomain}/governance/api/v2/resources/{{resourceId}}/request-conditions/{{requestConditionId}}/deactivate

Response

On successful execution of this request, Postman will provide a response of 200 OK along with the response body below, which shows the status of the request Condition as “INACTIVE.”