Jira Entitlement
Overview
Entitlement resource in IDHub maps to Group and Project Roles in Jira.
Groups contain members that indicate the User Accounts that are part of the Group. After creating a Group in Jira, the Group is updated using PATCH to add User Accounts as members.
Projects contain roles for different users/groups. Project Roles for a group/user can be revoked/modified/added as per requirement.
#Note : Entitlement name for Project Role Entitlement should be added as : <Role Name> in <Project Name> project
Entitlement Resource Schema Configuration
After creating a directory in the Atlassian Admin account for a specific domain, the provisioning APIs for the Group Resource can be called using the directoryId. For Project Roles, Jira Cloud Rest APIs need to be called.
Entitlement Resource Type
The Entitlement resource type schema is as follows :
{
"schemas" : [
"urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id" : "Entitlement",
"name" : "Entitlement",
"description" : "This resource creates/modifies/deletes Entitlements in Jira and returns your query to you in some form depending on the normal format of the endpoint (Resource or ListResponse).",
"endpoint" : "Entitlements",
"schema" : "urn:sath:params:scim:api:confluence:1.0:Entitlement"
}
Entitlement Schema Representation
The Entitlement schema is as follows :
{
"schemas" : [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id" : "urn:sath:params:scim:api:confluence:1.0:Entitlement",
"name" : "Entitlement",
"description" : "To perform operations on confluence Entitlements like group membership/ project roles",
"attributes" : [
{
"name" : "description",
"multiValued" : false,
"description" : "The description of the Entitlement. If Kind = GROUP, description is This is a Jira Group. If Kind = PROJECT_ROLE, description is This is a Jira Project Role. OPTIONAL."
},
{
"name" : "displayName",
"multiValued" : false,
"description" : "The displayName of the Entitlement. Format: Kind~<Entitlement Name>. REQUIRED.",
"required" : true
},
{
"name" : "externalId",
"multiValued" : false,
"description" : "A String that is an identifier for the resource as defined by the provisioning client. The \"externalId\" may simplify identification of a resource between the provisioning client and the service provider by allowing the client to use a filter to locate the resource with an identifier from the provisioning domain, obviating the need to store a local mapping between the provisioning domain's identifier of the resource and the identifier used by the service provider. Each resource MAY include a non-empty \"externalId\" value. The value of the \"externalId\" attribute is always issued by the provisioning client and MUST NOT be specified by the service provider. The service provider MUST always interpret the externalId as scoped to the provisioning domain. While the server does not enforce uniqueness, it is assumed that the value's uniqueness is controlled by the client setting the value. See Section 9 for additional considerations regarding privacy. This attribute has \"caseExact\" as \"true\" and a mutability of \"readWrite\". This attribute is OPTIONAL.\n",
"mutability" : "readOnly",
"returned" : "always",
"caseExact" : true
},
{
"name" : "id",
"multiValued" : false,
"description" : "The complex id of the Entitlement. Format: Kind~<EntitlementID>.REQUIRED.",
"returned" : "always",
"caseExact" : true,
"required" : true
},
{
"name" : "meta",
"multiValued" : false,
"description" : "A complex attribute containing resource metadata.",
"mutability" : "readOnly",
"subAttributes" : [
{
"name" : "resourceType",
"multiValued" : false,
"description" : "The name of the resource type of the resource.",
"mutability" : "readOnly",
"caseExact" : true
},
{
"name" : "created",
"multiValued" : false,
"type" : "dateTime",
"description" : "The \"DateTime\" that the resource was added to the service provider."
},
{
"name" : "lastModified",
"multiValued" : false,
"type" : "dateTime",
"description" : "The most recent DateTime that the details of this resource were updated at the service provider. If this resource has never been modified since its initial creation, the value MUST be the same as the value of \"created\"."
},
{
"name" : "location",
"multiValued" : false,
"description" : "The name of the resource type of the resource.",
"mutability" : "readOnly",
"caseExact" : true
},
{
"name" : "version",
"multiValued" : false,
"description" : "The version of the resource being returned. This value must be the same as the entity-tag (ETag) HTTP response header (see Sections 2.1 and 2.3 of [RFC7232]). This attribute has \"caseExact\" as \"true\". Service provider support for this attribute is optional and subject to the service provider's support for versioning (see Section 3.14 of [RFC7644]). If a service provider provides \"version\" (entity-tag) for a representation and the generation of that entity-tag does not satisfy all of the characteristics of a strong validator (see Section 2.1 of [RFC7232]), then the origin server MUST mark the \"version\" (entity-tag) as weak by prefixing its opaque value with \"W/\" (case sensitive).",
"mutability" : "readOnly",
"caseExact" : true
}
]
},
{
"name" : "schemas",
"multiValued" : true,
"description" : "The \"schemas\" attribute is a REQUIRED attribute and is an array of Strings containing URIs that are used to indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure. This attribute may be used by parsers to define the attributes present in the JSON structure that is the body to an HTTP request or response. Each String value must be a unique URI. All representations of SCIM schemas MUST include a non-empty array with value(s) of the URIs supported by that representation. The \"schemas\" attribute for a resource MUST only contain values defined as \"schema\" and \"schemaExtensions\" for the resource's defined \"resourceType\". Duplicate values MUST NOT be included. Value order is not specified and MUST NOT impact behavior.",
"mutability" : "readOnly",
"returned" : "always",
"caseExact" : true,
"required" : true
}
]
}
Schema to create different entitlements
For creating different entitlements, the payload should be compatible with the schema representation of the different resources as in Jira.
Note : 1. CRUD operations on entitlements are not part of current scope
Group Schema Representation | Project Schema Representation |
---|---|
CODE
|
CODE
|
Project Role Schema
Schema Representation | Sample Project Role Payload |
---|---|
CODE
|
CODE
|
#Note : Project roles cannot be modified in free Atlassian Access
Implementation
The following methods of the target system connector interface defined in the connector SPI needs to be implemented for Entitlement(Group, Project Role) resource.
Get Schema
CODE
|
Get Resource Type
CODE
|
Get SCIM Resource Service Information
CODE
|
Get Health
CODE
|
Create Resource
CODE
|
Get Resource
CODE
|
Replace Resource
CODE
|
Update Resource
CODE
|
Delete Resource
public void deleteResource(String id) throws ConflictException, NotFoundException, InternalServerErrorException, NotImplementedException {
//for Group resource
call https://api.atlassian.com/scim/directory/{directoryId}/Groups/{id} with Authorization as header
//for Project Role resource
throw NotImplementedException
if no resource exists for the given id
throw NotFoundException
if error occurs during resource creation
throw InternalServerErrorException
if no logic is implemented
throw NotImplementedException
}
Search Resource -
public ListResponse searchResource(SearchRequest searchRequest) throws BadRequestException, PayloadTooLargeException, InternalServerErrorException, NotImplementedException {
if the filter parameter is empty
return all(*) instances of the given resource type are returned
//for group resource
call https://api.atlassian.com/scim/directory/{directoryId}/Groups with Authorization and Accept as headers
//for project role resource
call https://iamsath.atlassian.net/rest/api/3/project/{projectIdOrKey}/role with admin api key and Accept as headers
in case of multiple pages, pagination can be done using start and limit in query parameters
if searchRequest is unparsable, syntactically incorrect, or violates schema
throw BadRequestException
if payload size in bytes exceeds the max payload size
throw PayloadTooLargeException
if error occurs during resource search
throw InternalServerErrorException
if no logic is implemented
throw NotImplementedException
return the list of resource objects matching the searchRequest
}