Novell Doc: Identity Manager Roles Based Provisioning Module 3.7 User Application: Administration Guide - Accessing and Using the Password Management and SSO Services

27.2 Accessing and Using the Password Management and SSO Services

The Password Management Service exposes resources to perform various password management functions. The SSO Service retrieves all SSO information related to a particular user.

NOTE:To test the REST service from remote client application, e.g. JAVA Swing, the client needs to pass a Base64 encoded user/password in the RESTAuthorization HTTP header. For example:

HttpURLConnection passwordURL = (HttpURLConnection) new URL(password).openConnection(); 
passwordURL.setRequestMethod("GET"); 
passwordURL.setDoOutput(true); 
passwordURL.setReadTimeout(20000); 
passwordURL.setRequestProperty("RESTAuthorization", new String(Base64.encodeBase64("username:password".getBytes("UTF-8")), "UTF-8")); 
passwordURL.connect();

27.2.1 Available Resources

There are several types of resources available for the Password Management and SSO Services:

Password Challenge Response
Password Hint Change
Change Password
Password Policy Status
Password Sync Status
Locale Change
SSO

27.2.2 Complete URI Syntax

The following table shows the complete URI syntax for all resource end points associated with the Password Management and SSO Services, along with a description for each URI and a list of supported HTTP methods:

Table 27-1 Resource URIs

URI	Description
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/chares	Password challenge response endpoint. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/chares Supported HTTP methods: GET: Get all challenge response information related to the user DN specified in the URI in JSON format. - Authentication needed. POST: Post user answered challenge response answers to the server and save.
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/hint	Password hint change endpoint. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/hint GET: Get all hint information related to the user DN specified in the URI in JSON format - Authentication needed. POST: Post user entered hint to the server and save.
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/password	Change password endpoint. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/password Supported HTTP methods: GET: Get all password information related to the user DN specified in the URI in JSON format - Authentication needed. POST: Post user entered new password to the server and save.
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/policy	Password policy status endpoint. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/policy Supported HTTP methods: GET: Get all password policy information related to the user DN specified in the URI in JSON format - Authentication needed.
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/sync	Password synchronization status endpoint. Here is a sample URL; http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/sync Supported HTTP methods: GET: Get all password synchronization status information related to the user DN specified in the URI in JSON format - Authentication needed.
http(s)://host:port/war_context/roa/v1/pwdmgt/user/{userDN}/locale	Locale change endpoint. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/pwdmgt/user/cn=restuser,ou=Password,ou=medical-idmsample,o=novell/locale Supported HTTP methods: GET: Get all locale information related to the user DN specified in the URI in JSON format - Authentication needed. POST: Post user entered new locale to the server and save.
http(s)://host:port/war_context/roa/v1/sso/user/{userDN}/sso	Single-sign on end point. Here is a sample URL: http://localhost:9000/IDMProv/roa/v1/sso/user/cn=admin,ou=medical-idmsample,o=novell/sso Supported HTTP methods: GET: Get all SSO information related to the user DN specified in the URI in JSON format - Authentication needed. POST: Post user entered SSO information to the server and save.

27.2.3 JSON Representations Received by the Client

This section provides details about the JSON representations returned by the client.

Password Challenge Response

Here is some sample return data:

[{"error_message":""},{"have_stored_challenges":"true","use_mask":"false"},{"0":"What is your mother's maiden name?"},{"1":"color1"},{"use_grace_login":"true","grace_login_remaining":"3"}]

Each element is described below:

error_message: Any errors occurred during retrieving challenges data.
have_stored_challenges: Indicates if the user has a stored challenge question.
use_mask: Indicates if user's challenge answers should be marked when user enters challenge answers, this is configured through User Application password administration screen.
{"0":"What is your mother's maiden name?"},{"1":"color1"}: Challenge questions starting from index 0. First group is administrator defined questions, second group is user defined questions.
use_grace_login Indicates whether the user is in grace login.
grace_login_remaining: Number of grace logins remaining.

Here is some sample POST data:

Table 27-2 Sample POST data

Field Name	Field Value
_answer0 maiden
_answer1 redred
_from_seq0	1
_from_seq1	2
_question0	What is your mother’s maiden name?
_question1	color1

NOTE:_question0 _question1, _answer0, _answer1 are the challenge questions and answers sequence. _from_seq0 and _from_seq1 are corresponding to challenge questions and answers pair 0 and 1, this is because when form validation is kicked in, if validation failed, the error message sent back will refer to form fields starting from 1, instead of 0.

Here is some sample return data from the POST:

[{"success_message":"Challenge responses were saved successfully"}]

Each element is described below:

success_message: Success message indicating that the save operation succeeded.
error_message: Error message indicating that the save operation failed.

Password Hint Change

Here is some sample return data:

[{"hint":"new hint message","hint_in_use":"Hint is not in use","hint_invalid":"Hint is invalid","message":"Any other error message"},{"use_grace_login":"true","grace_login_remaining":"3"}]

Each element is described below:

hint: Password hint.
hint_in_use: If this field exists in the returned JSON message, then it indicates the password hint is not in use with this user.
hint_invalid:If this field exists in the returned JSON message, then it indicates the password hint is invalid.
message: If this field exists in the returned JSON message, then it indicates some error occurred.
use_grace_login: Indicates whether the user is in grace login.
grace_login_remaining: Number of grace logins remaining.

Here is some sample POST data:

Table 27-3 Sample POST Data

Field Name	Field Value
hint	REST user name

Here is some sample return data from the POST:

[{"success_message":"Success"}]

Each element is described above:

success_message: Indicates that the hint save operation was successful.
error_message: Indicates that the hint save operation failed.

Change Password

Here is some sample return data:

[{"hintInUse":"true","hint":"rest user name","showSyncStatus":"false","rules":"<tr><td class=\"nv-fontSmall \">Your password must have the following properties:<\/td><\/tr><tr><td class=\"nv-fontSmall  nv-fontBold \"><\/td><\/tr><tr><td><ul><li class=\"nv-fontSmall\">Minimum number of characters in password: 4<\/li><li class=\"nv-fontSmall\">Maximum number of characters in password: 12<\/li><\/ul><\/td><\/tr><tr><td class=\"nv-fontSmall\">You may use numbers in your password.<\/td><\/tr><tr><td class=\"nv-fontSmall nv-fontBold\"><\/td><\/tr><tr><td><ul><\/ul><\/td><\/tr><tr><td class=\"nv-fontSmall\">The password is case sensitive.<\/td><\/tr><tr><td class=\"nv-fontSmall  nv-fontBold\"><\/td><\/tr><tr><td><ul><\/ul><\/td><\/tr><tr><td class=\"nv-fontSmall\">You may use special characters in your password.<\/td><\/tr><tr><td class=\"nv-fontSmall  nv-fontBold\"><\/td><\/tr><tr><td><ul><\/ul><\/td><\/tr>"},{"error_message","Error has occurred"},{"use_grace_login":"true","grace_login_remaining":"5"}]

Each element is described below:

hint_in_use: Indicates whether password hint is in use with this user.
hint: User's password hint.
ShowSyncStatus: If to show password sync status screen after user changes password.
rules: User's password rules.
error_message: Error message if error has occurred.
use_grace_login: Indicates whether the user is in grace login.
grace_login_remaining: Number of grace logins remaining.

Here is some sample POST data:

Table 27-4 Sample POST Data

Field Name	Field Value
oldPassword	test
newPassword	novell
retypeNewPassword	novell

Here is some sample return data from the POST:

[{"pwdChgRtnPage":"","accessMgr":"false","pwd_chg_rtn_page":"Password Change Return Page","success_message":"Your password has been changed successfully."}]

Each element is described above:

pwdChgRtnPage: Password change return page link - this is used when access manager is used when accessing REST service, so user knows where he can go after changing password.
accessMgr: Indicates whether REST service is accessed through access manager.
pwd_chg_rtn_page: This is just a localized label for pwdChgRtnPage link.
success_message: Indicates that the password change is successful.
error_message: Indicates that the password change failed.

Password Policy Status

Here is some sample return data:

[{"challengeresponse_status":"Valid","hint_status":"Invalid","password_status":"Valid"},{"error":"error occurred”},{"use_grace_login":"true","grace_login_remaining":"3"}]

Each element is described below:

challengeresponse_status: Indicates if challenge response status is valid.
hint_status: Indicates if hint status is valid.
password_status: Indicates if password change is needed. If password change is needed, then this field will return “Invalid”, else return “Valid”.
error: If exists, then error occurred.
use_grace_login: Indicates whether the user is in grace login.
grace_login_remaining: Number of grace logins remaining.

Password Synchronization Status

Here is some sample return data:

[{"0004":"Success","check_timeout":"3000","unchecked":"Unchecked","buffer_time":"0","0001":"Warning" ,"0000":"Error","0003":"Fatal","0002":"Retry","image_servlet":"passwordSyncAppImage","error_occurred":"Error occurred, please contact administrator.","error_complete":"Application synchronization status check completed with errors. Contact your administrator for more details.","supervisor":"false","check_exceeded":"Check count exceeded.","timeout_message":"Application synchronization status check timeout.","success_complete":"Application synchronization status check completed successfully.","images_per_row":"4","processing":"Processing......","no_app_configured":"There are no applications configured for Password Synchronization at this time.","process_count":"3","timeout":"300000","invalid-hash":"Hash Not Match"},{"D37BBE8D658A344C4AADD37BBE8D658A":"App2"},{"error_message":""},{"use_grace_login":"true","grace_login_remaining":"2"}]

Each element is described below:

Group 1: Returns a list of localized status message for displaying password sync status.
Group 2: Returns a list of Configured Applications to check for password sync status. For each configured application, will return "App's GUID" and "App's Name" which is configured by User Application administrator.
Group 3:
- error_message: If an error occurs, this field shows the message.
Group 4:
- use_grace_login: Indicates whether the user is in grace login.
- grace_login_remaining: Number of grace logins remaining.

Here is some sample POST data:

Table 27-5 Sample POST Data

Field Name	Field Value
guid	Application GUID
userDN	If checking user using Administrator credentials, then pass userDN, if user is self checking password sync status, then pass blank value.

Here is some sample return data from the POST:

[{"status":"0002"},{"error_message":"Error occurred"}]

Each element is described above:

Group 1: Returns user's password sync status on this application indicated by GUID.
Group 2: If an error occurs, the error_message field shows the message.

Locale Change

Here is some sample return data:

[{"en":"English"},{"NOT_AN_OPTION":"Select a locale to add...","zh-CN":"Chinese (China)","zh-TW":"Chinese (Taiwan)","nl":"Dutch","fr":"French","de":"German","it":"Italian","ja":"Japanese","pt":"Portuguese","ru":"Russian","es":"Spanish","sv":"Swedish"},{"message":""},{"display_name":"FirstName LastName","use_grace_login":"true","grace_login_remaining":"5"}]

Each element is described below:

Group 1: Returns a list of the user's configured locales.
Group 2: Returns a list of available locales.
Group 3: Any error messages are returned here.
Group 4:
- use_grace_login: Indicates whether the user is in grace login.
- grace_login_remaining: Number of grace logins remaining.

Here is some sample POST data:

Table 27-6 Sample POST Data

Field Name	Field Value
locale	en\|fr

Here is some sample return data from the POST:

[{"message":"Locale Preferences Saved"}]

SSO

Here is some sample return data:

[{"ssoEnabled":"false","signingKey":"Unassigned","signingCert":"Unassigned","changes":[{"ssoEnabled":"unchanged","signingKey":"unchanged","signingCert":"unchanged"}]},{"kerberos":{"expInt":"","header":"","attr":"","ssoEnabled":"false","signingKey":"Unassigned","signingCert":"Unassigned","certPath":"","libPath":"","isChanged":"false","changes":[{"expInt":"unchanged","serverPassword":"unchanged","ssoEnabled":"unchanged","server":"unchanged","attr":"unchanged","signingCert":"unchanged","signingKey":"unchanged","header":"unchanged"}]},"sap":{"expInt":"","header":"","attr":"","ssoEnabled":"false","signingKey":"Unassigned","signingCert":"Unassigned","certPath":"","libPath":"","isChanged":"false","changes":[{"expInt":"unchanged","libPath":"unchanged","certPath":"unchanged","ssoEnabled":"unchanged","attr":"unchanged","signingCert":"unchanged","signingKey":"unchanged","header":"unchanged"}]}},{"sso":"sso"}]

Here is some sample POST data:

Table 27-7 Sample POST Data

Field Name	Field Value
Framework	enable=true&header=fw&signKeyPassword=novell Here is some sample return data from the POST: [{"validKey":"Valid","validCert":"Valid","ssoEnabled":"true","success_message":"fw saved successfully. Values will be reflected on server restart."}]
Kerberos	attr=cn&byAttr=true&byDN=false&byKey=false&byPassword=true&enable=false&header=kerberos&int=35&server=server&serverPassword=password&signKeyPassword=novell Here is some sample return data from the POST: [{"validKey":"Valid","validCert":"Valid","success_message":"kerberos saved successfully. Values will be reflected on server restart."}]
sap	attr=cn&byAttr=true&byDN=false&certPath=locations&enable=true&header=sap&int=40&libPath=paths&signKeyPassword=novell Here is some sample return data from the POST: [{"validKey":"Valid","validCert":"Valid","success_message":"sap saved successfully. Values will be reflected on server restart."}]
custom	attr=cn&byAttr=true&byDN=false&enable=true&header=custom&int=40 Here is some sample return data from the POST: [{"validKey":"Invalid","validCert":"Valid","success_message":"custom saved successfully. Values will be reflected on server restart."}]