New User Registration Web Service Operations
The New User Registration framework provides the SCC_USERREG service. The SCC_USERREG service includes the following service operations that are described in this section:
SCC_USERREG_CREATEACCT—creates a user account.
SCC_USERREG_AUTHENTICATE—authenticates a user.
SCC_USERREG_GET_USERID—retrieves the user ID.
SCC_USERREG_GET_PSWD_HINT—retrieves the password hint.
SCC_USERREG_GET_PASSWORD—resets user password.
SCC_CHECK_AUTH—authenticates a user, and checks if the user has the required security role (authorization)
Note: If a SOAP service request XSD contains the 'languageCd' parameter then the service is enabled for National Language Support (NLS). An ISO Locale value must be passed as the languageCd variable. Valid values can be found in .
The following diagram shows the SCC_USERREG web service operations and their messages. The diagram also shows the location from where an online transaction can access the SCC_USERREG web service.
Image: SCC_USERREG Web Services and Locator Example
This example illustrates the fields and controls on the SCC_USERREG Web Services and Locator Example. You can find definitions for the fields and controls later on this page.
Use this service operation to enable an online user to create a user name (user ID) and password. This service operation creates a new PeopleTools user profile.
The service operation supports the PeopleTools user management system. The service operation also supports other user management systems through the adapter architecture. To allow your PeopleSoft system to interact with another user management system through SCC_USERREG, a new adapter must be created.
When calling the Create User Account service operation, the user is required to choose a user name and password, and optionally to enter some constituent information such as first name, last name, email address, and so on. This either creates or does not create a single user account in the user management system you configure. If the user name is valid and does not already exist in the user management system, the service operation creates a user account. The new user account can be used immediately (no need for the new user to manually login). The user account is created based on an existing user ID that serves as a template (the SCC_SS_TEMPLATE user ID). This account must contain the basic role and permission security to access and use your system. This is also referred as the generic role provisioning. The service operation copies the user default information contained in this template, to create the new account. Therefore, you must set up the SCC_SS_TEMPLATE user account to allow an online transaction to use New User Registration. A second user ID that needs to be created and which also serves as a template to create user profiles is SCC_GUEST.
See Developer Reference to Deploy New User Registration, “Step 1: Initial Setup for New User Registration.”
The Create User Account service operation:
Verifies whether the required input parameters have been passed in the user registration page (user name, password, and confirm password).
Retrieves any constituent information from the input parameters, if included in the registration page, and validates the information. The constituent information is stored in the CTM constituent staging tables using the CTM transaction NEW_USER_REGISTRATION.
Calls the user management adapter to:
Verify that the requested user name does not exist in the user management system.
Verify your Password Controls setup is respected. This is defined in
Create the new user account.
Authenticate the user and signs the user into the online transaction.
Prepares the response message. The service operation either creates a new user account which the user can immediately use or returns an error. The service error will return an error in the following conditions:
User name, password or confirm password input parameters are invalid.
Constituent information provided through the input parameters is invalid.
The PeopleSoft Password Controls rules are not respected.
An account for the same user name already exists in the user management system.
Note: If you intend to use the Forgot User ID and Forgot Password utilities, you must require the user to enter an email address when they create an account. To do this, you must select the Email Address check box in the New User Registration Installation page. The email address the user provides is stored in the newly created user profile and will serve to send user ID or reset password if the user later forgets his or her user ID or password. The New User Registration sample login page and New User Registration Tester page are integrated with the Forgot User ID and Forgot Password utilities. To take advantage of this integration, make sure you select the Email Address check box in the New User Registration Installation page.
See Defining Installation Options for New User Registration.
The Create User Account service operation includes the following three messages:
Input message: SCC_UR_CREATEACCT_REQ
The following diagram shows the input parameters that the SCC_USERREG_CREATEACCT service operation receives from a calling online transaction (mostly the user registration page):
Image: SCC_UR_CREATEACCT_REQ Message Parameters
This example illustrates the fields and controls on the SCC_UR_CREATEACCT_REQ Message Parameters. You can find definitions for the fields and controls later on this page.
The following input parameters are mandatory by the registration page to pass to the service operation:
SCC_USERNAME
SCC_PASSWORD
SCC_CONFIRMPWD
CONSTITUENT
While the CONSTITUENT tag is required in the request message (as indicated in the request message schema: <xs:element maxOccurs="1" minOccurs="1" ref="CONSTITUENT"/>) the CONSTITUENT elements can be empty in the request. This is because it is possible, but optional to gather constituent information at registration time.
Constituent is an entity defined in the Entity Registry. Use the PeopleTools Schema page to access the SCC_ENTITY_CONSTITUENT message schema (). Any attributes contained in the schema can be used in the registration page.
See Setting Up Entity Registry.
The following is an example of the SCC_UR_CREATEACCT_REQ message that the SCC_USERREG_CREATEACCT service operation receives from a user registration page:
<?xml version="1.0"?>
<SCC_UR_CREATEACCT_REQ>
<SCC_USERNAME>KANGA</SCC_USERNAME>
<SCC_PASSWORD>Rooly23</SCC_PASSWORD>
<SCC_CONFIRMPWD>Rooly23</SCC_CONFIRMPWD>
<CONSTITUENT>
<!-- Constituent data shape -->
</CONSTITUENT>
</SCC_UR_CREATEACCT_REQ>
Output message: SCC_UR_CREATEACCT_RESP
The following diagram shows the output parameters that the SCC_USERREG_CREATEACCT service operation passes to the calling online transaction:
Image: SCC_UR_CREATEACCT_RESP Message Parameters
This example illustrates the fields and controls on the SCC_UR_CREATEACCT_RESP Message Parameters. You can find definitions for the fields and controls later on this page.
Constituent is an entity defined in the Entity Registry. Use the PeopleTools Schema page to access the SCC_ENTITY_CONSTITUENT schema ().
Image: Example of the SCC_UR_CREATEACCT_RESP message that the SCC_USERREG_CREATEACCT service operation responds to the calling online transaction
This example illustrates the fields and controls on the Example of the SCC_UR_CREATEACCT_RESP message that the SCC_USERREG_CREATEACCT service operation responds to the calling online transaction. You can find definitions for the fields and controls later on this page.
Fault message: SCC_FAULT_RESP
If the service operation encounters an error condition, it responds with the SCC_FAULT_RESP message.
The following diagram shows the output parameters that the SCC_FAULT_RESP service operation passes to the calling online transaction:
Image: SCC_FAULT_RESP Message Parameters
This example illustrates the fields and controls on the SCC_FAULT_RESP Message Parameters. You can find definitions for the fields and controls later on this page.
This service operation uses the delivered User Manager adapter to validate a username (user ID) and password combination with the installed user management system. The service operation is delivered with the ability to authenticate a user using the PeopleTools user management system.
A call to the SCC_USERREG_AUTHENTICATE service operation verifies whether the supplied username and password combination is correct using the configured user management system. If the username and password combination is correct, then the user is signed into the PeopleSoft system. All users accessing the SCC_USERREG_AUTHENTICATE operation have an Anonymous status until they have been successfully authenticated. Anonymous users only have minimal system access.
Use SCC_USERREG_AUTHENTICATE to allow a user to access your system through a front door, such as a login page.
The Authenticate User (SCC_USERREG_AUTHENTICATE) service operation:
Verifies whether the input parameters exist (user name and password).
Calls the user management adapter to validate the user name and password combination.
If an EMPLID is tied to the retrieved user profile, uses the EMPLID to retrieve constituent information on the authenticated person.
Prepares the response message. The service operation either signs in the user to the PeopleSoft system or returns an error. The service error will return an error in the following conditions:
Input parameters, username and password, are invalid.
User name and password combination cannot be authenticated using the user management system.
The Authenticate User service operation includes the following messages:
Input message: SCC_UR_AUTHENTICATE_REQ
The following diagram shows the input parameters that the SCC_USERREG_AUTHENTICATE service operation receives from a calling online transaction (mostly the user login page):
Image: SCC_UR_AUTHENTICATE_REQ Message Parameters
This example illustrates the fields and controls on the SCC_UR_AUTHENTICATE_REQ Message Parameters. You can find definitions for the fields and controls later on this page.
The following input parameters are mandatory for the login page to pass to the service operation:
Username
Password
The following is an example of the SCC_UR_AUTHENTICATE_REQ message that the SCC_USERREG_AUTHENTICATE service operation receives from a login page:
<?xml version="1.0"?>
<SCC_UR_AUTHENTICATE_REQ>
<SCC_USERNAME>KANGA</SCC_USERNAME>
<SCC_PASSWORD>Rooly23</SCC_PASSWORD>
</SCC_UR_AUTHENTICATE_REQ>
Output message: SCC_UR_AUTHENTICATE_RESP
The following diagram shows the output parameter that the SCC_USERREG_AUTHENTICATE service operation passes to the calling online transaction:
Image: SCC_UR_AUTHENTICATE_RESP Message Parameters
This example illustrates the fields and controls on the SCC_UR_AUTHENTICATE_RESP Message Parameters. You can find definitions for the fields and controls later on this page.
Constituent is an entity defined in the Entity Registry. Use the PeopleTools Schema page to access the SCC_ENTITY_CONSTITUENT schema ().
Image: Example of the SCC_UR_ AUTHENTICATE_RESP message that the SCC_USERREG_AUTHENTICATE service operation transmits to the calling online transaction
This example illustrates the fields and controls on the Example of the SCC_UR_ AUTHENTICATE_RESP message that the SCC_USERREG_AUTHENTICATE service operation transmits to the calling online transaction. You can find definitions for the fields and controls later on this page.
<?xml version="1.0"?> <SCC_UR_CREATEACCT_RESP> <CONSTITUENT> <!-- Constituent data shape --> </CONSTITUENT> <NUR_REGISTRATION_CONTEXT> <SCC_APPL_CONTXT_ID>SCC_NURCTXT_20120918102441</SCC_APPL_CONTXT_ID> <SCC_APPL_CONTEXT>NUR_DELEGATED_ACCESS</SCC_APPL_CONTEXT> <URL>http://yourServer.yourDomain.com/EMPLOYEE/SCC_DA_PROXY/SS_CC_DA_TERMS_CON</URL> </NUR_REGISTRATION_CONTEXT> </SCC_UR_CREATEACCT_RESP>
Fault message: SCC_FAULT_RESP
Refer to the SCC_FAULT_RESP message example in the SCC_USERREG_CREATEACCT service operation section.
This service operation retrieves a user’s ID using the Forgot User ID utility. A user must provide the email address that is associated with his or her OPRID (stored inside the user’s profile) in order to retrieve the user ID. The user ID is retrieved only if one OPRID is associated with the email address. The New User Registration framework uses the Notifications framework to generate the email message that contains the user ID.
The Retrieve User ID service operation:
Verifies whether the required input parameter (email address) has been passed to the Forgot my User ID page.
Validates whether the email address entered is associated with only one user ID (OPRID) (from the PSOPRDEFN and PSUSEREMAIL records).
Prepares the response message. The service operation either retrieves the user ID and uses the Notifications framework to send an email that contains the user ID, or returns an error. An error is returned when:
The email address is not found.
The email address is associated with multiple user IDs (OPRIDs), or to no user ID.
See Notifications Framework and New User Registration.
The Retrieve User ID service operation includes the following messages:
Input Message: SCC_USERREG_GET_USERID_REQ
The email address is a mandatory input parameter to pass to the service operation. The utility evaluates whether there is only one OPRID assigned to the email address. If so, the user ID is retrieved.
Output Message: SCC_USERREG_GET_USERID_RESP
When the user ID is retrieved, an email that contains the user ID is sent to the user as part of the response. The Notifications framework is triggered to send the email message.
If more than one user ID is assigned to an email address or no user ID is found, the user ID is not retrieved and an error message appears.
See:
This service operation retrieves the Forgot Password Hint set when a user forgets his or her password and triggers the PeopleTools Forgot Password utility. The PeopleTools Forgot Password utility requires that Forgot Password Hints should be defined. A user must provide his or her user ID in order to reset and receive a new password. When a user forgets his or her password and invokes the Forgot Password utility, the user ID that is provided is used to fetch the email address and Forgot Password hint set. The user’s response is compared with the information stored in the database.
The Retrieve Password Hint service operation:
Verifies whether the required input parameter, user ID (OPRID), has been passed in the Forgot my password page.
Evaluates whether the user ID is valid.
Prepares the response message. If the user ID is valid, the service operation retrieves the associated email address and displays the password hint set, or returns an error. An error is returned when:
The user ID is not found.
The user ID is not associated with a Forgot Password hint set.
The user ID is not associated with an email address, so an email cannot be sent.
See Using the Forgot Password Utility.
The Retrieve Password Hint service operation includes the following messages:
Input Message: SCC_USERREG_GET_PSWDHINT_REQ
The user ID (OPRID) is a mandatory parameter to pass to the service operation. The service operation evaluates whether the user ID is valid. If so, the associated email address and hint question are retrieved.
Output Message: SCC_USERREG_GET_PSWDHINT_RESP
If the user ID is valid, the associated email address and hint question are returned. If the user ID does not exist, is not associated with an email address or hint question, the service operation displays an error.
See Developer Reference to Deploy New User Registration, “Step 10: Configuring the Forgot Password Utility.”
This service operation resets a user’s password using the PeopleTools Forgot Password utility. When a user forgets his or her password and uses the Forgot Password utility, the user ID that is provided is used to fetch the associated Forgot Password hint set. The user must provide the correct response to the hint question. The response is compared with the information stored in the database, and when the information matches, a new password is generated and emailed to the user.
The Reset Password service operation:
Evaluates whether the user’s response to the hint question matches the information stored in the database.
Generates a new password if the user’s response and the information in the database match.
The Reset Password service operation includes the following messages:
Input Message: SCC_USERREG_GET_PASSWORD_REQ
The hint response is a mandatory parameter to pass to the service operation. The custom interface SCC_NUR_EMAIL_PSWD is invoked. If the hint response matches the information in the database, the password is reset and all the PeopleTools tables are updated with the new password.
Output Message: SCC_USERREG_GET_PASSWORD_RESP
A new password is generated and emailed to the user through the PeopleTools Forget Password email utility.
This service operation uses the User Manager adapter to validate a user name (user ID) and password combination against your user management system. The service operation provides an additional facility to return authorization information for an authenticated user. The service operation also authenticates a user using the PeopleTools user management system.
A call to the SCC_CHECK_AUTH service operation verifies whether the supplied user name and password combination is correct using the configured user management system. If the user name and password combination is correct, then the user is signed into the PeopleSoft system. Optionally, this service operation can return Role Based Access control (RBAC) authorization information for the authenticated user. The service caller can include optional role filter criteria in the request. The optional role filter criteria is compared against the PeopleSoft RBAC information associated with the user profile, and the matching role information is then returned to the client. This means that the user has access to the returned roles. All users accessing the SCC_CHECK_AUTH operation have an Anonymous status until they have been successfully authenticated. Anonymous users only have minimal system access.
Use SCC_CHECK_AUTH to allow a user to access your system through a front door, such as a login page, and to validate role authorization information.
The Check Authorization service operation:
Verifies whether the input parameters exist (user name and password and optional Role filters).
Calls the user management adapter to validate the user name and password combination.
Matches the roles to the user profile roles and returns only roles that are common, if the optional role filters are provided.
Prepares the response message. The service operation either signs in the user to the PeopleSoft system or returns an error. An error is returned when:
The input parameters, user name and password, are invalid.
The user name and password combination cannot be authenticated using the user management system.
The Check Authorization User service operation includes the following messages:
Input message: SCC_CHECK_AUTH_REQ
The following diagram shows the input parameters that the SCC_CHECK_AUTH service operation receives from a calling online transaction. For example, the user login page:
Image: SCC_CHECK_AUTH_REQ Message Parameters
This example illustrates the fields and controls on the SCC_CHECK_AUTH_REQ Message Parameters. You can find definitions for the fields and controls later on this page.
The following input parameters are mandatory for the login page to pass to the service operation:
User name
Password
The following is an example of the SCC_CHECK_AUTH_REQ message that the SCC_CHECK_AUTH service operation receives from a login page:
<?xml version="1.0"?> <SCC_CHECK_AUTH_REQ> <SCC_USERNAME>KANGA</SCC_USERNAME> <SCC_PASSWORD>Rooly</SCC_PASSWORD> <AUTHORIZATION> <ROLE> <ROLENAME>CS - Prospect</ROLENAME> <ROLENAME>CS - Student</ROLENAME> </ROLE> < /AUTHORIZATION> </SCC_CHECK_AUTH_REQ>
Output message: SCC_CHECK_AUTH_RESP
The following diagram shows the output parameter that the SCC_CHECK_AUTH service operation passes to the calling online transaction:
Image: SCC_CHECK_AUTH_RESP Message Parameters
This example illustrates the fields and controls on the SCC_CHECK_AUTH_RESP Message Parameters. You can find definitions for the fields and controls later on this page.
The following is an example of the SCC_CHECK_AUTH_RESP message that the SCC_CHECK_AUTH service operation transmits to the calling online transaction:
<?xml version="1.0"?> <SCC_CHECK_AUTH_RESP xmlns="http://xmlns.oracle.com/Enterprise/HCM/services"> <AUTHORIZATION> <ROLE> <ROLENAME>CS - Student</ROLENAME> </ROLE> </AUTHORIZATION> </SCC_CHECK_AUTH_RESP>
Fault message: SCC_FAULT_RESP
See Create User Account (SCC_USERREG_CREATEACCT) Service Operation, Fault message: SCC_FAULT_RESP.