Add Users to an Identity Domain

Creates a batch of users in an identity domain using an ANSI or UTF-8 encoded Comma Separated Value (CSV) file that was previously uploaded to the environment. The CSV file should not include the account of the user who executes this command. You can use the Upload REST API to upload the file. The file should be deleted after the API executes. The file format is as follows:

First Name,Last Name,Email,User Login
Jane,Doe,jane.doe@example.com,jdoe
John,Doe,john.doe@example.com,john.doe@example.com

See Importing a Batch of User Accounts in Getting Started with Oracle Cloud for a detailed description of the CSV file format.

If a user definition in the CSV file matches a user accounts that exists in the identity domain, no changes will be made to the existing user account. This API creates accounts only for new users whose account information is included in the file. Because user accounts are common to all service environments that an identity domain supports, new users are available to all the environments that share the identity domain.

This API should be run only by an Identity Domain Administrator in the identity domain where users are to be created. After the user accounts are created, Oracle Cloud sends each new user an email with details about their accounts.

The API is asynchronous and returns the Job ID. The presence of status -1 in the response indicates that the creation of users is in progress. Use the job status URI to determine whether the creation of users is complete. Any non-zero status except -1 indicates failure of adding users.

This REST API is version v1.

Table 8-2 Tasks for Add Users

Task Request REST Resource
Add users POST /interop/rest/security/users
Add users status GET /interop/rest/security/<api_version/jobs/<jobid>

REST Resource

POST /interop/rest/security/<api_version>/users

Supported Media Types: application/json

Parameters:

The following table summarizes the POST request parameters.

Table 8-3 Parameters

Name Description Type Required Default
filename

The name of the uploaded ANSI or UTF-8 encoded CSV file containing the users to add, such as addUsers.csv.

Form Yes None
userpassword The default password that you want to assign to new users who are created in the identity domain. The password must meet the minimum identity domain password requirements. Form Yes None
resetpassword Whether new users must change password at the first log in, true or false. Unless this optional parameter is set to false, new users will be forced to change the password at the first sign in. Form No true

Response

Supported Media Types: application/json

Parameters:

Table 8-4 Parameters

Name Description
details In the case of errors, details are published with the error string
status See Migration Status Codes
links Detailed information about the link
href Links to API call or status API
action The HTTP call type
rel Possible values: self or Job Status. If the value is set to Job Status, you can use the href to get the status of the recreate service
data Parameters as key value pairs passed in the request
items Details about the resource
links Details of the first URL to be requested to get the job details; rel is "Job Details"

Note: This API does not trigger automatic email notifications containing credentials (login name and password) to newly added users.

  • If SSO with an identity provider is not enabled for your environment: Always specify a value for userpassword. Email credentials (login name and password) to new users. Additionally, force users to reset the default password after their initial login by setting resetpassword to true
  • If SSO with an identity provider is enabled for your environment: If userpassword is not specified, newly added users can log in only by using their SSO credentials (using the Company Sign In option in the Welcome screen), even if the Enable Sign In to Oracle Cloud Services with Identity Domain Credentials setting was selected while setting up SSO in My Services. To enable users also to sign in using their identity domain credentials, specify a value for userpassword. Email credentials (login name and password) to newly added users. Additionally, force users to reset the default password after their initial login by setting resetpassword to true.

Examples of Response Body in JSON format.

Example 1, when job is in progress

{
  "links": [
    {
      "rel": "self",
      "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/users",
      "data": {
        "jobType": "ADD_USERS",
        "filename": "<filename>",
        "resetpassword": "<true|false>"      },
      "action": "POST"
    },
    {
      "rel": "Job Status",
      "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/users",
      "data": null,
      "action": "GET"
    }
  ],
  "details": null,
  "status": -1,
  "items": null
}

Example 2, when job completes with errors:

{
  "links": [
    {
      "rel": "self",
      "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/jobs/",
      "data": null,
      "action": "GET"
    }
  ],
  "details": "Failed to add users. File <fileName> is not found. Please provide a valid file name.",
  "status": 1,
  "items": null
}

Example 3, when job completes without errors:

{
  "links": [
    {
      "rel": "self",
      "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/jobs/",
      "data": null,
      "action": "GET"
    }
  ],
  "details": "Processed - 3, Succeeded - 2, Failed - 1.",
  "status": 0,
  "items": null
}

Java Sample Code

Prerequisites: json.jar

Common Functions: See CSS Common Helper Functions for Java

public void addUsers(String fileName, String userPassword, boolean resetPassword) {
		try {
			String url = this.serverUrl + "/interop/rest/security/" + apiVersion + "/users";
			Map<String, String> reqHeaders = new HashMap<String, String>();
			reqHeaders.put("Authorization", "Basic " + DatatypeConverter
					.printBase64Binary((this.userName + ":" + this.password).getBytes(Charset.defaultCharset())));

			Map<String, String> reqParams = new HashMap<String, String>();
			reqParams.put("filename", fileName);
			reqParams.put("userpassword", userPassword);
			reqParams.put("resetpassword", resetPassword + "");

			Map<String, String> resetResult = CSSRESTHelper.callRestApi(new HashMap(), url, reqHeaders, reqParams,
					"POST");
			String jobStatus = CSSRESTHelper.getCSSRESTJobCompletionStatus(restResult, reqHeaders);
			System.out.println(jobStatus);
		} catch (Exception e) {
			e.printStackTrace();
		}
	}

Shell Script Sample Code

Prerequisites: jq (http://stedolan.github.io/jq/download/linux64/jq)

Common Functions: See CSS Common Helper Functions for cURL

funcAddUsers() {
	url="$SERVER_URL/interop/rest/security/$API_VERSION/users"
	params="filename=$1&userpassword=$2&resetpassword=$3"
	header="Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
	cssRESTAPI="AddUsers"
	statusMessage=$(funcCSSRESTHelper "POST" "$url" "$header" "$USERNAME" "$PASSWORD" "$params" "$cssRESTAPI")
	echo $statusMessage
}

Groovy Sample Code

Common Functions: See CSS Common Helper Functions for Groovy

def addUsers(fileName, resetPassword, userPassword) {

	String scenario = "Creating users in " + fileName;
	String params = "jobtype=ADD_USERS&filename="+ fileName +"&resetpassword="+ resetPassword +"&userpassword="+ userPassword;
	def url = null;
	def response = null;
	try {
		url = new URL(serverUrl + "/interop/rest/security/" + apiVersion + "/users");
	} catch (MalformedURLException e) {
		println "Please enter a valid URL"
		System.exit(0);
	}
	response = executeRequest(url, "POST", params, "application/x-www-form-urlencoded");
	if (response != null) {
		getJobStatus(getUrlFromResponse(scenario, response, "Job Status"), "GET");
	}
}