New functionality has been added in the EPM Cloud 18.09 release to provide the ability to manage users and roles at an identity domain level with either EPM Automate or the REST API. In this post I am going to cover this functionality starting off with EPM Automate.
Four new commands have been added to EPM Automate and these are:
The comma separated files have to be uploaded to the cloud instance first using the “uploadfile” command before you can use the new commands, I would have preferred it if it could have been done in a single command without having to upload files but unfortunately that is not the way it has been developed.
I am quickly going to go through each command and provide an example.
Let’s start off with adding new users to the identity domain.
Before you can use the “addusers” command, you will need a file containing the new user information in the correct format.
The file can contain as many users you would to like to add, for demo purposes I am just going to be adding one user.
The file is required to be in the following format:
The format is the same as if you were importing a batch of users through Oracle Cloud My Services.
Now that I have the file ready I can upload it using EPM Automate, I have assumed the user has been logged in and a file with the same name does not already exist in the cloud instance, you can easily use the “deletefile” command first to remove it if needed.
The file will then be available in the “Inbox/Outbox Explorer”
The format to add users with EPM Automate is:
epmautomate addusers <FILE_NAME> <userPassword=PASSWORD > <resetPassword=true|false>
FILE_NAME is the name of the comma separated file containing the new user information which I just uploaded.
userPassword is a default password that is assigned to the new users. It will need to meet the minimal password requirements for identity domain passwords.
resetPassword defines whether the new users must change the password the first time they log in. I recommend this is always set to true.
An example to create the users contained in the file that was just uploaded is:
The response from issuing the command will include how many new users were processed, including the number of successful and failed user creations.
If successful, the user should then be available in the identity domain. Oracle cloud should also send out an email to the new user with their account information.
As I set the reset password parameter to true, the first time the user logs in they will be redirected to the “Identity Self Service” and require changing their password.
Now that the user has been created we can assign a new identity domain role.
The format for the EPM Automate command is:
epmautomate assignrole <FILE_NAME> <ROLE>
FILE_NAME is the name of a comma separated file containing the user login for the users that you want to assign an identity domain role to.
ROLE is one of the predefined identity domain roles which are:
I hoped I could use the same file used for creating the users as it also contains the “User Login” information, but when I tried that I received the following EPM Automate error:
EPMAT-1:Failed to assign role for users. File does not have valid header. Please provide a valid header in file.
Before being able to use the “assignrole” command the above file was uploaded using EPM Automate.
After the file has been uploaded, the “assignrole” command can be executed, in my example I am assigning the “Power User” role to the user in the “assignUsers.csv” file.
The response is the same as when adding users, as the command was successful the user has been assigned the role.
Unassigning a role is no different to assigning a role, the format for the command is:
epmautomate unassignrole <FILE_NAME> <ROLE>
I don’t feel I need to explain what the parameters are this time.
In the following example I am using the same file I uploaded for assigning roles to users, this time I am going to unassign the “Power User” role.
The EPM Automate command completed successfully and a quick check in “My Services” confirms the role has been removed.
On to the final command to delete users from the identity domain.
The format for the EPM Automate command is:
epmautomate removeusers FILE_NAME
The filename should contain all the users you want to remove, and the file format is the same as when assigning/unassigning roles.
In the following example using EPM Automate, I upload the file containing the users to remove and then remove them with the “removeusers” command.
Back in “My Services” the user has been deleted.
As the EPM Automate utility is built on top of the REST API then all the above commands will be available using REST.
So let us repeat the available functionality using a REST client. There are lots of free clients out there so pick the one you prefer. As usual I will be using the Boomerang REST client for Chrome.
First, I am going to delete the CSV file in the cloud instance containing the users and then upload a new one.
The REST URL format to delete files is:
https://<cloud_instance>/interop/rest/11.1.2.3.600/applicationsnapshots/<filename>
A DELETE method is used, so to delete the “newusers.csv” file a request would be made to the following:
If the deletion was successful a status of 0 will be returned.
If the file does not exist, a status of 8 will be returned and an error message.
Now to upload a new file containing the users to add in the identity domain. I have covered uploading files using the REST API in the past which you can read about here, so there is no need for me to go into much detail again.
The REST URL to upload files is:
https://<cloud_instance>/interop/rest/11.1.2.3.600/applicationsnapshots/<filename>/contents?q={"isLast":<true/false>,"chunkSize":<sizeinbytes,"isFirst":<true/false>}
A POST method is required, for example:
In the body of the post I added the user information for the file.
You can include as many users as you want to add.
The request header content type equals “application/octet-stream”
A response status of 0 will be returned if the file was uploaded.
If the file already exists, you would receive something like:
The file is now available in the “Inbox/Output Explorer”.
On to adding the user contained in the file using the REST API.
The URL format for managing users is:
https://<cloud_instance>/interop/rest/security/v1/users
It is a shame that the user information could not have been included the body of the request instead of having to upload a file.
The response will contain job information for adding new users. It includes a URL which can be accessed to check the job status.
A GET request can be made to keep checking the job status until it completes.
A status of 0 means the operation was successful, just like with EPM Automate details are included to inform how many new users creations were processed and how many succeeded or failed.
As the job was successful the new user has been added and is available in “My Services”
We can now move on to assigning a role for the new user.
I uploaded the following file:
In my example the file only contains a single user but it can contain as many as you want to assign a role to.
To assign a role to the users contained in a file the same URL format is required as when adding users.
A PUT method is required, and the body of the request should include the filename, the role name and a job type of “ASSIGN_ROLE”
This time I am going to assign the “User” identity domain role.
The current job status for assigning the role is returned, once again it includes a URL to check the job status.
The job status can then be checked until it completes.
As the operation was successful, the “User” role has been assigned to the user contained in the file.
To unassign roles is very similar to assigning. A PUT method is required, and the body of the request should contain the filename containing the users that the role should be unassigned from, the role name and a job type of “UNASSIGN_ROLE”
The current job status is returned in the response.
The job status can be checked until it completes.
As the job was successful the “User” role has been removed for the user contained in the specified file.
To remove users, a file should be uploaded containing the user login details of the users to remove.
I uploaded the following file.
A DELETE method is required, and the URL should include the filename containing the users to remove.
No surprise that job status information is returned in the response.
The job status can be checked until it completes.
The response confirms the user was removed. A look in “My Services” confirms the user has been removed.
I was going to include an example using scripting, but I think you should get the idea. I have covered scripting with the REST API many times in the past so just have a look at my previous posts if you are unclear.
Update - New functionality to manage users was added in the 18.11 release, you can read about in here.
Four new commands have been added to EPM Automate and these are:
- addusers – Creates new users in the identity domain based on the contents of a comma separated file.
- removeusers – Deletes identity domain accounts based on the contents of a comma separated file.
- assignrole – Assigns an identity domain role to all users that are contained in a comma separated file.
- unassignrole – Unassigns an identity domain role to all users that are contained in a comma separated file.
The comma separated files have to be uploaded to the cloud instance first using the “uploadfile” command before you can use the new commands, I would have preferred it if it could have been done in a single command without having to upload files but unfortunately that is not the way it has been developed.
I am quickly going to go through each command and provide an example.
Let’s start off with adding new users to the identity domain.
Before you can use the “addusers” command, you will need a file containing the new user information in the correct format.
The file can contain as many users you would to like to add, for demo purposes I am just going to be adding one user.
The file is required to be in the following format:
The format is the same as if you were importing a batch of users through Oracle Cloud My Services.
Now that I have the file ready I can upload it using EPM Automate, I have assumed the user has been logged in and a file with the same name does not already exist in the cloud instance, you can easily use the “deletefile” command first to remove it if needed.
The file will then be available in the “Inbox/Outbox Explorer”
The format to add users with EPM Automate is:
epmautomate addusers <FILE_NAME> <userPassword=PASSWORD > <resetPassword=true|false>
FILE_NAME is the name of the comma separated file containing the new user information which I just uploaded.
userPassword is a default password that is assigned to the new users. It will need to meet the minimal password requirements for identity domain passwords.
resetPassword defines whether the new users must change the password the first time they log in. I recommend this is always set to true.
An example to create the users contained in the file that was just uploaded is:
The response from issuing the command will include how many new users were processed, including the number of successful and failed user creations.
If successful, the user should then be available in the identity domain. Oracle cloud should also send out an email to the new user with their account information.
As I set the reset password parameter to true, the first time the user logs in they will be redirected to the “Identity Self Service” and require changing their password.
Now that the user has been created we can assign a new identity domain role.
The format for the EPM Automate command is:
epmautomate assignrole <FILE_NAME> <ROLE>
FILE_NAME is the name of a comma separated file containing the user login for the users that you want to assign an identity domain role to.
ROLE is one of the predefined identity domain roles which are:
- Service Administrator
- Power User
- User
- Viewer
I hoped I could use the same file used for creating the users as it also contains the “User Login” information, but when I tried that I received the following EPM Automate error:
EPMAT-1:Failed to assign role for users. File does not have valid header. Please provide a valid header in file.
Before being able to use the “assignrole” command the above file was uploaded using EPM Automate.
After the file has been uploaded, the “assignrole” command can be executed, in my example I am assigning the “Power User” role to the user in the “assignUsers.csv” file.
The response is the same as when adding users, as the command was successful the user has been assigned the role.
Unassigning a role is no different to assigning a role, the format for the command is:
epmautomate unassignrole <FILE_NAME> <ROLE>
I don’t feel I need to explain what the parameters are this time.
In the following example I am using the same file I uploaded for assigning roles to users, this time I am going to unassign the “Power User” role.
The EPM Automate command completed successfully and a quick check in “My Services” confirms the role has been removed.
On to the final command to delete users from the identity domain.
The format for the EPM Automate command is:
epmautomate removeusers FILE_NAME
The filename should contain all the users you want to remove, and the file format is the same as when assigning/unassigning roles.
In the following example using EPM Automate, I upload the file containing the users to remove and then remove them with the “removeusers” command.
Back in “My Services” the user has been deleted.
As the EPM Automate utility is built on top of the REST API then all the above commands will be available using REST.
So let us repeat the available functionality using a REST client. There are lots of free clients out there so pick the one you prefer. As usual I will be using the Boomerang REST client for Chrome.
First, I am going to delete the CSV file in the cloud instance containing the users and then upload a new one.
The REST URL format to delete files is:
https://<cloud_instance>/interop/rest/11.1.2.3.600/applicationsnapshots/<filename>
A DELETE method is used, so to delete the “newusers.csv” file a request would be made to the following:
If the deletion was successful a status of 0 will be returned.
If the file does not exist, a status of 8 will be returned and an error message.
Now to upload a new file containing the users to add in the identity domain. I have covered uploading files using the REST API in the past which you can read about here, so there is no need for me to go into much detail again.
The REST URL to upload files is:
https://<cloud_instance>/interop/rest/11.1.2.3.600/applicationsnapshots/<filename>/contents?q={"isLast":<true/false>,"chunkSize":<sizeinbytes,"isFirst":<true/false>}
A POST method is required, for example:
In the body of the post I added the user information for the file.
You can include as many users as you want to add.
The request header content type equals “application/octet-stream”
A response status of 0 will be returned if the file was uploaded.
If the file already exists, you would receive something like:
The file is now available in the “Inbox/Output Explorer”.
On to adding the user contained in the file using the REST API.
The URL format for managing users is:
https://<cloud_instance>/interop/rest/security/v1/users
A POST method is required, and the body of the request should contain the filename and the default and reset password values. These are the same parameters which are used with EPM Automate commands.
It is a shame that the user information could not have been included the body of the request instead of having to upload a file.
The response will contain job information for adding new users. It includes a URL which can be accessed to check the job status.
A GET request can be made to keep checking the job status until it completes.
A status of 0 means the operation was successful, just like with EPM Automate details are included to inform how many new users creations were processed and how many succeeded or failed.
As the job was successful the new user has been added and is available in “My Services”
We can now move on to assigning a role for the new user.
I uploaded the following file:
In my example the file only contains a single user but it can contain as many as you want to assign a role to.
To assign a role to the users contained in a file the same URL format is required as when adding users.
A PUT method is required, and the body of the request should include the filename, the role name and a job type of “ASSIGN_ROLE”
This time I am going to assign the “User” identity domain role.
The current job status for assigning the role is returned, once again it includes a URL to check the job status.
The job status can then be checked until it completes.
As the operation was successful, the “User” role has been assigned to the user contained in the file.
To unassign roles is very similar to assigning. A PUT method is required, and the body of the request should contain the filename containing the users that the role should be unassigned from, the role name and a job type of “UNASSIGN_ROLE”
The current job status is returned in the response.
The job status can be checked until it completes.
As the job was successful the “User” role has been removed for the user contained in the specified file.
To remove users, a file should be uploaded containing the user login details of the users to remove.
I uploaded the following file.
A DELETE method is required, and the URL should include the filename containing the users to remove.
No surprise that job status information is returned in the response.
The job status can be checked until it completes.
The response confirms the user was removed. A look in “My Services” confirms the user has been removed.
I was going to include an example using scripting, but I think you should get the idea. I have covered scripting with the REST API many times in the past so just have a look at my previous posts if you are unclear.
Update - New functionality to manage users was added in the 18.11 release, you can read about in here.
John - Excellent Post.
ReplyDeleteCould you also please provide how to assign group(s) to the users through REST client? that would be really helpful.
Vijay
Hi John,
ReplyDeleteLike Sammy asked, Can we assign users to groups using REST API in Cloud?
Thanks
Senthil
Yes, have a read of http://john-goodwin.blogspot.com/2018/11/epm-cloud-managing-users-with-epm.html
ReplyDelete