DRAFT For Discussion Purposes Only

Transcription

1 DRAFT For Discussion Purposes Only Statements or comments made by the ministry or information provided in the draft technical specifications are not binding on the ministry. In particular, the ministry makes no representations or warranties of any kind whatsoever in any way arising out of or in connection with the information provided and will not be responsible or liable for any losses, damages, expenses or costs of any kind whatsoever incurred by the Vendors in any way arising out of or in connection with the information provided. Vendors should note that the contents of the final technical specifications may vary from the draft document provided. Technical Specifications for MOHLTC Electronic Business Services (EBS)

2 Table of Contents TABLE OF CONTENTS... 2 GLOSSARY... 3 NOTICE TO READER... 6 INTENDED AUDIENCE FOR THIS TECHNICAL SPECIFICATION DOCUMENT... 7 ABOUT THIS DOCUMENT... 8 INTRODUCTION... 9 Certificate Specifications...10 EBS Web Service Interface...10 MSA Security Process...11 IDP Security Process...12 TECHNICAL INTERFACE SOAP Message:...13 The Message WSDL...13 SAML ASSERTION Identity Requirements...15 SAML Assertion Table...15 EBS: STRUCTURE OF THE SAML ASSERTION Hierarchy...16 Authorization Process...17 Signing Requirements...17 Audit Log data elements and format...17 TESTING APPENDIX A: ERROR CODES APPENDIX B: THE SOAP MESSAGE WSDL POLICY STATEMENT

3 Glossary Term Assertion Identifier Claim Submission Number (CSN, a.k.a. Billing Number) Digital Certificate End User Electronic Medical Records (EMR) GUID Health Care Provider (HCP) Health Information Custodian (HIC) Ministry Unique Identifier Identity Provider (IDP) MOHLTC Definition The name of the assertion identifier attributes ID. The type of the identifier attribute is xs:id. A unique identifier that is assigned to a Health Care Provider who is registered with MOHLTC on the Corporate Provider Database for the purpose of submitting claims for insured services. An electronic identity card that includes information about: the card holder; the issuer of the certificate; and cryptographic data that enables independent verification of those identities. The certificate includes the public key of the holder, which can be used to verify the source of electronic documents, and to encrypt electronic documents such that they can be decrypted only by the intended recipient. A Health Information Custodian (HIC) or an agent of a HIC (i.e. employee, 3 rd party service provider) acting under the direction and control of the Service User and who is the individual taking the physical steps necessary to invoke an EBS service on behalf of the Service User. An Electronic Medical Record (EMR) formerly known as Clinical Management System (CMS) is a system that enables physicians' to store patient administrative/clinical information/charts electronically and is typically interactive. All patient information is stored within the physician's systems/service including the patient Electronic Health Record (EHR... The implication is that this system has interoperability/interconnectivity features built in. An EMR should have the ability to transfer data to other EHRs, hospitals, labs, ministry etc. Globally Unique Identifier Individual, group or facility licensed to provide health care services to residents of Ontario. Health Information Custodian as defined in Personal Health & Information Privacy Act (PHIPA). An identifier assigned by the Ministry of Health and Long- Term Care to individuals or organizations that access ministry services. A kind of service provider that creates, maintains, and manages identity information for principals and provides principal authentication to other service providers The Ontario Ministry of Health and Long-Term Care. 3

4 Term Master Services Agreement (MSA) PHI Security Assertion Mark-up Language (SAML) Sender -Vouches Service Provider (SP) Service Requestor (SR) Service User (SU) Simple Object Access Protocol (SOAP) Stakeholder Number (SN) Trusted Certificate Authority Web Services Security: SAML Token Profile 1.1 Definition The binding legal agreement through which MOHLTC accepts the identity of an end user at face value based on authenticating the Service Requestor and Service User at the time of the service request. Protected Health Information An XML based framework for ensuring secure transmission of electronic messages. SAML version 2.0 will be used for: identification; authentication; and authorization of parties using EBS as well as ensuring message integrity by means of a digital signature applied to each message. For more information refer to The sender-vouches confirmation method is used when a server needs to propagate the client identity with SOAP messages on behalf of the client. This method is similar to identity assertion, but it has the added flexibility of using SAML assertions to propagate not only the client identity, but also propagate client attributes. The attesting entity must protect the vouched for SAML assertions and SOAP message content so that the receiver can verify that it has not been altered by another party Throughout this document, Service Provider refers exclusively to MOHLTC, as the provider of a service via EBS. The business entity that sends the SOAP message to the ministry s web service via EBS on behalf of a user and asserts the identities. The HIC on who s behalf the web service is being used. An XML-based protocol for exchanging structured information between computer systems. A unique identifier that is assigned to stakeholders of interest who are registered with the MOHLTC on the Corporate Provider Database. The unique identifier is either 7 digits long or 8 digits long depending on the type of stakeholder to which it belongs. A third party organization recognized by the Ministry of Health and Long-Term Care as an approved certificate authority. This specification defines the use of Security Assertion Markup Language (SAML) assertions as security tokens from the <wsse:security> header block defined by the WSS: SOAP Message Security specification. For more information refer to 4

5 Term Web Services Description Language (WSDL) Definition Simple Object Access Protocol: an XML-based protocol for exchanging structured information between computer systems. For more information refer to 5

6 Notice to Reader All possible measures are exerted to ensure accuracy of the contents of this manual; however, the manual may contain typographical or printing errors. The public is cautioned against complete reliance upon the contents hereof without confirming the accuracy and currency of the information contained herein. The Crown in Right of Ontario, as represented by the Ministry of Health and Long-Term Care (MOHLTC), assumes no responsibility for any person s use of the material herein or any costs or damages associated with such use. This technical specification is intended to be a technical document to guide the development of the services via MOHLTC Electronic Business Services (EBS), a web interface service client application. The business relations, roles and responsibilities are governed solely by the terms agreed to within the Master Services Agreement (MSA) and appropriate Service Schedule or the use of an approved Identity Provider, part of the enrolment criteria for services via EBS. Revisions to the specification will be made as required. The ministry will make every effort to give as much advance notice as possible. It is essential that implementers keep current regarding any changes to this specification. The current version of the technical specification will be available for download at the following URL: Please direct any questions that arise during the integration of your computer system with the standardized, internet based protocols, assertions and communication methods described in this Technical Specifications document to the Service Support Contact Centre (SSCC) at or SSContactCentre.MOH@ontario.ca. 6

7 Intended Audience for this Technical Specification Document This document is intended for use by developers of applications and products that support communication with MOHLTC EBS. These services are built to the web services standards detailed in this document. This document is also intended to be read in the context of either a service agreement between the ministry and the Service Requestor (SR) through a Master Service Agreement (MSA) and the appropriate service(s) Schedule(s) between the ministry and the Service Requestor (SR) or a Service Users (SU) use of an approved EBS Identity Provider and the acceptance of the appropriate Acceptable Use Policy for the required service(s). Since the actual message in support of the request for the service via EBS is made by a Service Requestor or a Service User this technical specification is targeted to either of these users. This technical specification is also targeted to vendors of various software applications and products that have or plan to have modules that support EBS through a web service interface within the province of Ontario in Canada. The document describes the web service, the SOAP message specification and the SAML 2.0 assertion specification and aims to guide the users in the development of client application to integrate with this web service. It is assumed that the reader has knowledge of web services and related protocols, SOAP and XML message formats/processing, SAML 2.0, relevant interoperability profiles and identity assertions. 7

8 About This Document The Ministry of Health and Long-Term Care provides internet accessible services to health care providers (HCP). This document is intended as the starting point for all web service technical specifications. It outlines the security requirements that all web services may adhere to. Technical Specification Document Flow Diagram As such the specifications for individual web services will reside in secondary technical specifications. Designers and developers will need to adhere to the EBS security technical specifications and the appropriate web service specification(s) to be successful in implementing a client for a service. This document is intended to provide the reader with sufficient information to implement either of the supported EBS security interfaces. All EBS will support one of or both of these security frameworks. For ministry web service specifications a user should consult the appropriate technical specification for that service implementing of both the required EBS security interface and the ministry web service interface. The SOAP Message Section provides the technical specifications of the SOAP message including: Message Web Services Description Language (WSDL); The SAML section includes: Technical specifications of the SAML 2.0 assertion; Identity requirements; Signing requirements ; and Time stamps. Appendices provide: Error codes; SAML Elements; 8

9 Introduction This document represents the first in a series of technical specifications that outline the specification for services under the ministry s EBS initiative. As such this document is the entry point for all technical specifications for all services that are provided as part of the EBS. This document outlines the supported security models and the specifications around client software supporting these security models. There are two supported security models. The first is the Master Services Agreement (MSA) model and the second is the Identity Provider (IDP) model. Security Model: Master Service Agreement Third Party Assurance - Certificate Authority - Registration Authority - Contract Management High Trust Internal ID Providor Service Requestor Ministry of Health and Long-Term Care End User Identity and Attributes are asserted to MOHLTC Policy Agreement 9

10 All MOHLTC EBS will support one or both security models. Certificate Specifications Each SR in the MSA model or SU in the IDP model will need to have a valid certificate from a ministry accepted certificate authority. This certificate must be a medium level certificate or on a case by case basis a suitable alternative agreed to by the ministry to be used for any EBS. To ensure confidentiality and integrity of sensitive information within the message, sender software must use public key technology to encrypt user passwords (and any other sensitive data) with the service's public key and sign the resulting assertion using its own private key. The signing certificate must be issued by a ministry approved authority. All PHI data being returned by services will use the WS-Security protocol to encrypt the data. The public key of the caller will be used to encrypt any returned PHI data. EBS Web Service Interface EBS provides a sustainable, convenient, efficient and secure manner for health service providers and the ministry to send and receive personal health information and establishes a foundation for other electronic service delivery programs. 10

11 The EBS considers up to four roles in the end to end process of providing services: Role Service Provider (SP) Service Requestor (SR) Service User (SU) End User Description MOHLTC The entity that transmits a service request to MOHLTC. This term is only used in the MSA agreement model. Each SR has a Ministry Unique Identifier and this identifier is validated by MOHLTC on each request. An entity that is a HIC and has its own Ministry Unique Identifier (eg. Claim Submission Number (CSN) or Stakeholder Number (SN)). This identifier is asserted within the SOAP message and is validated by MOHLTC on each request. The person who initiates the service request. In the MSA agreement model this end user must be identified within the SR environment. This identifier is generated by the SR and asserted within the SOAP message in support of logging within the service via EBS transaction. In the IDP agreement model this end user is authenticated by the IDP. MSA Security Process 1. Health services patient / consumer requests an EBS service. 2. HCP or agent (End User) submits the request into an electronic system (this could be a hospital Clinical Management System (CMS), an Electronic Medical Record (EMR) or Hospital Information System (HIS), a purpose built application or other). 3. Service User (could be the Service Requestor) submits a validation request to Service Requestor on behalf of End User 4. Service Requestor verifies identity and authorization of Service User and End User. 5. Service Requestor constructs SOAP message using appropriate values, and inserts SAML assertion/s into the SOAP message header to assure the Service Provider that the End User is an individual authorized to access the service. The assertion includes a digital signature to guarantee message integrity and source. 6. Service Requestor submits the request. 7. MOHLTC receives the request. 8. MOHLTC verifies message signature, authorizes the asserted identities within message, processes the request and sends the response back to the Service Requestor. 11

12 9. The Service Requestor receives the signed and possibly encrypted response. 10. Service Requestor verifies message signature, decrypts encrypted data, and makes available the response to Service User and End User as per the agreement between the SR and the Service User. The web service identifies the entities at each layer based on the identifiers provided through SAML assertions for the Service Requestor, Service User and End User. These identifiers are expected in specific attributes within the SAML Assertions. Various scenarios could arise; at one end of the spectrum an entity can assume all the roles (SR, Service User and End User) and at the other end of the spectrum a different entity can assume each of the specified roles. At the SR level - Ministry Unique Identifier the SN is expected, and Service User level - a Ministry Unique Identifier the SN or CSN - is expected. The ministry expects valid identifiers issued by the ministry. IDP Security Process 1. Health services patient / consumer requests a service from an HCP. 2. HCP or agent (End User) submits the request into an electronic system (this could be a hospital Clinical Management System (CMS), an Electronic Medical Record (EMR) or Hospital Information System (HIS), a purpose built application or other). 3. End User submits a request to Service Provider. 4. End User constructs SOAP message using appropriate values, and inserts SAML assertion/s into the SOAP message header with the user name and password for an approved IDP. The assertion includes a digital signature to guarantee message integrity and source. 5. MOHLTC receives the request. 6. MOHLTC verifies message signature, authenticates the asserted identities within message, processes the request and sends the response back to the Service Requestor. 7. The End User receives the signed and possibly encrypted response. 8. Service User verifies message signature, decrypts encrypted data, and makes available the response to Service User and End User. The web service identifies the entities at each layer based on the identifiers provided through SAML assertions for the Service User and End User. These identifiers are expected in specific attributes within the SAML Assertions. 12

13 Technical Interface The Province of Ontario is responsible and accountable for the service provider component. The service interface uses the SOAP protocol for communication and the SAML protocol, bound by WS-Security, for transaction security. There are several implementations of the SAML protocol available and it is suggested that one of those be used where possible. The following sections provide detailed descriptions of the SOAP message format and the expected SAML header format. SOAP Message: SOAP is an XML-based standard protocol that defines a message specification for transmitting XML documents via a network. Since this message specification does not depend on a particular programming language or operating system (OS), data transfer can be conducted among and between systems that use different languages or operating systems. The Message WSDL A WSDL is a specification for coding web services-related information (access point and interface specifications, etc.) in XML. Note that while WSDL does not define a protocol when sending/receiving messages, the ministry is using SOAP via HTTPS as the protocol for message transmission. 13

14 SAML Assertion SAML version 2.0 is used for identification, authentication and authorization of the health card validation web service. The EBS acts as a Relying Party and consumes SAML assertions provided by accredited Service Requestors. A new assertion MUST be created for each message. Time to live for the assertion will be 30 seconds. The maximum number of retries allowed will be 3. 14

15 Identity Requirements As part of the SAML assertion, the caller must assert the stock elements. SAML Assertion Table The SAML assertion includes the following standard elements: Element/Attribute MSA IDP Description Stock Elements Authentication Context Y Y A mandatory element in the authentication statement. Assertion ID Y Y A UUID prefixed with a _ (underscore) character. Audience Y Y The relying party (the service). Confirmation Method Y Y sender-vouches under MSA, bearer under IDP. Issuer Y Y Partner that issues/signs the SAML. This should be the distinguished name of the subject of the certificate used to sign the assertion. Recipient Y Y The URI of the service being called. Session index Y Y A unique identifier for this session that can distinguish among user sessions and defend e.g. against certain types of replay attacks (UUID). Session not on or after Y Y Instant at which the assertion expires. Signature Y Y Digital signature with RSA with SHA256 algorithm or on a case by case basis a suitable alternative agreed to by the ministry. Subject Y Y Identifier assigned by service requestor to end user. This is recorded for audit purposes. will provide it to the user/implementer. Y Y Conformance key assigned by ministry to software package upon successful completion of conformance test. Y N Identifier assigned by Ministry to Service Requestor. Under the MSA this is the SR Stakeholder Number. This could include an ID type as well, e.g. SN. This must be a persistent identifier for auditability. Subject Locality A mandatory element in the authentication statement. Authentication Context Y Y A mandatory element in the authentication statement. Custom Attributes urn:moh:names:idm:attribute:authmodel Y Y A descriptor for the authentication model being used. Values msa or go-secure. urn:moh:names:idm:attribute:encryptedpassword N Y An encrypted attribute that must be the password associated with the subject in the IDP s realm. urn:moh:names:idm:attribute:identityprovider N Y Is the unique identifier of the Identity Provider being used in the IDP security model. This identifier will be provided by the ministry to the Identity Provider who urn:moh:names:idm:attribute:softwareconformance-id urn:moh:names:idm:attribute:srministry-unique-id urn:moh:names:idm:attribute:suministry-unique-id Y Y Identifier assigned by Ministry to Service User typically a Claim Submission Number (CSN). This could include a value for ID type as well, e.g. CSN, SN, CPSO urn:moh:names:idm:attribute:tx-audit-id Y Y Unique identifier assigned to this assertion (UUID). 15

16 EBS: Structure of the SAML Assertion Hierarchy 1. Assertion a. Assertion ID := A UUID prefixed by a single underscore b. Issuer := The distinguished name of the party signing the assertion c. Subject i. Confirmation method := [sender-vouches bearer] 1. Confirmation Data a. Recipient := URL of service to which assertion delivered (varies by service) ii. Name ID 1. Value := End user s identity within the authentication realm 2. Format := persistent (urn:oasis:names:tc:saml:2.0:nameidformat:persistent) d. Issue instant := The date/time at which the assertion is created e. Conditions i. Audience := Service Provider s Unique Identifier ii. Not before := #Issue instant iii. Not on or after := #Issue instant plus ministry-specified duration f. Authentication Statement i. Authentication instant := #Issue instant ii. Session index := UUID iii. Session not on or after := #Not on or after iv. Subject locality := The IP address or DNS name of the system that authenticated the client v. Authentication context 1. Authentication Context Decl := [agreement password] g. Attribute Statement i. Authentication model := [msa gosecure] ii. SR audit ID := UUID iii. SU ministry UID := Service user s ministry-assigned identifier, initially CSN or SN iv. Conformance key := Unique value assigned to software upon successful completion of conformance testing v. SR Ministry UID := Service requestor s ministry-assigned identifier, initially CSN or SN vi. Identity provider := TBD vii. Encrypted attribute (Key placement := PEER) 1. Encryption Parameters a. Algorithm := AES Key encryption parameters a. Credential := EBS Encryption Certificate b. Algorithm := RSA OAEP 3. Attribute a. Attribute Name := urn:moh:names:idm:attribute:encrypted-password b. Value := End user s password in authentication realm h. Signature i. Signing credential := determined by installation ii. Algorithm := RSA with SHA256 preferred key length 2048 ( iii. Canonicalization algorithm := iv. Key info 1. Certificate := determined by installation Note: Red highlighted values are subject to change. 16

17 Authorization Process If a Service Requestor or Service User is not authorized to use the service, a SOAP Fault is returned, including a ministry specific fault code and fault string. (See Error Codes Appendix A for more details) Signing Requirements The Service Requestor, when producing the SAML assertion, must sign the assertion using a certificate issued by an issuer approved by the Ministry of Health and Long-Term Care. Audit Log data elements and format The Service Requestor is responsible for providing on demand audit information describing specific transaction or transaction sequences as identified by the ministry as circumstances dictate. The data that is logged for audit purpose should include at least: o Transaction id o Service User o End User identifier o Time / date / duration o Action / event detail o Simple success or failure o Exit status / messages o Error messages The audit information is to be provided in a comma separated text file. 17

18 Testing All software is required to conformance test with the ministry prior to receiving access to EBS. Any environment changes, including protocol or software changes, or software changes relating to the service interface to the ministry services are also subject to conformance testing. Conformance Testing is the mandatory process of testing performed by all parties that develop software that interface with EBS. This will allow MOHLTC to verify whether the software application complies with the required services Technical Specifications for communication with the ministry s systems before production access is granted. Once this process is completed successfully a software conformance id will be provided by MOHLTC. This id will then need to be sent as part of the SAML for each call to EBS. For more information contact the Service Support Contact Centre (SSCC) at: SSContactCentre.MOH@ontario.ca 18

19 APPENDIX A: Error Codes Character based error codes are returned as well as textual descriptions of the error. All ministry specific error codes are 9 characters. The following are the ministry specific error codes that may be returned within a SOAP Fault accompanied by brief explanations. Error Code EHCAU0002 EHCAU0003 EHCAU0004 EHCAU0005 EHCAU0006 EHCAU0007 EHCAU0008 EHCAU0009 EHCAU0010 EHCAU0011 EHCAU0012 EHCAU0013 EHCAU0014 EHCAU0015 SMIDL1000 SMIDL0100 Error Comment The Service Requestor is not authorized to use the service. The Service Requestor is not authorized to use the service. The Service Requestor is not authorized to use the service. The Service Requestor is not known to the ministry. The Service Requestor is not enrolled in the service. The Service Requestor is under suspension. The Software Conformance key submitted is not recognized. The Service User is not authorized to use the service. The Service Users MOH id is not valid. The Service User is a person and has an invalid status. The Service User is an organization and has an invalid status. The IDP id submitted is unknown. SAML authentication failed. Expired credentials. Password reset may be required. Web Service Unavailable Web Service Initialization Failure 19

20 Appendix B: The SOAP Message WSDL Policy Statement <wsp:policy wsu:id="ebsservice_envelopepolicy"> <sp:asymmetricbinding> <wsp:policy> <sp:initiatortoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token11 /> </sp:x509token> </sp:initiatortoken> <sp:recipienttoken> <wsp:policy> <sp:x509token sp:includetoken=" <wsp:policy> <sp:requirethumbprintreference /> <sp:wssx509v3token11 /> </sp:x509token> </sp:recipienttoken> <sp:algorithmsuite> <wsp:policy> <sp:basic256 /> <sp:basic256sha256 /> <sp:basic128 /> <sp:basic192sha256 /> <sp:basic192 /> <sp:basic128sha256 /> </sp:algorithmsuite> <sp:layout> <wsp:policy> <sp:lax /> </sp:layout> <sp:includetimestamp /> 20

21 <sp:protecttokens /> <sp:onlysignentireheadersandbody /> </sp:asymmetricbinding> <sp:signedsupportingtokens> <wsp:policy> <sp:samltoken sp:includetoken=" <wsp:policy> <sp:wsssamlv20token11 /> </sp:samltoken> </sp:signedsupportingtokens> <sp:wss11> <wsp:policy> <sp:mustsupportrefkeyidentifier /> <sp:mustsupportrefissuerserial /> <sp:mustsupportrefthumbprint /> <sp:mustsupportrefencryptedkey /> <sp:requiresignatureconfirmation /> </sp:wss11> <wsp:policy wsu:id="ebsservice_mandatoryelementspolicy"> <sp:requiredelements> <All> <sp:xpath> </sp:xpath> <sp:xpath> </sp:xpath> <sp:xpath> </sp:xpath> <sp:xpath> </sp:xpath> <ExactlyOne> <All> <sp:xpath> </sp:xpath> 21

22 <sp:xpath> </sp:xpath> </All> <All> <sp:xpath> </sp:xpath> </All> </ExactlyOne> </All> </sp:requiredelements> 22