Integration Document - MITA1 · Integration Document ... The Client should enroll and install the...
29
Malta Information Technology Agency, Gattard House, National Road, Blata l-Bajda HMR 9010 Malta Telephone: (+356) 21234710 Facsimile: (+356) 21234701 Web Site: www.mita.gov.mt Integration Document eID Live Integration Document Date: 21/11/2013 Version: 1.1 Department: ECPD Public
Transcript of Integration Document - MITA1 · Integration Document ... The Client should enroll and install the...
Malta Information Technology Agency, Gattard House, National Road, Blata l-Bajda HMR 9010 Malta
Telephone: (+356) 21234710 Facsimile: (+356) 21234701 Web Site: www.mita.gov.mt
Integration Document
eID Live Integration Document
Date: 21/11/2013
Version: 1.1 Department: ECPD
Public
Public MITA eID Integration Procedure - Live
Page i
Document Control Information
01. Document reference
IMSU-REP-EIDProcedure-Live-v1.1.doc
02. Document type
Procedure
03. Security classification
Public
04. Synopsis
Document entails the procedures to integrate to the live eID Web services.
05. Document control
Author Change controller Distribution controller
IMSU IMSU IMSU
This document may be viewed and/or downloaded from the IMS On-Line, which maintains the latest issues of all documents and forms.
06. Authorisation
Issuing authority Approval authority
Signature / Date Signature / Date
Wayne Grixti Consultant / ECPD
Adrian Camilleri Programme Manager / ECPD
07. Modification history
Version Date Comments
Version 1.0 20/11/2012 First version for release
Version 1.1 21/11/2013 Appendices E, F, G and H
Public MITA eID Integration Procedure - Live
Page ii
Table of Contents
DOCUMENT CONTROL INFORMATION ............................................................................................................................I
TABLE OF CONTENTS .....................................................................................................................................................II
01. BACKGROUND.....................................................................................................................................................1
02. SCOPE .................................................................................................................................................................2
03. DEFINITIONS .......................................................................................................................................................3
04. PROCESS MAP ....................................................................................................................................................4
05. ACCESS TO THE EID WEB SERVICES ................................................................................................................5
05.1 APPLICATION HOSTED ON A SHE ...........................................................................................................................5 05.2 APPLICATION HOSTED WITHIN MITA .......................................................................................................................5 05.3 SUPPLIERS .........................................................................................................................................................5
06. EXPIRY OF DIGITAL CERTIFICATE .....................................................................................................................6
APPENDIX A – RAISE AN ERFS .......................................................................................................................................8
A1. REQUEST FOR A NEW EID ACCOUNT ............................................................................................................................8 A2. REQUEST FOR DIGITAL CERTIFICATE ...........................................................................................................................8
APPENDIX B – ENROLMENT OF DIGITAL CERTIFICATE.................................................................................................9
APPENDIX C – EXPORT DIGITAL CERTIFICATE ........................................................................................................... 10
C1. EXPORT CERTIFICATE WITH PRIVATE KEY.................................................................................................................. 11 C2. EXPORT CERTIFICATE WITHOUT PRIVATE KEY (PUBLIC KEY).......................................................................................... 13
APPENDIX D – ELECTRONIC IDENTITY FORM.............................................................................................................. 16
APPENDIX E – WEB SERVICES ..................................................................................................................................... 18
E1. SYSTEM LOGON ...................................................................................................................................................... 18 E2. SYSTEM LOGOFF ..................................................................................................................................................... 18 E3. CHECK VALID SESSION ............................................................................................................................................ 18 E4. GET ENTITY TYPE ................................................................................................................................................... 18 E5. GET ESERVICE........................................................................................................................................................ 18 E6. GET ENTITY ESERVICES ........................................................................................................................................... 19 E7. GET USER ESERVICE EXTENDED............................................................................................................................... 19 E8. GET ORGANISATION ESERVICE EXTENDED ................................................................................................................. 19 E9. GET CITIZEN ........................................................................................................................................................... 19 E10. GET ORGANISATION .............................................................................................................................................. 20
APPENDIX F – SAMPLE CODE – BIND DIGITAL CERTIFICATE TO EID WEB SERVICE ................................................ 21
APPENDIX G – SAMPLE CODE – READING RANDA2 COOKIE ...................................................................................... 22
APPENDIX H – CERTIFICATE CONFIGURATION TOOL ................................................................................................. 24
Public MITA eID Integration Procedure - Live
Page 1
01. Background
The eID framework, which is hosted at MITA, provides a shared authentication mechanism for e-Government services. Service providers can integrate their respective e-Government service with the eID framework through a process that spans over the involvement of the IDMO and the respective parties within MITA as defined by this procedure.
Public MITA eID Integration Procedure - Live
Page 2
02. Scope
The scope of this document is to lay down the processes and procedures for 3rd
party integrators to integrate their application with the Electronic Identity services.
Public MITA eID Integration Procedure - Live
Page 3
03. Definitions
eID Electronic Identity
ERFS Electronic Request For Service
IDMO Identity Management Office
IGS Internet and Groupware Services
IMSU Identity Management Systems Unit
SCC Service Call Centre
SHE Segregated Hosting Environment
Public MITA eID Integration Procedure - Live
Page 4
04. Process Map
MITA eID Integration Procedure – Live Environment
SupplierIGS IMSUClient
Start
Raise ERFS
and Fill the
Electronic Identity
Form
Export Certificate
without the private
key
Export Certificate
with private key
Create EID
credential_username
and EID
credential_password
Set appointment with
Client in MITA Data
Center to create EID
credential_password
Send Certificate to
IGS
End
Bind Certificate
Install on SHE
environment
Approve Change
Request
Hosted at
MITA?
Go to Section
5.2
Yes
No
Enroll Certificate
Require
Network
Access?
Yes
No
ERFS for
Request for
access and Appy
for Digital
Certificate under
the eID
Webservices
Section
ERFS
Approval by
IDMO
Public MITA eID Integration Procedure - Live
Page 5
05. Access to the eID Web Services
This section explains the basic steps required by 3rd
party integrators to integrate with the Live eID Environment for applications hosted on a Segregated Hosted Environment (SHE) and applications hosted within the MITA Web Framework. Applications hosted on a SHE require 2-factor authentication to be able to access the eID web services, i.e. a username and password, and digital certificate.
05.1 Application hosted on a SHE
The Client is requested to raise an ERFS to open access to the live eID web services and another ERFS to procure a digital certificate (refer to Appendix A – Raise an ERFS). The ERFSs must be approved by the CIO. Following approval a change is requested to open network access from the SHE to the Live eID Environment. The IGS Team within MITA, schedules an appointment with the Client at MITA-01 to create the personalized eID Web Service credentials.
The Electronic Identity Form (refer to Appendix D – Electronic Identity Form) must be filled in by the Client and handed over to the IGS representative during the appointment at MITA-01. The Client should enroll and install the digital certificate on the server, and then export the certificate without the private key and forward via email to the IGS team ([email protected]), and copy the eID Support ([email protected]) (Refer to Appendix C – Export Digital Certificate). The email subject should include the ERFS number.
05.2 Application hosted within MITA
The Client is requested to register the new eService with the IDMO and communicate the information regarding the new eService to the eID Support on [email protected].
05.3 Suppliers
Technical Documentation The technical eID integration guide that provides technical information on the eID integration interfaces is available at https://www.mita.gov.mt/page.aspx?pageid=258. Configuration Parameters Once the application with the IDMO is complete, the AppKey (or Organisation Key) and the Service Key are provisioned. Web Service Interfaces The list of eID web service URLs is made available in Appendix E – Web Services. Sample Source Code Appendix F – Sample Code – Bind Digital Certificate to eID Web Service provides sample source code for 3
rd party integrators to be able to bind the Digital Certificate with the Web Service request.
Public MITA eID Integration Procedure - Live
Page 6
06. Expiry of Digital Certificate
One (1) month prior expiration of the Digital Certificate an email is sent to the mailbox that was set when carrying out the enrollment of the Digital Certificate.
1. Renew certificate using link in the email. The email received will look as follows:
From: [email protected] Subject: Your Digital ID is ready Dear <>, Your Administrator has approved your Digital Certificate request. To assure that someone else cannot obtain a Digital Certificate that contains your personal information, you must retrieve your Digital Certificate from a secure web site using a unique Personal Certificate Identification Number (PIN). You can retrieve your Digital Certificate by following these simple steps: Step 1: Visit the Digital Certificate retrieval web page. You can retrieve your Certificate at: For Netscape users please visit: https://onsite.trustwise.com/services/GovernmentofMaltaeMailCertificateServi ce/client/nspickup.htm For Microsoft users please visit: https://onsite.trustwise.com/services/GovernmentofMaltaeMailCertificateServi ce/client/mspickup.htm Step 2: In the form, enter your Personal Identification Number (PIN): Your PIN is: <> Step 3: Follow the instructions on the page to complete the installation of your Digital Certificate. If you applied for Secure email service with token, please note that you will be contacted for an appointment. If not, kindly refer to the attachments sent previously via email from the MITA Call Centre mailbox to configure Secure email on MS Outlook. Please do not reply or send messages to this e-mail address. If you require further information/assistance, please contact MITA Service Call Centre on telephone number 25992777 or send an e-mail to [email protected] MITA Service Call Centre
Public MITA eID Integration Procedure - Live
Page 7
2. The Client should export the certificate without the private key and forward via email to IGS ([email protected]) and copy the eID Support ([email protected]). In the email, the Client must include the Service Application Name and the Login Name.
Public MITA eID Integration Procedure - Live
Page 8
Appendix A – Raise an ERFS
A1. Request for a new eID Account
Steps to request for a new eID account:
- Log in the ERFS System.
- Choose the eID Web services from the displayed list of services as shown in Figure A1 below
and select Request for Access to the live eID Environment1;
Figure A1: eID WebServices
- The window displayed in Figure A2 below should be displayed. Fill in the service details in the
provided fields.
Figure A2: Details of request
A2. Request for Digital Certificate
Create a new request for a digital certificate through the ERFS system.
1. Log on the ERFS System.
2. Tick the checkbox Apply for an eID Web service Digital Certificate1.
3. Follow the instructions to enroll and obtain the digital certificate. (Refer to Appendix B)
4. Install the digital certificate on the server.
5. Export the certificate without the private key and forward via email to IGS ([email protected])
and copy the eID Support ([email protected]), including the ERFS number within the subject. (Refer to Appendix C – Export Digital Certificate)
1 These requests shall trigger the necessary changes that will be carried out by MITA.
Public MITA eID Integration Procedure - Live
Page 9
Appendix B – Enrolment of Digital Certificate
An email is sent to the requester’s mailbox including a link to enroll the Digital Certificate. Enrolment URL: https://onsite.trustwise.com/services/GovernmentofMaltaeMailCertificateServiceG2/client/userEnrollMS.htm
Figure B2: Enrolment Form
Public MITA eID Integration Procedure - Live
Page 10
Appendix C – Export Digital Certificate
This section explains the steps required to export the certificate: C1. With Private key C2. Without Private Key (Public key only)
- Click on Internet Explorer
- Tools
- Internet Options
- Click on the Content Tab
- Click on the Certificates button (refer to Figure C1)
Figure C1 – IE Options
- Select the Certificate and click on the export button (refer to Figure C2)
Public MITA eID Integration Procedure - Live
Page 11
Figure C2 – IE Certificates
- Certificate export wizard will load and click on next (refer to Figure C3)
Figure C3 – IE Export Wizard
C1. Export Certificate with Private Key
- Select the radio button which says Yes, export the private key and click next (refer to Figure
C4)
Public MITA eID Integration Procedure - Live
Page 12
Figure C4 – IE Export private key
- Tick checkboxes (refer to C5) o Include all certificates in the certification path if possible o Export all extended properties
Figure C5 – IE Export private key – File Format
- Enter password and click next (refer to Figure C6)
Public MITA eID Integration Procedure - Live
Page 13
Figure C6 – IE Password
C2. Export Certificate without private key (public key)
- Select the radio button which says No, do not export the private key and click next (refer to
Figure C7)
Figure C7 – IE Export without private key
Public MITA eID Integration Procedure - Live
Page 14
- Select option DER encoded binary X.509(.CER)
Figure C8 – IE Export without private key – File Format
The next steps apply to both (export of the private and public key).
- Specify path where to export the eID Digital Certificate (refer to Figure C9)
Figure C9 – IE Export Path
Public MITA eID Integration Procedure - Live
Page 15
- Click finish (refer to Figure C10)
Figure C10 – IE Export Complete
Public MITA eID Integration Procedure - Live
Page 16
Appendix D – Electronic Identity Form
The Electronic Identity Form must be filled in by the Client and handed over to the IGS representative during the appointment at MITA Data Centre.
Public MITA eID Integration Procedure - Live
Page 1
Electronic Identity Form ERFS Number: ________________________________________________
Applicant Details Name and Surname: ________________________________________________ Identity Card Number: ________________________________________________ Organisation Name: ________________________________________________ Organisation Address: ________________________________________________ ________________________________________________ ________________________________________________ E-mail Address: ________________________________________________ Contact Number: ________________________________________________ Authorising Officer Name and Surname: ________________________________________________ Authorising Officer Email Address: ________________________________________________ Authorising Officer Contact Number: ________________________________________________
Electronic Service Details Name of Electronic Service: ________________________________________________ Brief Description of Electronic Service: ________________________________________________ ________________________________________________ ________________________________________________
Public MITA eID Integration Procedure - Live
Page 2
Supplier Name: ________________________________________________ Supplied Login: ________________________________________________ Electronic Service hosting address: ________________________________________________ (Public)
Terms
01. Application Accounts’ password complexity requirements: a. Passwords must be at least fifteen alphanumeric characters long; b. Passwords must contain both upper and lower case characters (e.g. a-z, A-Z); c. Passwords must have digits and punctuation characters as well as letters e.g. 0-
9,!@#$%^&*()_+|~-=\’{}[]:”;’<>?,./); d. Passwords must not be dictionary words in any language, slang, dialect, jargon, etc.; e. Passwords must not contain keyboard patterns e.g. qwerty, 12345; f. Passwords must not contain work related acronyms; g. Passwords must not contain Individual username or variations of the username; h. Passwords must not be based on personal information, names of family, etc.
02. Application Accounts’ passwords must be handled securely by the application. 03. The confidentiality of Application Accounts’ passwords must be safeguarded at all times.
04. Application Accounts are non-transferable and their use should be limited exclusively to the
organisation owning the electronic service.
05. The authorized officer is responsible for the account and password and its security at all
times.
06. The authorized officer is responsible for renewing the digital certificate before expiring.
□ I have read and accepted the terms displayed within this form
____________________________________ ____________________________________ Signature Date
Public MITA eID Integration Procedure - Live
Page 18
Appendix E – Web Services
This section contains information about the eID Web Services. URLs marked SHE are to be used for applications hosted on the Segregated Hosting Environment and URLs marked as Internal are for applications hosted within MITA.
E1. System Logon
Before any interactions can be done the eCitizen will need to authenticate with the eID. The authentication can be achieved by calling the web service systemlogon.asmx. SHE: https://services.mygov.mt/eidws/WebServices/session/systemlogon.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/session/systemlogon.asmx
E2. System Logoff
When an eCitizen has finished using the required eservices the eID session needs to be terminated. To terminate the session call the web service systemlogoff.asmx. SHE: https://services.mygov.mt/eidws/WebServices/session/systemlogoff.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/session/systemlogoff.asmx
E3. Check Valid Session
The web service will be used to check that the existing session information held by a service provider is still valid. Calling the web service will also renew the existing session, which will be extended by the configured session lifetime. To check if the user has an existing valid session and renew session timeout, call the web service checkvalidsession.asmx. SHE: https://services.mygov.mt/eidws/WebServices/session/checkvalidsession.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/session/checkvalidsession.asmx
E4. Get Entity Type
The web service will return the entity associated with a given entity id. Each entity id can only be associated with one entity type. The entity type can be either an eCitizen or Organisation. To determine the entity type, call the web service getentitytype.asmx. SHE: https://services.mygov.mt/eidws/WebServices/eservice/getentitytype.asmx. Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/eservice/getentitytype.asmx
E5. Get eService
The web service will return all the information held about an eService.
Public MITA eID Integration Procedure - Live
Page 19
To retrieve the eService and related information call the web service geteservice.asmx. SHE: https://services.mygov.mt/eidws/WebServices/eservice/geteservice.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/eservice/geteservice.asmx
E6. Get Entity eServices
The web service will return all the eServices that an eCitizen has subscribed for. The web service will also return eServices that have been assigned or delegated by another eCitizen. To retrieve the list of eServices that can be accessed call the web service getentityeservices.asmx. SHE: https://services.mygov.mt/eidws/WebServices/eservice/getentityeservices.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/eservice/getentityeservices.asmx
E7. Get User eService Extended
The web service will return the eService information and also the information submitted by the user when subscribing for the eService including any eService attributes. To retrieve all the subscription information for an eService subscribed for by an eCitizen call the web service getusereserviceex.asmx. SHE: https://services.mygov.mt/eidws/WebServices/eservice/getusereserviceex.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/eservice/getusereserviceex.asmx
E8. Get Organisation eService Extended
The web service will return the eService information and also the information submitted by the user on behalf of the organisation when subscribing for the eService including any eService attributes. Sensitive but Unclassified eID Integration Document To retrieve all the subscription information for an eService subscribed for by an organisation manager on behalf of an organisation call the web service getorganisationeserviceex.asmx. SHE: https://services.mygov.mt/eidws/WebServices/eservice/getorganisationeserviceex.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/eservice/getorganisationeserviceex.asmx
E9. Get Citizen
The Get Citizen web service will return the eCitizen information held by the eID. To retrieve the information for an eCitizen call the web service getcitizen.asmx. SHE: https://services.mygov.mt/eidws/WebServices/profile/getcitizen.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/profile/getcitizen.asmx
Public MITA eID Integration Procedure - Live
Page 20
E10. Get Organisation
The Get Organisation web service will return the Organisation information held by the eID. To retrieve the information for an Organisation call the web service getorganisation.asmx. SHE: https://services.mygov.mt/eidws/WebServices/organisation/getorganisation.asmx Internal: http://ws.wf.root.govmt:9000/eidv2/WebServices/organisation/getorganisation.asmx
Public MITA eID Integration Procedure - Live
Page 21
Appendix F – Sample Code – Bind Digital Certificate to eID Web Service
Passing digital certificate with web service request 2 Keys in the web.config:
ClientCertificatePath - certificate path location CredentialsUser - username to authentication with webservice CredentialsPass - password to authentication with webservice CredentialsDomain - Domain to authentication with webservice
------------------------------------------------------------------------------------------------------------------------------------------- credentials = new System.Net.NetworkCredential(ConfigurationManager.AppSettings["CredentialsUser"].ToString(),
ConfigurationManager.AppSettings["CredentialsPass"].ToString(),
ConfigurationManager.AppSettings["CredentialsDomain"].ToString());
sysLogon.Credentials = credentials;
if (bool.Parse(ConfigurationManager.AppSettings["isCertificateRequired"].ToString()))
{
// Load the certificate into an X509Certificate object.
X509Certificate cert =
X509Certificate.CreateFromSignedFile(ConfigurationManager.AppSettings["ClientCertificatePath"].ToString());
sysLogon.ClientCertificates.Add(cert);
} -------------------------------------------------------------------------------------------------------------------------------------------
2 All source code in this document is provided "as is" without warranties or guarantees. The Government of Malta, MITA, the author and/or distributor of this
source code will not accept any responsibilities for the use of this source code. The user is advised to test any derived source code thoroughly before relying on it. The user must assume the entire risk of using the source code.
Public MITA eID Integration Procedure - Live
Page 22
Appendix G – Sample Code – Reading Randa2 Cookie
Reading Randa2 cookie information 3 EIdSessionEntity current = null; //get the eID cookie HttpCookie cookie = HttpContext.Current.Request.Cookies.Get(<EIdSSOCookieName>); if (cookie != null) { if (!string.IsNullOrEmpty(cookie.Value)) { //set up the current session current = new EIdSessionEntity(); current.value = cookie.Value; current.cypherText = GetCypherText(cookie.Value); current.locale = GetLocale(cookie.Value); } } /// <summary> /// Helper method to get the Cypher Text from the eId cookie value /// </summary> /// <param name="value">value stored in the eId cookie</param> /// <returns></returns> private static string GetCypherText(string value) { return value.Substring(0, value.LastIndexOf("|")); }
3 All source code in this document is provided "as is" without warranties or guarantees. The Government of Malta, MITA, the author and/or distributor of this
source code will not accept any responsibilities for the use of this source code. The user is advised to test any derived source code thoroughly before relying on it. The user must assume the entire risk of using the source code.
Public MITA eID Integration Procedure - Live
Page 23
// Call Web Service frameworkManager.LogTrace("CheckValidSession - Started"); //set up the service request header EGovRequestHeader header = new EGovRequestHeader(); header.AppKey = <EIdWebServiceKey>; header.CypherText = session.CypherText; header.Locale = session.Locale; checkvalidsession checkValidSession = new checkvalidsession(); checkValidSession.Url = <EIdWebServiceCheckSessionUrl>; checkValidSession.Credentials = new System.Net.NetworkCredential(<EIdWebServiceDomainUser>, <EIdWebServiceDomainPassword>, <EIdWebServiceDomainName>); if (<EIdUseCertificate>) { checkValidSession.ClientCertificates.Add(GetAuthenticationCertificate(<EIdCertificateSerialNumber>); } checkValidSession.EGovRequest = header; sessionValidated = checkValidSession.CheckValidSession(); eGovResponse = checkValidSession.EGovResponse; if (sessionValidated) { LogTrace("CheckValidSession - Result: Valid"); } else { LogTrace("CheckValidSession - Result: Invalid"); }
Public MITA eID Integration Procedure - Live
Page 24
Appendix H – Certificate Configuration Tool
Certificate Configuration Tool enables administrators to install and configure client certificates in any certificate store. Note: The user must have sufficient privileges to use this tool, which requires the user to be an administrator and the same user who installed the client certificate.
1. Import certificate: winhttpcertcfg -g -i certificatepath -c LOCAL_MACHINE\My -a accountname -p pfxpassword
2. Grant access to user account: winhttpcertcfg -g -c LOCAL_MACHINE\My -s certificatename -a useraccount
For example winhttpcertcfg -g -i "c:\eidcert.pfx" -c LOCAL_MACHINE\My -a IIS_IUSRS -p password
winhttpcertcfg -g -c LOCAL_MACHINE\My -s [email protected] -a useraccountname
Use the following command to view which accounts can access the certificates: winhttpcertcfg -l -c LOCAL_MACHINE\My -s [email protected]
For further reference view the following link: http://msdn.microsoft.com/en-us/library/windows/desktop/aa384088(v=vs.85).aspx
Public MITA eID Integration Procedure - Live
Page 25
Blank Page
