North Carolina – NCID
NCID Web Service
Creation date: 3/15/2010 Last updated: 6/15/2015 3:19 PM Revision: 2.0 Author Sridhar Sripathy Revised By Joshua Niu Revised Date 6-15-2015
Last updated on 6/15/15 3:19 PM Page 1 North Carolina – NCID
Table of Contents
1 INTRODUCTION ...... 3 1.1 PURPOSE ...... 3 1.2 OVERVIEW OF OPERATIONS ...... 3 1.2.1 Validate a user’s login credentials ...... 3 1.2.2 Group Membership Check and Modification ...... 3 1.2.3 User Search & View ...... 4 1.2.4 Organizational Structure Search ...... 4 2 APPLICATION ACCOUNTS ...... 5 2.1 PURPOSE & DESCRIPTION ...... 5 2.2 PRE-REQUISITE TO USING NCID WEB SERVICE ...... 5 3 CLIENT ACCESS TO NCID WEB SERVICES ...... 7 3.1 NCID WEB SERVICE ENDPOINT ...... 7 3.2 ACCESS TO NCID WEB SERVICE VIA 3RD PARTY SOAP TEST TOOL ...... 7 3.3 USING .NET VISUAL STUDIO AND CODE ...... 7 3.4 USING JAVA CLIENT AND CODE...... 8 4 USER SEARCH & VIEW RESPONSE FORMAT ...... 10 4.1 NCID SEARCH & VIEW RESPONSE FORMAT ...... 10 5 AUTHENTICATETONCIDV2 WEB SERVICE METHOD RETURN CODES ...... 13
6 WEB SERVICE METHODS FOR GROUP MANIPULATION ...... 14
7 SOAP RESPONSE MAPPING BETWEEN NCID LEGACY AND NCID WEB SERVICE METHODS ...... 15
8 SEARCH OPERATION TYPES ...... 19
9 AGENCY/DIVISION/SECTION ATTRIBUTE LIST ...... 20
10 USER PROFILE ATTRIBUTE LIST ...... 21
11 GLOSSARY ...... 23
Last updated on 6/15/15 3:19 PM Page 2 North Carolina – NCID
1 Introduction
1.1 Purpose
The NCID Web Service is built on the Web Service operations offered by the NetIQ Identity Management products. It works as a shim to allow end users to call NetIQ Identity Management methods without changing their API when NetIQ upgrades or changes their services.
1.2 Overview of Operations NCID Web Service methods provide the following types of functionality:
1. Validate a user’s login credentials
2. Group Membership Check and Modification
3. User Search & View o By User ID o By GUID o By selected attributes
4. Organizational Structure Search
o Search for Agencies o Search for Divisions o Search for Sections
1.2.1 Validate a user’s login credentials Using this Web Service method the application can check to see if the user can login successfully to NCID and if not, the reasons behind the login failure. This allows agency applications to augment their SSO functionality. This operation is not meant to be a replacement for an NCID reverse proxy, which is a software appliance that does both authentication and authorization based on rules and policy domains.
1.2.2 Group Membership Check and Modification Some NCID protected agency applications require membership to an agency role before a user is authorized to use that application. These roles are maintained in the application LDAP directory. This operation allows agency applications to implement native authentication and authorization based on group membership, at the same time maintaining their delegated administration within NCID with the role and resource model.
Last updated on 6/15/15 3:19 PM Page 3 North Carolina – NCID
1.2.3 User Search & View This method allows finding a user(s) based on a given criteria of userid, first name, last name etc. This operation validates the existence of users in the NCID system without the need for a manual search operation within the NCID UI. The SOAP response in NCID for search and view operations is the same.
1.2.4 Organizational Structure Search This Web Service request is useful for applications that want to create their State or Local Organizational structure based on NCID’s 3-tier structure consisting of Agencies, Divisions and Sections. This is especially useful for an application that implements fine-grained authorization based on the NCID organization structure.
NCID WebServices
NCID WSDL Application Server Identity XML Vault Response
Figure 1: NCID Web Service Architecture
Last updated on 6/15/15 3:19 PM Page 4 North Carolina – NCID
2 Application Accounts
2.1 Purpose & Description Application accounts are created for the sole purpose of being used in Web Services. A user cannot use this account to login through the NCID UI. Application accounts will be created by the NCID team with strong passwords and they obey a password policy that is different from user accounts. Application account passwords can only be changed via a request process to the NCID team.
The account needs to be created in each environment. An application account password will not be duplicated across NCID environments. Development, Pre-Production and Production will have separate passwords
2.2 Pre-requisite to using NCID Web Service An application developer planning to use the NCID Web Service suite requires an application account. A formal request to create an Application account will need to be communicated to the NCID team via a service desk ticket.
The current process associated with Application accounts is in the process diagram below:
Last updated on 6/15/15 3:19 PM Page 5 North Carolina – NCID
Application Account Creation Process
NCID Team Creates Application Account
Associate App Account to the “Application Account” Organization
Application account made a Role Manager and Resource Manager of appropriate Role(s) and Resource(s) (ex: DOA-MFM-Users)
NCID team contacts Application owner and communicates password (securely)
Agency\Customer validates the account against a webservice (ex: isMemberOfGroup)
Last updated on 6/15/15 3:19 PM Page 6 North Carolina – NCID
3 Client Access to NCID Web Services
3.1 NCID Web Service Endpoint Any application that needs to consume NCID Web Service needs to connect to the following endpoint:
DEV https://idpdncid.nc.gov/ncidwebservice/ PRE-PROD https://idppncid.nc.gov/ncidwebservice/ PRODUCTION https://idpncid.nc.gov/ncidwebservice/
In order to subscribe to the various operations available for NCID, the applications need to view the WSDL document at
DEV https://idpdncid.nc.gov/ncidwebservice/ncidws.wsdl PRE-PROD https://idppncid.nc.gov/ncidwebservice/ncidws.wsdl PRODUCTION https://idpncid.nc.gov/ncidwebservice/ncidws.wsdl
It is important that a client review the WSDL contents for what is needed for requests and what is being sent back before proceeding to develop applications.
3.2 Access to NCID Web Service via 3rd party SOAP test tool There are many open source and commercial tools available for consuming Web Services. These tools allow a developer to look at the structure of the SOAP request and response structure, for guidance on developing the right XML parsing code. These 3rd party SOAP tools aid in testing connectivity to NCID environments, and validating request/response using app id, prior to integration of Web Service calls in an agency application.
3.3 Using .NET Visual Studio and Code Below are the steps to be followed for any .NET Visual Studio projects that will need to access the custom NCID Web Service methods:
1. Ensure that an Application account has been created for the use with the Web Service offering. 2. For updates to the existing list of custom Web Service methods, the Web Reference to the WSDL location (for example in DEV) https://idpdncid.nc.gov/ncidwebservice/ncidws.wsdl will need to be re- added. Only then are the new services accessible to the code within the projects.
Last updated on 6/15/15 3:19 PM Page 7 North Carolina – NCID
3. In case code needs to point to a different environment, for example a move from DEV to PreProd, the web reference to the following needs to be change to https://idppncid.nc.gov/ncidwebservice/ncidws.wsdl Ensure that any DNs used in the code are relevant to the environment. User DNs change between environments and the GUIDs will need to be re-entered before the code can be properly tested.
3.4 Using Java client and Code Below are steps to be followed for any Java projects that will need to access the custom NCID Web Services.: For a Java client, develop a proxy object and a Java client that submits the request. You use a WSDL-to-Java conversion tool to process the WSDL file and to generate automatically a Java proxy object for the request. Here are some WSDL-to-Java tools: Apache Axis 1.4 * (or versions above) (open source product) comes with a WSDL2Java tool. Download Axis from http://ws.apache.org/axis/. Assuming that you installed Axis in the C:\axis-1_4\ location, add the following jars to CLASSPATH: C:\axis-1_4\lib\wsdl4j-1.5.1.jar C:\axis-1_4\lib\saaj.jar C:\axis-1_4\lib\log4j-1.2.8.jar C:\axis-1_4\lib\jaxrpc.jar C:\axis-1_4\lib\axis.jar C:\axis-1_4\lib\commons-logging-1.0.4.jar C:\axis-1_4\lib\commons-discovery-0.2.jar
Invoke the following command via a DOS command prompt: java org.apache.axis.wsdl.WSDL2Java -o C:\wsdl2java\ WSDLFileName Replace WSDLFileName with the actual WSDL File name, and replace C:\wsdl2java\ with the folder in which you want the code to be generated.
More information about axis-1.4 could be found on axis.apache.org website at: http://axis.apache.org/axis/java/user- guide.html#WSDL2Java:_Building_stubs_skeletons_and_data_types_from_W SDL
The current version of Apache Axis2/Java could be found at http://axis.apache.org/axis2/java/core/
Eclipse SDK 3.2 (open source product), has a Web Tools plug-in available at http://www.eclipse.org/webtools/main.html. The Web Tools platform includes a Web Service wizard, where you can create a Java Client proxy using a WSDL. The link below has the details:
http://help.eclipse.org/help31/index.jsp?topic=/org.eclipse.jst.ws.axis.ui.doc.user/tasks/tsampappa.html.
Last updated on 6/15/15 3:19 PM Page 8 North Carolina – NCID
IBM’s WSDL2Java tool that comes with the IBM WSDK. The IBM Web Services Toolkit (WSTK) is available at the following location: http://www.alphaworks.ibm.com/aw.nsf/reqs/webservicestoolkit. Before installing the toolkit, follow the directions on this site to install the IBM WebSphere SDK for Web Services. From IBM WebSphere SDK for Web Services version 5.0, open the help from the Start menu, go to Accessing a Webservice > from a standalone java application > Service Locator client. This shows you how to run a sample client.
After the Java proxy object has been generated: 1) Write a Java client to call these objects. 2) Compile the generated files and the Java client and then run the client. 3) Confirm the results.
The tool TCPMon that comes with the IBM toolkit shows the XML/Simple Object Access Protocol (SOAP) request that is sent to NCID and the SOAP response that NCID returns. The Web Tools platform in Eclipse SDK allows you to test the Web Services using the Transmission Control Protocol/Internet Protocol (TCP/IP) Monitor. The link below has the details: http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.wst.wsi.ui.doc.user/tasks/tmonitor.html.
NOTE: Prior to any consumption of this Web Service all Java client applications will need to download the SSL certificate (in .der format) and add it to their own JRE/JDK keystore.
* Please note that NCID web services are not intrinsically tied to the Java Web Service client or their versions. The instructions above are merely an example setup with a client.
Last updated on 6/15/15 3:19 PM Page 9 North Carolina – NCID
4 User Search & View Response Format
4.1 NCID Search & View Response Format The XML response from NCID is shown below. For details on the responses, please refer to the NCID WSDL documents.
Last updated on 6/15/15 3:19 PM Page 10 North Carolina – NCID
Last updated on 6/15/15 3:19 PM Page 11 North Carolina – NCID
Note: A State/Local Government employee or NCID Delegated administrators can only belong to one Organization. The
Last updated on 6/15/15 3:19 PM Page 12 North Carolina – NCID
5 AuthenticateToNCIDv2 Web Service Method Return Codes
This mapping table will be used to implement the mapping of NCID error codes to the NCID Web Service error codes that SOAP clients currently consume.
User Name Password WS Return Value Valid Valid Code = 0 (Active) Message = SUCCESS Valid Invalid Code = 103 (Active) Message =ERROR; Invalid credentials supplied Valid Valid Code = 113 (Locked) Message =ERROR; User has been locked out Valid Invalid Code = 113 (Locked) Message =ERROR; User has been locked out Valid (De- Valid Code = 101 Activated) Message =ERROR; Invalid credentials supplied Valid (De- Invalid Code = 101 Activated) Message =ERROR; Invalid credentials supplied (Archived) n/a Code = 101 Message =ERROR; Invalid credentials supplied Invalid Invalid Code = 101 Message =ERROR; Invalid credentials supplied Valid Valid Code = 111 (Active) (Expired) Message =ERROR; The password has already expired.
Last updated on 6/15/15 3:19 PM Page 13 North Carolina – NCID
6 Web Service Methods for Group Manipulation
The following Web Services allow applications to run checks against and modify NCID Groups: isMemberOfAGroup modifyGroup UnsubscribeUserFromGroup SubscribeUserToGroup
The common parameters for the above WS methods besides the application credentials are memberDN and groupDN. The memberDN parameter is the DN of a user who may be a member of the group. This user DN can be obtained by any of the User Profile Web Service methods such as searchUserByLoginID or searchUserByAttr etc.
The mapping table below shows the DN formats of different user type. Please note that Full Name may be truncated during the DN construction and hence obtaining the exact DN from a Web Service call is the preferred method as opposed to constructing it programmatically via attributes. MemberDN (NCID) Comment cn=John Doe - 3f79afc8-5025-4adf-be55- For State Employee User Type 5b24282c440b,ou=State,ou=Internal,ou=People,o=NC cn=John Doe - 3f79afc8-5025-4adf-be55- For Local Gov Employee User Type 5b24282c440b,ou=Local,ou=Internal,ou=People,o=NC cn=John Doe - 3f79afc8-5025-4adf-be55- For Business User Type 5b24282c440b,ou=Business,ou=External,ou=People,o= NC cn=John Doe - 3f79afc8-5025-4adf-be55- For Individual User Type 5b24282c440b,ou=Individual,ou=External,ou=People,o =NC
The Group DN example is as follows: GroupDN (NCID) Comment cn=DOA-MFM-Users - 69941555-7b5e-4880-b2b8- Format for all Groups in NCID is 34bfb249e492,ou=Groups,o=NC Group Name – GUID, ou=Groups, o=NC
Last updated on 6/15/15 3:19 PM Page 14 North Carolina – NCID
7 SOAP Response Mapping between NCID Legacy and NCID Web Service Methods
Inde Method NCID Response x 1. The Well-formed and validated XML Soap isMemberOfAGroup(UserID As Response within isMemberOfAGroupResult string, Password As tag is either true or false: string, memberDN As
2. Returns the status of the provisioning modifyGroup(UserID As request: string, Password As PROVISIONED string, memberDN As PROVISION string, groupDN As DENIED NEW_REQUEST string, action As string) As PROVISIOINING_ERROR string CLEANUP
PROVISIONED status maps to True in NCID and DENIED maps to false. All the other status results are stages in provisioning. Since this is asynchronous process, a request may return NEW_REQUEST i.e the NetIQ IDM drivers have not completed the modification. The Well-formed and validated XML Soap Response within modifyGroupResult tag is
- PROVISION ED - 3. Well-formed and validated XML Response searchAgencies(UserID As within the searchAgenciesResult tag is: string, Password As
Last updated on 6/15/15 3:19 PM Page 15 North Carolina – NCID
4. Well-formed and validated XML Response searchDivisions(UserID As within the searchDivisionsResult tag is: string, Password As
5. Well-formed and validated XML Response searchSections(UserID As within the searchSectionssResult tag is: string, Password As
6. Detailed comparison of what attributes searchUserByAttr(UserID As are display is shown in a different table. string, Password As The following well-formed and validated string, AttrName As XML appears in string, AttrVal As searchUserByAttrResult tag:
7. - same as above searchUserByGUID(UserID As string, Password As string, AttrVal As string, SearchOp As string) As
Last updated on 6/15/15 3:19 PM Page 16 North Carolina – NCID
string
8. -same as above- searchUserByLoginID(UserID As string, Password As string, AttrVal As string, SearchOp As string) As string
9. -same as modifyGroupResult- subscribeUserToGroup(UserID As string, Password As string, memberDN As string, groupDN As string) As string
10. -same as modifyGroup result- UnsubscribeUserFromGroup(U serID As string, Password As string, memberDN As string, groupDN As string) As string
11. -same as searchUserxxxxResult- viewUserByDN(UserID As string, Password As string, UserDN As string) As string
12. -same as viewUserByDN- viewUserByUserID(AppID As string, AppPassword As string, UserID As string) As string
13. -same as viewUserByDN- ViewUserByGUID(AppID As
Last updated on 6/15/15 3:19 PM Page 17 North Carolina – NCID
string, AppPassword As string, sGUID As string) As string
14. The message codes and the messages authenticateToNCIDv2(UserID as remain the same in NCID, only the XML string, Password as string) response is now well-formed and validated as below. In addition all the reasons for a login failure are returned instead of just one:
Last updated on 6/15/15 3:19 PM Page 18 North Carolina – NCID
8 Search Operation Types OSM—Substring match. Search results include entries whose value contains the data entered for this parameter.
OGE—Greater than or equal to. Search results include entries whose string value is greater than or equal to the data entered for this parameter.
OLE—Less than or equal to. Search results include entries whose string value is greater than or equal to the data entered for this parameter.
OBW—Begins with. Search results include entries whose string value begins with the data entered for this parameter.
OEW—Ends with. Search results include entries whose string value ends with the data entered for this parameter.
OEM—Exact match. Search results include entries whose string value is the same as the data entered for this parameter.
Last updated on 6/15/15 3:19 PM Page 19 North Carolina – NCID
9 Agency/Division/Section Attribute List
Agency Search Param List: These are the attributes names that need to be passed to the searchAgencies() operation in order to search for a user Index NCID Search Notes Attribute Name
1. ncEntityName 2. ncEntityShortName 3. ncEntityType The codes to be used in the search are on the left hand side: SA – State Agency LG – Local Gov
4. ncLocalEntityType C – County, K – School, I – City, E - Community College 5. ncGUID 6. ncEntryDN Dn of the Organization 7. ncStatus ACTIVE or INACTIVE
Division Search Param List: These are the attributes names that need to be passed to the searchDivisions() operation in order to search for a user Index NCID Search Notes Attribute Name
1. nDivisionName 2. ncParentAgency Dn of the agency 3. ncStatus 4. ncSectionFlag TRUE or FALSE 5. ncDivisionType S or L 6. ncGUID
Section Search Param List: These are the attributes names that need to be passed to the searchSections() operation in order to search for a user Index NCID Search Notes Attribute Name
1. nSectionName 2. ncParentDivision A dn of the division 3. ncStatus 4. ncSectionType S or L 5. ncGUID
Last updated on 6/15/15 3:19 PM Page 20 North Carolina – NCID
10 User Profile Attribute List
User Search Param List: These are the attributes names that need to be passed to the searchUserByAttr() operation in order to search for a user Index NCID Search Notes Attribute Name
1. givenName 2. sn 3. fullName Not always present 4. ncGUID 5. InternetEmailAddres s
6. Uid
User View Attribute List: These are the attributes exposed in the SOAP responses of searchUserxxxx() and viewUserxxx() operations Index NCID Attr Label NCID Search Notes Attribute Name
1. Prefix personalTitle Mr., Ms., etc –(O) 2. First_Name givenName 3. Middle_Initial Initials Not always present 4. Last_Name Sn 5. Suffix generationQualifier Jr., Sr., etc - Not always present 6. Full_Name fullName First + MI + Last Name 7. User_ID Uid Can change 8. Business_Phone telephoneNumber Not always present 9. Extension ncBusinessPhoneExte Not always present nsions
10. Address_Line 1 postalAddress Not always present 11. Address_Line 2 postalAddress2 Not always present 12. City L Not always present 13. State St Not always present 14. Zip_Code postalCode Not always present 15. eMail Mail Not always present 16. Employee_Type employeeType Full Time, Part Time, Contractor - Not always present
Last updated on 6/15/15 3:19 PM Page 21 North Carolina – NCID
Index NCID Attr Label NCID Search Notes Attribute Name
17. User_Type ncUserType Passed as one character S - State employee L - Local employee B - Business I - Individual 18. GUID NcGUID Unique and does not change 19. Member_of_Organiz ncMemberOfOrganizati Passed as a DN reference - Not ation on always present
20. Member_of_Division ncMemberOfDivision Passed as a DN reference - Not always present
21. Member_of_Section ncMemberOfSection Passed as a DN reference - Not always present
22. Password_Expiratio ***passwordExpiration n_Time Time
23. Login_Disabled ***loginDisabled True or False - Not always present 24. I Locked_By_Intruder ***LockedByIntruder True or False 25. Status ***ncAccountStatus ACTIVE, DEACTIVATED 26. Account_Expiration_ ***ncAccountExpiration Required for Contractors - Not Date Date always present
27. Role nrfAssignedRoles Role Name - Not always present 28. Resource nrfAssignedResources Resource Name, - Not always present
* Attribute name remains the same where blank under NCID Attribute ** Some attributes are required for certain user types ***Display of account status attributes are an enhancement
Last updated on 6/15/15 3:19 PM Page 22 North Carolina – NCID
11 Glossary
NCID: Indicates the NCID system based on the NetIQ Identity Management suite of products. Role(s): Access control in NCID system is defined by roles. Example: NCID Delegated Administrators are assigned appropriate roles that define which users then can administer for password resets, unlocks etc. Resource(s): This can either a membership to a Group, system account on a Linux server etc. WSDL: WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services).
Last updated on 6/15/15 3:19 PM Page 23