Token specification for Energinet.dk DataHub

Transcription

1 Token specification for Energinet.dk DataHub Author: Jakob Gadegaard Bendixen, Signaturgruppen A/S Review: Peter Buus, Morten Storm Petersen, Thomas Mostrup Nymand Version: 0.4 Introduction The purpose of this document is to specify the format of the security tokens to be used when an energy consumer wants to get an overview of his energy consumption from a number of different providers. 30. marts 2012 JHH Choice of technologies The technology of choice will be SAML 2.0 assertions as specified in the OASIS SAML 2.0 specification [1]. SAML 2.0 assertions have been chosen as the token format as SAML 2.0 is the de facto standard for distributed authorization within digitalization of public services in Denmark. The alternative solutions considered was either to invent a proprietary XML format or to use the tokens provided by NemId logon. Both solutions where rejected due to their limitations. The assertions are always created on the website of the electricity supplier and there will be no need for requesting additional attributes from the electricity supplier once the signed assertion has been issued to the Datahub. Therefore the solution will not utilize the entire SAML 2.0 standard. Protocol The consumer is authenticated using his NemId. If the authentication is successful an authorization token is issued and the consumer is redirected to the Energinet.dk DataHub. The consumer is presented his consumption data. The token consists of a signed SAML 2.0 assertion containing the following attributes: - SubjectSerialNumber from the consumer's certificate - A friendly name of the consumer - A friendly name of the electricity supplier who authenticated the user. The friendly name of the consumer will be taken from the certificate Common Name (CN). In the OCES infrastructure it is possible to be anonymous in which case the certificate CN will be Pseudonym. If the authentication is done using an employee certificate (MOCES) CN is chosen by the LRA of the company in question. Although the LRA is obliged by contract to fill in the name of the employee, there is no technical mechanism to enforce this obligation. The friendly name of the provider is set by the provider himself and is not validated and should be used for presentation purposes only. The contents of the certificate fields are regulated by the OCES II specification [5]. All attributes are UTF8 strings. The SAML assertion will be signed with the VOCES certificate of the authenticating electricity supplier. The Attributes provided in the SAML assertion is the full name of the user as the provider name and the consumer subject serial number are given in the saml:issuer and saml:subject fields respectively. Doc _v1, Case 10/3365 1/6

2 An issue of consideration is the time gap given in the saml:constraint. It must be sufficiently big to allow server time skews and sufficiently small to avoid replay attacks. In order to avoid time skews the implementing parties are advised to synchronize with a timeserver such as ntp1.tele.dk. Please refer to the following assertion sample for reference. This example illustrates the minimum number of fields to be filled out. Any SAML 2.0 compliant assertion containing those fields and attributes will be accepted. The following table outlines the fields which must be present and their expected content. All other fields in the assertion will be ignored in the validation. Name Xpath Expected content Issuer /assertion/issuer Friendly name of the provider Subject /assertion/subject SubjectSerialNumber of the consumer ConsumerName AttributeStatement/Attribute[@Name= ConsumerName ]/AttributeValue Common Name of the consumer Time constraint before Time constraint after /assertion/conditions@notbefore /assertion/conditions@notonorafter Beginning of the valid period End of the valid period Signature /assertion/signature XML-Dsig signature signed with the VOCES of the provider The signature of the assertion is of type enveloped as specified in the XML-Dsig standard[6] Sample SAML 2.0 assertion <?xml version="1.0" encoding="utf-8"?> <saml:assertion xmlns:saml="urn:oasis:names:tc:saml:2.0:assertion" ID="_706381eabe57febe9a041d f41" IssueInstant=" T19:57:39.171Z" Version="2.0"> <ds:signature xmlns:ds=" <saml:issuer>dong Energy</saml:Issuer> <saml:subject> <saml:nameid Format="urn:oasis:names:tc:SAML:2.0:nameidformat:persistent"> CVR: RID: </saml:nameid> </saml:subject> <saml:conditions NotBefore=" T19:57:29.171Z" NotOnOrAfter=" T20:27:39.171Z"/> <saml:attributestatement> <saml:attribute Name="ConsumerName"> <saml:attributevalue>test Testesen</saml:AttributeValue> Doc _v1, Case 10/3365 2/6

3 </saml:attribute> </saml:attributestatement> </saml:assertion> Verification rules The verification of the token consists of the following steps. 1. Verify that the SAML assertion is valid according to the XML schema[2]. 2. Verify the contained XML signature including validation of the certificate chain 3. Verify that the assertion is valid w.r.t. the time constraints specified 4. Verify that the signing electricity supplier is trusted 5. If the consumer is a company the RID given in the SAML assertion must be authorized against the attribute service provided by DanId.[4] The validation of the XML structure is done by comparing it to the SAML 2.0 scheme as defined in The XML signature is validated w.r.t. the XML-DSig signature standard. The XML element signed is the entire assertion element, which is canonicalized using the algorithm. The certificate is validated by verifying the signature of the certification authority (CA), checking if it is still valid in terms of expiry date and by checking that it has not been revoked. The last step is done by either checking the certificate revocation list (CRL) of the CA or by performing a request to the OCSP service of the CA. This solution will be using CRL checking for revocation check. Step 3 is performed by checking the values in saml:conditions element in the assertion and comparing them to current time. Step 4 is performed by checking if the CVR number in the signing VOCES certificate is known to the database Obligations Electricity supplier obligations In order to participate the electricity suppliers must hold a valid VOCES issued by DanId and a mechanism for authenticating users using NemId. By signing the SAML assertion with their VOCES the electricity supplier guarantees that they have authenticated the user who s subject serial number is given in the saml:subject field. The electricity suppliers must not use SAML assertions issued on behalf of a user to retrieve the metering data of the user. The servers of the electricity suppliers must be reasonable synchronized. Maximum time skew is 5 minutes. Energinet.dk obligations Energinet.dk is obliged to present a consumer s metering data if and only if given a valid SAML assertion with respect to the verification rules outlined in this document. Workflow The workflow for private consumers is illustrated by the following: Doc _v1, Case 10/3365 3/6

4 1. The consumer authenticates himself at the electricity suppliers website using NemId. 2. The electricity supplier validates the NemId of the consumer and signs the DataHub token with their VOCES. 3. The consumer is presented a web page containing an iframe which refers to Energinet.dk s customer web application and the token is forwarded using a GET parameter. The token is validated with respect to rules outlined in this document and the subject serial number is mapped to the relevant installation addresses. 4. Energinet.dk s customer web application returns the relevant metering data to the consumer. The next illustration illustrates the workflow for commercial consumers Doc _v1, Case 10/3365 4/6

5 DanID NemID Attribut PID/CPR CRL Grant access 4: Check attribute Administ Web rator application Administrator Browser 5: data Token Validation Attribut Data 3: Token iframe Internet Employee 2: iframe w. token 1: NemID login Web Application NemID VOCES tool Token VOCES 1. An employee of the consuming company authenticates himself to the electricity supplier using his MOCES / commercial NemId. 2. The electricity supplier validates the NemId/Signature of the employee and signs the token using his VOCES. 3. The employee is presented a web page containing an iframe which refers to Energinet.dk s customer web application and the token is forwarded using a GET parameter. The token is validated with respect to rules outlined in this document. Energinet.dk s customer web application validates the employee s authorization against the DanId attribute service. Should this authorization fail the employee is referred to his local administrator. 4. Energinet.dk s customer web application returns the relevant metering data to the consumer. Doc _v1, Case 10/3365 5/6

6 References 1. OASIS SAML 2.0 standard 2. SAML Assertion schema: xsd 3. Contract number Attribute Service Specification 5. OCES II specification: 6. XML DSig specification: Doc _v1, Case 10/3365 6/6