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.
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
The resources component provides the REST resource endpoints as described in the SCIM specification.
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.
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.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.
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:
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" } |
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" } |
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:
|
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. |
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.
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. |