Skip to main content

users

Creates, updates, deletes, gets or lists a users resource.

Overview​

Nameusers
TypeResource
Idoci.identity.users

Fields​

The following fields are returned by SELECT queries:

The user was retrieved.

NameDatatypeDescription
idstringThe OCID of the user.
namestringThe name you assign to the user during creation. This is the user's login for the Console. The name must be unique across all users in the tenancy and cannot be changed.
capabilitiesobjectProperties indicating how the user is allowed to authenticate.
compartmentIdstringThe OCID of the tenancy containing the user.
dbUserNamestringDB username of the DB credential. Has to be unique across the tenancy.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
descriptionstringThe description you assign to the user. Does not have to be unique, and it's changeable. (For tenancies that support identity domains) You can have an empty description.
emailstringThe email address you assign to the user. The email address must be unique across all users in the tenancy. (For tenancies that support identity domains) The email address is required unless the requirement is disabled at the tenancy level.
emailVerifiedbooleanWhether the email address has been validated.
externalIdentifierstringIdentifier of the user in the identity provider
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
identityProviderIdstringThe OCID of the IdentityProvider this user belongs to.
inactiveStatusinteger (int64)Returned only if the user's lifecycleState is INACTIVE. A 16-bit value showing the reason why the user is inactive: - bit 0: SUSPENDED (reserved for future use) - bit 1: DISABLED (reserved for future use) - bit 2: BLOCKED (the user has exceeded the maximum number of failed login attempts for the Console)
isMfaActivatedbooleanFlag indicates if MFA has been activated for the user.
lastSuccessfulLoginTimestring (date-time)The date and time of when the user most recently logged in the format defined by RFC3339 (ex. 2016-08-25T21:10:29.600Z). If there is no login history, this field is null. For illustrative purposes, suppose we have a user who has logged in at July 1st, 2020 at 1200 PST and logged out 30 minutes later. They then login again on July 2nd, 2020 at 1500 PST. Their previousSuccessfulLoginTime would be 2020-07-01:19:00.000Z. Their lastSuccessfulLoginTime would be 2020-07-02:22:00.000Z.
lifecycleStatestringThe user's current state. After creating a user, make sure its lifecycleState changes from CREATING to ACTIVE before using it. (CREATING, ACTIVE, INACTIVE, DELETING, DELETED)
previousSuccessfulLoginTimestring (date-time)The date and time of when the user most recently logged in the format defined by RFC3339 (ex. 2016-08-25T21:10:29.600Z). If there is no login history, this field is null. For illustrative purposes, suppose we have a user who has logged in at July 1st, 2020 at 1200 PST and logged out 30 minutes later. They then login again on July 2nd, 2020 at 1500 PST. Their previousSuccessfulLoginTime would be 2020-07-01:19:00.000Z. Their lastSuccessfulLoginTime would be 2020-07-02:22:00.000Z.
timeCreatedstring (date-time)Date and time the user was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectuserId, regionGets the specified user's information.
listselectcompartmentId, regionpage, limit, identityProviderId, externalIdentifier, name, sortBy, sortOrder, lifecycleStateLists the users in your tenancy. You must specify your tenancy's OCID as the value for the<br />compartment ID (remember that the tenancy is simply the root compartment).<br />See [Where to Get the Tenancy's OCID and User's OCID](/Content/API/Concepts/apisigningkey.htm#five).<br />
createinsertregion, name, compartmentId, descriptionopc-retry-tokenCreates a new user in your tenancy. For conceptual information about users, your tenancy, and other<br />IAM Service components, see [Overview of IAM](/Content/Identity/getstarted/identity-domains.htm).<br /><br />You must specify your tenancy's OCID as the compartment ID in the request object (remember that the<br />tenancy is simply the root compartment). Notice that IAM resources (users, groups, compartments, and<br />some policies) reside within the tenancy itself, unlike cloud resources such as compute instances,<br />which typically reside within compartments inside the tenancy. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the user, which must be unique across all users in your tenancy<br />and cannot be changed. Allowed characters: No spaces. Only letters, numerals, hyphens, periods,<br />underscores, +, and @. If you specify a name that's already in use, you'll get a 409 error.<br />This name will be the user's login to the Console. You might want to pick a<br />name that your company's own identity system (e.g., Active Directory, LDAP, etc.) already uses.<br />If you delete a user and then create a new user with the same name, they'll be considered different<br />users because they have different OCIDs.<br /><br />You must also specify a description for the user (although it can be an empty string).<br />It does not have to be unique, and you can change it anytime with<br />[UpdateUser](#/en/identity/20160918/User/UpdateUser). You can use the field to provide the user's<br />full name, a description, a nickname, or other information to generally identify the user.<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before<br />using the object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />A new user has no permissions until you place the user in one or more groups (see<br />[AddUserToGroup](#/en/identity/20160918/UserGroupMembership/AddUserToGroup)). If the user needs to<br />access the Console, you need to provide the user a password (see<br />[CreateOrResetUIPassword](#/en/identity/20160918/UIPassword/CreateOrResetUIPassword)).<br />If the user needs to access the Oracle Cloud Infrastructure REST API, you need to upload a<br />public API signing key for that user (see<br />[Required Keys and OCIDs](/Content/API/Concepts/apisigningkey.htm) and also<br />[UploadApiKey](#/en/identity/20160918/ApiKey/UploadApiKey)).<br /><br />Important: Make sure to inform the new user which compartment(s) they have access to.<br />
updateupdateuserId, regionif-matchUpdates the description of the specified user.
deletedeleteuserId, regionif-matchDeletes the specified user. The user must not be in any groups.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment (remember that the tenancy is simply the root compartment).
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
userIdstringThe OCID of the user.
externalIdentifierstringThe id of a user in the identity provider.
identityProviderIdstringThe id of the identity provider.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return in a paginated "List" call.
namestringA filter to only return resources that match the given name exactly.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.
sortBystringThe field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for NAME is ascending. The NAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by Availability Domain if the scope of the resource type is within a single Availability Domain. If you call one of these "List" operations without specifying an Availability Domain, the resources are grouped by Availability Domain, then sorted.
sortOrderstringThe sort order to use, either ascending (ASC) or descending (DESC). The NAME sort order is case sensitive.

SELECT examples​

Gets the specified user's information.

SELECT
id,
name,
capabilities,
compartmentId,
dbUserName,
definedTags,
description,
email,
emailVerified,
externalIdentifier,
freeformTags,
identityProviderId,
inactiveStatus,
isMfaActivated,
lastSuccessfulLoginTime,
lifecycleState,
previousSuccessfulLoginTime,
timeCreated
FROM oci.identity.users
WHERE userId = '{{ userId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new user in your tenancy. For conceptual information about users, your tenancy, and other<br />IAM Service components, see [Overview of IAM](/Content/Identity/getstarted/identity-domains.htm).<br /><br />You must specify your tenancy's OCID as the compartment ID in the request object (remember that the<br />tenancy is simply the root compartment). Notice that IAM resources (users, groups, compartments, and<br />some policies) reside within the tenancy itself, unlike cloud resources such as compute instances,<br />which typically reside within compartments inside the tenancy. For information about OCIDs, see<br />[Resource Identifiers](/Content/General/Concepts/identifiers.htm).<br /><br />You must also specify a name for the user, which must be unique across all users in your tenancy<br />and cannot be changed. Allowed characters: No spaces. Only letters, numerals, hyphens, periods,<br />underscores, +, and @. If you specify a name that's already in use, you'll get a 409 error.<br />This name will be the user's login to the Console. You might want to pick a<br />name that your company's own identity system (e.g., Active Directory, LDAP, etc.) already uses.<br />If you delete a user and then create a new user with the same name, they'll be considered different<br />users because they have different OCIDs.<br /><br />You must also specify a description for the user (although it can be an empty string).<br />It does not have to be unique, and you can change it anytime with<br />[UpdateUser](#/en/identity/20160918/User/UpdateUser). You can use the field to provide the user's<br />full name, a description, a nickname, or other information to generally identify the user.<br /><br />After you send your request, the new object's lifecycleState will temporarily be CREATING. Before<br />using the object, first make sure its lifecycleState has changed to ACTIVE.<br /><br />A new user has no permissions until you place the user in one or more groups (see<br />[AddUserToGroup](#/en/identity/20160918/UserGroupMembership/AddUserToGroup)). If the user needs to<br />access the Console, you need to provide the user a password (see<br />[CreateOrResetUIPassword](#/en/identity/20160918/UIPassword/CreateOrResetUIPassword)).<br />If the user needs to access the Oracle Cloud Infrastructure REST API, you need to upload a<br />public API signing key for that user (see<br />[Required Keys and OCIDs](/Content/API/Concepts/apisigningkey.htm) and also<br />[UploadApiKey](#/en/identity/20160918/ApiKey/UploadApiKey)).<br /><br />Important: Make sure to inform the new user which compartment(s) they have access to.<br />

INSERT INTO oci.identity.users (
compartmentId,
definedTags,
description,
email,
freeformTags,
name,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ email }}',
'{{ freeformTags }}',
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
capabilities,
compartmentId,
dbUserName,
definedTags,
description,
email,
emailVerified,
externalIdentifier,
freeformTags,
identityProviderId,
inactiveStatus,
isMfaActivated,
lastSuccessfulLoginTime,
lifecycleState,
previousSuccessfulLoginTime,
timeCreated
;

UPDATE examples​

Updates the description of the specified user.

UPDATE oci.identity.users
SET 
dbUserName = '{{ dbUserName }}',
definedTags = '{{ definedTags }}',
description = '{{ description }}',
email = '{{ email }}',
freeformTags = '{{ freeformTags }}'
WHERE 
userId = '{{ userId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
name,
capabilities,
compartmentId,
dbUserName,
definedTags,
description,
email,
emailVerified,
externalIdentifier,
freeformTags,
identityProviderId,
inactiveStatus,
isMfaActivated,
lastSuccessfulLoginTime,
lifecycleState,
previousSuccessfulLoginTime,
timeCreated;

DELETE examples​

Deletes the specified user. The user must not be in any groups.

DELETE FROM oci.identity.users
WHERE userId = '{{ userId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;