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