Omada Identity Graph API
Overview
Omada Identity customers can integrate access request workflows directly within other clients through Omada Identity Graph API. It is Omada Everywhere initiative, building capabilities for third parties to build clients for Omada’s access processes.
With the release of the May 2023 Cloud Update, Omada now supports third parties building Access Request clients based on version 2.0 of our Graph API.
Version 1.0 and Version 1.1 are not supported.
Version 2.0 supports:
- Creating and submitting access requests to Omada cloud environments
- List submitted access requests and their status
More specifically:
- Request for one or more identities
- Request for one or more resources
- Support for Server-side hidden and Requires value settings for the Business Context field
- Support for Server-side hidden and Requires value settings for the Reason field
- Resources with visible attributes
- Support multiple accounts
- Set validity period
- List of submitted access requests (requests or resource assignments)
- Report request status
- Filter on resources and attributes
For information on authentication, refer to the OAuth Auhentication section in the documentation.
Changelog
-
Version 2.6
- Added new accessApprovalSurveyConfiguration query
- Added new filter workflowStep filter in the
- accessRequestApprovalSurveyQuestions query
-
Version 2.5
New queries:
- ResourceType
- ResourceOwner
- Contexts
- accessRequestConfiguration
-
Version 2.4
- New query accessRequestApprovalSurveyQuestions
- New mutation SubmitRequestQuestions
- New riskLevel fields to:
- ResourceType
- IdentityType
-
Version 2.3
- Changed all Datetimes to return their values in UTC format
- New query userSettings
-
Version 2.2
New query extendAccessRequests
-
Version 2.1
New queries:
- identitiesCanRequestResource
- extendableResourceAssignments
New mutation extendAccess
All queries which supports pagination and accessRequests have been wrapped into a new type, paginationListType, with fields:
- Data
- Total
- Pages
New types: identityResourcesInputType
Changes to:
- accessRequestAsResourcesInputType: reason has been made nullable, added identityResources
- accessRequestAsTextInputType: reason has been made nullable
- accessRequestType: validFrom and validTo has been made nullable, added reason and resourceAssignmentId
- contextType: has been renamed to displayName
New fields to:
- resourceType: resourceCategory, resourceType, resourceFolder and accountTypes
- accessRequestConfigurationType: isAccountRequired, isReasonRequired and defaultAccountType
New fields to:
- IdentityType: IdentityType and accounts
- ResourceInputType: AccountInfo
-
Version 2.0
New queries:
- textBasedAccessRequest
- textBasedAccessRequestsByIds
- accessRequestsByIds There is a bug in this version when requesting access to a resource that contains child resources. The data is not loading, and an exception is being recorded in the event log.
-
Version 1.1
Added support of Attributes in the Resource type.
-
Version 1.0
Initial release of the API
Enabling the GraphiQL browser page
Prerequisites
- Enable the new user interface (UI).
- Graphiql browser page should only be enabled in test or development environments (not in production).
Steps
-
Open the ticket is Omada Service Desk Support to set the API Documentation UI Enabled customer setting to TRUE.
-
Enter the URL, for example:
https://< instancename>.omada.cloud//ApiDoc.aspx?api=domain&version=X.X/.
If no version (X.X) is chosen, 1.0 will be selected by default.
Use of DomainApi to create Access Requests
-
Use the basic queries to determine the lists of: reasons, systems, and optionally context.
{
accessRequest{
reasons{
id
name
}
systems(filter: "Active directory", sortColumn: "name", sortOrder:DESC page: 1, rows: 5){
id
name
}
context(identityIds: ["cf12e9f1-1cf8-4a75-b189-26a0677fdc01"], ){
id
name
}
}
}noteThe context property is optional.
-
Use the resources query to, optionally with a systemId as input, get a list of applicable resources for the user to choose between. Be sure to respect the intent of the flag includeThirdPartyExcludedResources.
{
accessRequest{
resources(systemId: "590c58a0-fdee-4d44-83ea-8b20911af15e", includeThirdPartyExcludedResources: false)
id
name
}
} -
Call the mutation createAccessRequest with the parameter accessRequest being an object that looks like this:
mutation {
createAccessRequest(accessRequest:{
reason: "Need additional access",
validFrom: "2022-06-01T11:11:11Z"
validTo: "2022-10-01T11:11:11Z"
businessContext: "1a53fe46-de0a-4d36-b160-25799a0082b7",
identities: [{id: "cf12e9f1-1cf8-4a75-b189-26a0677fdc01"}],
resources: [{id: "b366b716-4022-4328-98a1-36f9a1cc2525"}]
}){
id
}
} -
Use the accessRequest query to get status of your access-request.
{
accessRequests (ids: ["1f195673-e33b-44c7-b1b3-698e3f04a717"]){
id
beneficiary{
id
firstName
lastName
displayName
}
requestedBy{
id
firstName
lastName
}
resource{
id
name
}
status{
approvalStatus
}
}
}
If you don’t include the ids-parameter, you will get all the access-requests created by the user.
Graph API filter search
The accessRequestComponents/resources query offers enhanced filtering capabilities. It allows filtering based on attributes such as resourceOwnerId, resourceTypeId, and contextObjectId, which points to objects belonging to a context associated with the resource.
- resourceTypeId sample query:
query getResourceTypes {
accessRequestComponents {
resourceTypes {
data {
id
name
}
pages
total
}
}
- resourceTypeId sample result:
{
"data": {
"accessRequestComponents": {
"resourceTypes": {
"data": [
{
"id": "847f63f6-dd32-40d5-8bab-2acd0c636d80",
"name": "Identity Manager Role"
},
{
"id": "5bd6c538-ae25-4e4d-85dc-069d0fa6ebf0",
"name": "Org. Unit Manager Role"
},
...
{
"id": "2c463d75-7e0d-4008-88e2-85996aa7d55b",
"name": "Omada Identity Account"
}
],
"pages": 0,
"total": 31
}
}
}
}
}
- resourceOwnerId sample query:
query GetUsers {
accessRequestComponents {
users{
data {
id
displayName
}
pages
total
}
}
}
- resourceOwnerId sample result:
{
"data": {
"accessRequestComponents": {
"users": {
"data": [
{
"id": "a3527a28-4365-4674-9797-939c995247f7",
"displayName": "System Administrator"
},
{
"id": "d3ef74e8-aea9-4a8a-9aa4-1c3e4f327331",
"displayName": "Eric Cantona"
},
{
"id": "2c86dfa7-823f-44df-9c2b-4e0abf6761a8",
"displayName": "Alex Ferguson"
},
{
"id": "57f6f100-3e33-4574-b150-d222ebdc246c",
"displayName": "Dennis Bergkamp"
}
],
"pages": 0,
"total": 4
}
}
}
}
}
- contextObjectId sample query:
query GetDataObjectsInContext {
accessRequestComponents {
dataObjectsInContexts {
displayName
id
type
typeId
}
}
}
- contextObjectId sample result:
{
"data": {
"accessRequestComponents": {
"dataObjectsInContexts": [
{
"displayName": "Customer identities [CUSTIDENTS]",
"id": "ba9c8ebb-3336-48ea-bfdf-b611e8bf7806",
"type": "OrgUnit",
"typeId": "3178bf72-a4c5-4aed-9084-6bb99aa42510"
},
{
"displayName": "Department1 [DEPT1]",
"id": "ea5ecc7b-c8f4-45a0-b8d0-a208c721b0fc",
"type": "OrgUnit",
"typeId": "3178bf72-a4c5-4aed-9084-6bb99aa42510"
},
{
"displayName": "Department2 [DEPT2]",
"id": "935a24e5-ce12-4258-8be2-25be1e2b6a92",
"type": "OrgUnit",
"typeId": "3178bf72-a4c5-4aed-9084-6bb99aa42510"
},
{
"displayName": "Organization [ORGANIZATION]",
"id": "60ccec0c-dad1-4df8-bb09-c77f15029fcd",
"type": "OrgUnit",
"typeId": "3178bf72-a4c5-4aed-9084-6bb99aa42510"
},
{
"displayName": "Technical identities [TECHIDENTS]",
"id": "31056ff3-e08b-4350-b94c-e8a508c64cc8",
"type": "OrgUnit",
"typeId": "3178bf72-a4c5-4aed-9084-6bb99aa42510"
}
]
}
}
}
References
For further reference on GraphQL APIs and GraphiQL, see the following resources: