Overview
Labels are vital for categorizing information within Okta Identity Governance (OIG). This guide will focus on their common use in Identity Governance and Administration (IGA) for managing requestable resources.
Resource labels in Okta serve as metadata to enhance context for resources. These labels enable administrators to efficiently locate resources that meet specific criteria and streamline governance configurations. To view labels in the Okta Admin Console, administrators must have a role that includes the "View labels" permission.
Resource labels are structured as (key, value) pairs. The resource label key acts as a name encompassing all associated values. Additionally, multiple labels can be assigned to the same resources.
Consider a scenario where labels are used to identify requestable resources. An organization could define a label key "Resources" with a value of "Requestable". Any resource that users are able to request, such as specific applications or access roles, would then have the "Resources: Requestable" label applied to it. This allows administrators to target those applications within an Access Certification campaign and via API for reporting.
NOTE: Not all resources show the associated labels at this time but will be added in future releases. Once assigned, all are visible via API, and Access Certifications is label aware. The adoption of this feature will expand to Access Requests in the future.
-
Max 10 custom labels, with each having up to 10 values for a total of 100 resource labels
-
Labels are case-insensitive
-
Each resource can be assigned up to 10 labels
Use Cases
-
Resources within Okta that are labeled as requestable and can be managed.
-
Resources that need to be targeted within an Access Certification campaign.
-
Resources that need to be included in a Security Access Review.
-
Resources within Okta using labels can be targeted within Access Certification campaigns.
-
Labels and resources with labels will be managed by API.
Third-party Integration
Migration:
Most third-party Identity Governance and Administration (IGA) tools offer a way to track requestable items within an organization. The initial step in migrating to a new system is to establish a connection with the existing third-party IGA tool.
The following process details the migration from an existing IGA tool. After all items have been migrated and assigned a resource label, new resources that are onboarded will also require resource label assignments.
This process uses the Okta Catalog for Access Request ingestion. Therefore, all reporting on access requests will be available with the Okta reports and via API.
Sync:
Third-party systems will need to synchronize a list of requestable resources from Okta initially using the API. Maintaining that list in their system could be done as a synchronization process or when new resources are onboarded. See the API examples included in this article.
SUPPORTED RESOURCE TYPES
-
Applications
-
Groups
-
Entitlements Values
-
Entitlements Bundles
-
Collections
ASSUMPTIONS
-
As part of the onboarding of applications, labels should be assigned to identify requestable resources, including entitlement values, entitlement bundles, applications, and collections.
-
The API will be used to assign labels to resources during the creation/update process.
LABEL API
Labels are created and assigned using the Label API.
Create a label:
The API enables you to create new labels on resources in the Okta environment. The API consists of a name and a list of values, including a set of pre-defined colors (red, orange, yellow, green, blue, purple, teal, beige, and gray).
Create a Resource Label with a Label value called “Requestable”. See the supplied workflow templates for working examples.
POST - https://{OktaDomain}/governance/api/v1/labels
Payload:
{
-
"name": "Resources", -
"values": [-
{-
"name": "Requestable", -
"metadata": {-
"additionalProperties": {-
"backgroundColor": "blue"
} -
} -
} -
] -
}
List all labels:
The API enables looking up all existing labels. The label ID needed for updates and/or DELETE is found in this response.
GET - https://{OktaDomain}/governance/api/v1/labels
RESPONSE:
{
"data": [
{
"labelId": "lbc131rxgxObK3rfT1d7",
"name": "Resources",
"values": [
{
"labelValueId": "lbl131rxgyyeuMEzE1d7",
"name": "Requestable",
"metadata": {
"additionalProperties": {
"backgroundColor": "blue"
}
}
}
],
"_links": {
"self": {
"href": "https://{OktaDomain}.okta.com/governance/api/v1/labels/lbc131rxgxObK3rfT1d7",
"hints": {}
}
}
}
],
"_links": {
"self": {
"href": "https://{OktaDomain}.okta.com/governance/api/v1/labels",
"hints": {}
}
}
}
Retrieve a label:
The API enables looking up a label based on a label ID. The label needed for updates and/or DELETE is found in this response.
GET - https://{OktaDomain}/governance/api/v1/labels/{labelId}
Assign the labels to resources:
The API enables you to assign an existing label to one of the supported resource types listed above. See Understanding Okta Resource Name (ORN) for use in the payload.
POST - https://{OktaDomain}/governance/api/v1/resource-labels/assign
Payload:
{
"resourceOrns": [
"orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-bundles:enbogpaj3XUzcM62u1d6",
"orn:okta:governance:00o11edPwGqbUrsDm0g4:collections:cologpaj3XUzcM62u1d6",
"orn:okta:governance:00o11rndFqmZ5rNfs0g4:entitlement-values:ent63C22YQoNMWOJf0g2"
],
"labelValueIds": [
"lblo3v6xlwdtEX2il1d1"
]
}
Delete a label:
The API enables the deletion of existing labels that are not currently assigned to any resources. NOTE: Deletion will not complete if the label is assigned to any resources.
Deleting an existing label requires supplying the label ID, which can be located by calling the List all Labels API referenced in the guide. The format of a Label ID will begin with "lbc" and be followed by a string of characters.
DELETE - https://{OktaDomain}/governance/api/v1/labels/{labelId}
Example:https://{OktaDomain}/governance/api/v1/labels/lbc131rxgxObK3rfT1d7
NOTE: The Example workflows are downloadable on the Okta Developer Community. Search for OIG under workflow templates.
Refer to the API for other supported APIs related to Labels:
Summary
This article outlines how to manage requestable resources using Labels within Okta, focusing on their use for identifying and organizing information. It details the capabilities and limitations of Okta Labels, including the maximum number of labels and values, as well as their case-insensitivity. Key use cases discussed are labeling resources as "requestable" for targeting Access Certification campaigns.
The article details the migration of third-party integrations, outlining the process of synchronizing requestable resources from third-party systems (such as SailPoint) to Okta. It then covers the assignment of labels to these new resources. The article also specifies the supported resource types — Applications, Groups, Entitlement Values, Entitlement Bundles, and Collections — and the assumptions for label assignment during the onboarding and creation processes.
The article then provides a comprehensive guide to the Label API, including examples for:
-
Creating a label (specifically a "Resource" label with a "Requestable" value).
-
Listing all existing labels.
-
Retrieving a specific label by ID.
-
Assigning labels to various resource types.
-
Deleting labels that are not in use.
Related References
