2 Resources

The OHSIAMS Inbound User Provisioning Service API exposes resources through distinct URLs and the HTTP method calls dictate the action that is required to be performed on the identified resource. OHSIAMS resources include Users, Groups, and Bulk.

2.1 URL Taxonomy

The OHSIAMS Inbound User Provisioning Service API follows the URL taxonomy:

https://hs-identity-api.us.oracleindustry.com/scim/v1/<tenant>/<resource>

where

<tenant> determines the tenancy of the target resource. The OIM entitlements validate whether the authenticated user has the appropriate privileges to create or read resources in the specified tenant.

<resource> can be:

/Users
/Users/{id}
/Groups
/Groups/{groupname}
/Bulk

2.2 REST Resource Endpoints

The resources component provides the REST resource endpoints as described in the SCIM specification.

2.2.1 Users

The /Users resource endpoint handles user management operations.

Table 2-1 Using HTTP Methods with the Users Resource Endpoint

HTTP Method	Path	Description
GET	/Users/{id}	Given the ID of the user, returns the OIM user, if it exists.
GET	/Users?filter={filterName} eq "<username \| externalId>"&attributes={comma separated attributes}	Searching for the user requires a filter. Supported filters are userName and externalId. The accepted operator is eq. Attributes is optional.
POST	/Users	Creates a user in OIM. Existing OHSIAMS validations apply while creating the user.
PUT	/Users/{id}	Replaces all the attributes of the user. If an attribute is not specified, the value is removed from the user in OIM.
PATCH	/Users/{id}	Updates only the specified attributes.
DELETE*	/Users/{id}	To maintain audit history, you cannot delete a user in the OHSIAMS application. Instead, the account is disabled and all the current roles and groups are revoked for this user account.

*After a user is deleted, when a new user request is received that matches the deleted (disabled) username in OIM, the application returns a 303 Redirect response with the location of the disabled user. You can either enable the user at this location or pick a new username and resubmit the request.

If the username in the new user request matches an active user, the application returns a 412 Precondition Failed with username already exists error message.

2.2.2 Groups

The /Groups resource endpoint handles group management operations.

Table 2-2 Using HTTP Methods with the Groups Resource Endpoint

HTTP Method	Path	Description
GET	/Groups/{groupname}	Given the groupname, returns the group description and the list of OIM users currently assigned to the group.
GET	/Groups	Returns a list of groupnames under the given tenant.
PATCH	/Groups/groupname	Updates the group membership.

Note:

Creation and deletion of a role in OIM is not supported for the tenant administrator role. Therefore, there is no support for the POST and DELETE operations.

2.2.3 Bulk

The /Bulk resource endpoint handles bulk operations.

Table 2-3 Using HTTP Methods with the Bulk Resource Endpoint

HTTP Method	Path	Description
POST	/Bulk	Performs the bulk operations.

2.3 Resource Schema

The OHSIAMS Inbound User Provisioning Service API is a service provider implementation of the SCIM 2.0 specification. It uses the SCIM resource definition schema. Not all the SCIM schema attributes are required or supported. Below are the SCIM schema attributes supported by OHSIAMS.

2.3.1 Users

URI ® urn:scim:schemas:core:2.0:User

Table 2-4 Supported SCIM Schema Attributes for Users

SCIM Attribute	Constraint: Mutability	Constraint: Uniqueness	Constraint: Required	Description
id	Read Only	Unique on the server across tenants.	True (generated by service provider).	32-character GUID generated by OHSIAMS. Example: "id":"82be808061044f9e9cef4c8f08d53ef0"
externalId	Read Write	Unique on the server within a tenant.	False	Generated by the client. Must be unique within a tenant. OHSIAMS internally stores the externalId with tenant prefix. The combination of tenant plus externalId must not exceed 255 characters. Example: "externalId":"john.doe@customer.com"
username	Read Write	Unique on the server within a tenant.	True	The non-tenant-qualified username. OHSIAMS internally stores the username with tenant prefix. This username is used to log into OHSIAMS-protected applications. The tenancy of the user is derived from the request URL of the resource. Valid usernames are any combination of the following characters: [a-z], [A-Z], [0-9], space ( ), dash (-), and period (.). If the username is a valid email address, the at-sign (@) is permitted. The username must contain at least 4 characters. The combination of tenant plus username must not exceed 255 characters. Example: "userName": "JOHN.DOE"
name.givenName	Read Write	None	True	User's first name. Length must be between 1 and 150 characters. Example: "name":{ "familyName":"Doe", "givenName":"John" }
name.familyName	Read Write	None	True	User's last name. Length must be between 1 and 150 characters. Example: "name":{ "familyName":"Doe", "givenName":"John" }
emails [work]	Read Write	None	True	OHSIAMS supports a single value of the work type. Example: "emails":[{ "value":"john.doe@customer.com", "type":"work" }]
phoneNumbers [work]	Read Write	None	False	OHSIAMS supports a single value of the work type.Example: "phoneNumbers":[ { "value": "555-555-5555", "type":"work" }
active	Read Write	None	False	Account Status. SCIM:TRUE ® IAMS: Active, SCIM:FALSE ® IAMS: Disable If True, the IAMS account is active. If False, the IAMS account is disabled. A user status can be Disabled in OHSIAMS if: User has been disabled via a PATCH SCIM request. The user status is marked as disabled without removing any of the user's prior roles. User has been issued a DELETE SCIM request. The user status is marked as disabled after removing any of the user's existing roles. You can only specify this attribute in a PATCH request. It must be specified alone (without any other user attributes). Example: "active":true
password	Write Only	None	False	Auto-generated if a value is not specified in the POST request. A password change is not allowed in a PUT request. A PATCH request must be specified alone (without any other user attributes). Updating the password (via PATCH) also unlocks the user account if it has been locked. Must adhere to OHSIAMS password policies. Example: "password":"P@ssW0r3"
groups	Read Only	None	False	Lists the authorized business services of the current user.Example: "groups":[ { "value": "<tenant>.bizsvcrole", "display":"bizsvcrole" } ] <tenant> is the owner of the service.
meta	Read Only	None	False	Includes the user creation date, last update date, and location.Example: "meta":{ "created": "2014-05-29T18:00:35Z", "lastModified": "2014-05-29T18:00:35Z", "location": "http://hs-identity-api.oracleindustry.com /scim/v1/mypharms/User/54dc4a653ee71a34e3a783883c744", "resourceType":"User" }

2.3.2 Groups

URI ® urn:scim:schemas:core:2.0:Group

Table 2-5 Supported SCIM Schema Attributes for Groups

SCIM Attribute	Constraint: Mutability	Constraint: Uniqueness	Constraint: Required	Description
Id	Read Only	Unique on the server across tenants.	True	SCIM group ID is a tenant-qualified business service name (OIM role) in OHSIAMS. Example: "id":"<tenant>.pfst51trial"
displayName	Read Only	None	False	Non-tenant-qualified business service name. Example: "displayName":"pfst51trial"
members	Read Write	None	False	Multivalued complex type.
members.value	Read Write	None	False	SCIM ID of the user.
members.display	Read Only	None	False	Non-tenant-qualified username.
members.$ref	Read Only	None	False	Location URI of the member. Example: http://hs-identity-api.oci.com/scim/v1/<tenant>/Users/82be808061044f9e9cef4c8f08d53ef0
members.type	Read Only	None	False	Of the type User. OHSIAMS does not support nested roles in OIM.
meta	Read Only	None	False	Group creation date and the last update date. Example: "meta":{ "created": "2014-05-29T18:00:35Z", "lastModified": "2014-05-29T18:00:35Z", "resourceType":"Group" }

2.3.3 Bulk

URI ® urn:scim:schemas:core:2.0:BulkRequest/BulkResponse

Bulk requests and bulk responses share many attributes. Unless otherwise specified, each attribute below is present in both bulk requests and bulk responses.

Table 2-6 Supported SCIM Schema Attributes for Bulk

SCIM Attribute	Constraint: Uniqueness	Constraint: Required	Description
failOnErrors	None	False	An integer specifying the number of errors allowed before the operation is terminated and an error response is returned. Only the operations that are processed until the failOnErrors limit is reached are returned in the BulkResponse. The rest of the operations are ignored. Optional in a request. Not valid in a response.
Operations	None	True	Complex multivalued attribute.
Operations.method	None	True	The HTTP method of the current operation. Possible values are: POST, PUT, PATCH, or DELETE for User operations. PATCH for Group operations.
Operations.bulkId	Must be unique within a bulk request.	False	The bulkId is a surrogate resource ID, enabling clients to uniquely identify newly created resources in the response and to cross-reference new resources in and across operations within a bulk request. Required when method is POST.
Operations.path	None	True	The relative path of the resource. If the method is POST, the value must specify a resource type endpoint (for example, /Users). All other method values must specify the path to a specific resource (for example, /Users/2819c2237f76453a919d)
Operations.data	None	True for all except the DELETE method.	The resource data for the bulk POST, PUT, or PATCH resource operation as a single request.
Operations.location	None	True for response.	The resource endpoint URL. Required in a response, except in the event of a POST failure.
Operations.status	None	True for response.	A complex type that contains information about the success or failure of one operation within the bulk request. Required in a response.
Operations.status.code	None	True for response.	The HTTP response code returned for the bulk operation as a single request. Required.
Operations.status.description	None	False	A human-readable error message. Required when an error occurs.

2.4 Return Codes

In addition to returning an HTTP response code, the OHSIAMS Inbound User Provisioning Service API returns errors in the body of the response with error code and descriptions, as well as messages describing successful requests.

Table 2-7 HTTP Return Codes

HTTP Return Code	Description
200	Request processed successfully.
201	Request has been processed and a new resource has been created.
204	The server has fulfilled the request, but does not return a response (in a DELETE request).
303	See Other redirect. (If a user with similar user name or externalId exists in a DISABLED state, the location of the user is sent in the response.)
401	Unauthorized. (User is not authenticated.)
403	Forbidden. (User is not authorized for the operation.)
404	Not found.
412	Precondition failed. (One or more validations failed. Refer to the error response for remediation.)
415	Client media type unsupported. (Only application/JSON is supported for all operations.)
500	Generic server failure.
501	Requested method or operation is not implemented.