The Vetuma Service of the Finnish Public Administration SAML interface specification Version: 3.5

Transcription

1 The Vetuma Service of the Finnish Public Administration SAML interface specification Version: 3.5 Vetuma Authentication and Payment

2 Table of Contents 1. Introduction The General Features of the SAML Interface of Vetuma Metadata Service entity ID Certificate used in XML signatures A service utilizing single sign-on User attributes returned upon single sign-on Single logout url Name of organization displayed on user interface Name of online service displayed on user interface Online service billing ID for transaction reporting Relaying SAML request and response messages Parameter policies Creating an XML signature XML signatures in request and response messages Vetuma SAML Single Sign-On Authentication methods Payload parameters of an authentication request Payload parameters of an authentication response Vetuma SAML Single Logout Payload parameters of a logout request Payload parameters of a logout response SAML Identity Provider Discovery in Vetuma Relaying identity provider discoveries and responses Identity provider discovery parameters Payload parameters of an identity provider response General Processing of Exceptions Exceptions detected by Vetuma Return to application in case of exceptions Test environment support for troubleshooting request errors Errors in relaying request and response messages Expiration of a Vetuma session Overlapping requests Appendices and References Appendices References Copyright Fujitsu Finland Oy 2 (25)

3 1. INTRODUCTION The Vetuma service is citizens online authentication and payment service designed for the e- services of public administration organizations. Fujitsu Finland Oy, as the service provider, will implement the Vetuma service to be utilized by different organizations of the government and municipalities. The functionality of the Vetuma service is described in a separate document titled The Vetuma Service of the Finnish Public Administration Description of the functionality offered to applications. In addition to the functionality of applications, the Vetuma service package includes, for example, functions relating to user management, billing and reporting. However, the above-mentioned description document only gives an outline of the application functionality. Applications have access to functionality offered by Vetuma through Vetuma s own interface, which is specified in the document titled The Vetuma Service of the Finnish Public Administration Interface Specification. Moreover, applications have access to Vetuma s authentication functions coupled with the SAML single sign-on through the SAML interface specified in this document. This document describes the SAML interface of Vetuma version 3.4. It complements and outlines the functions of the Vetuma service as an addition to the actual SAML 2.0 specification. The message format, XML signatures and verifications shall be based on the SAML 2.0 specifications. The SAML interface of Vetuma is designed to be compatible with Public Administration s SAML 2.0 protocol deployment and attribute profiles, reference [FinnishSAML2Profile]. The SAML interface can be used for authentication only. The payment service, signature service and confirmation service are available only through Vetuma s own interface. The SAML interface of Vetuma offers the single sign-on functionality to Vetuma between the services connected to Vetuma using the SAML interface. In version 3.3, the service was complemented with SAML identity provider query. Version 3.4 added support on HTTP Redirect binding and updated support on the current interfaces of banks. Version 3.4 supports SAML 2.0 protocol deployment profile for Finnish Public Sector. Authentication responses uses RSAwithSHA256 algorithm for XML-signatures, and specified value for strong authentication methods. Version 3.5 does not contain changes to the SAML interface. 2. THE GENERAL FEATURES OF THE SAML INTERFACE OF VETUMA This chapter describes the general features of the SAML interface provided in the Vetuma service: relaying of request and response messages, parameter policies, and XML signatures of messages. The Vetuma SAML interface offers user authentication to e-service applications, employing the strong methods of authentication of the Vetuma interface. Online services using Vetuma authentication are always offered Tupas, the methods based on a citizen certificate and mobile certificate. These functions are described in the document titled Suomalaisen julkishallinnon Vetuma-palvelu, sovelluksille tarjotun toiminnallisuuden kuvaus. This chapter describes the requests and responses and parameters of these functions through the SAML interface. Copyright Fujitsu Finland Oy 3 (25)

4 2.1 Metadata Upon joining the SAML interface of Vetuma, e-service applications shall deliver a metadata file describing the SAML interface of their own service. The metadata file shall follow the SAML 2.0 specifications. Instructions on the file requirements will be delivered upon joining. This document outlines all the required information, while a more detailed description with examples can be found in a separate document titled Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto.pdf Service entity ID The service entity ID is a unique ID for the SAML service of an e-service application. The ID is the value of the entityid attribute in the metadata file describing the SAML interface. The ID in question will be issued in the <Issuer> element of an authentication request to refer to the configuration data (metadata) of the online service Certificate used in XML signatures The KeyDescriptor element of metadata determines the public key certificate with the corresponding private key of which the online service will sign the message it sends to Vetuma. Vetuma requires that all metadata files come with a certificate in the X509Certificate element. In the Vetuma metadata file, multiple certificates can be simultaneously defined for one online service. As needed, the online service can deliver to Vetuma temporary metadata containing several certificates. The format has been defined in the SAML standard (section of metadata specification). More specific requirements for metadata can be found in the document titled Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto A service utilizing single sign-on The return url s, indexes and used SAML protocols of a service utilizing single sign-on are defined in metadata. The index can be used in an SAML protocol message to select a certain return url. When using Vetuma version 3.4 or later, the value of the used protocol must at all times be as follows: urn:oasis:names:tc:saml:2.0:bindings:http-post User attributes returned upon single sign-on The services and requested user attributes utilizing the attributes returned upon authentication can be specified in the metadata. The index can be used in a SAML protocol message to select a certain set of attributes. Available attributes are defined in section Payload parameters of an authentication response Single logout url The return url and SAML protocol of the service using single logout are defined in the metadata. The return url describes the url to which Vetuma, upon single logout, sends the service-related logout requests or logout responses. When using Vetuma version 3.4 or later, the value of the used protocol shall be as follows: urn:oasis:names:tc:saml:2.0:bindings:http- Redirect or urn:oasis:names:tc:saml:2.0:bindings:http-post Name of organization displayed on user interface Upon delivering metadata, the name of the organization shall be saved in the Vetuma service. The organization s name can be given in all the languages that Vetuma supports. Vetuma will use the language selected for the user interface on the authentication request. Copyright Fujitsu Finland Oy 4 (25)

5 2.1.7 Name of online service displayed on user interface The name of the online service can be given in metadata in all the languages that Vetuma supports. Vetuma will use the language version of the name selected for the user interface on the authentication request. If the value configured in metadata is too long to fit in the Vetuma user interface, it will be cut to the length allowed in Vetuma. A more detailed description can be found in a separate metadata document. If the name of the online service is not wished to be displayed in the user interface, this information will be omitted from the online service metadata. As a distinction to Vetuma s own user interface, there the name of the online service is given in parameter APPNAME Online service billing ID for transaction reporting A billing ID can be given in metadata for transaction reporting purposes. If the value configured in the metadata is too long to fit in the Vetuma user interface, it will be cut to the length allowed in Vetuma. A more detailed description can be found in a separate metadata document. If billing ID is not intended to be included in a transaction report, this item will be omitted from the online service metadata. As a distinction to the Vetuma service s own user interface, there the billing ID is given with authentication request parameter APPID. 2.2 Relaying SAML request and response messages The SAML interface of Vetuma is a message interface where messages are implemented using the Redirect and POST commands of the HTTP protocol. The same mechanism is used in Vetuma s own interface also. The employed protocol is SAML 2.0 compliant HTTP POST Binding or HTTP Redirect Binding Reference 4 [SAMLBind]. When an e-service application calls the Vetuma service, it sends via the user s browser a POST command to the service where SAML request and session ID are given as HTML form fields. In the HTTP Redirect Binding protocol, HTTP GET request is in use. See reference 4 for further details. In accordance with the SAML protocol, the application can define a return url to Vetuma in an SAML request either in the AssertionConsumerServiceIndex or AssertionConsumerServiceURL attribute. If no url is given in the request, the default url of the application from the metadata file will be used. Vetuma returns a response to the return url in the following situations: function successful, function cancelled by user, or error. When Vetuma returns a response to the e-service application that called it, it will send to it through the user s browser a POST command in which an SAML response and session ID as HTML form fields has been issued from Vetuma to the application. The confidentiality of messaging (protecting the content of messages against disclosure) is based on encrypting the used connections with the SSL/TLS protocols, that is, request and response messages are sent over HTTPS connections. Before the application returns to the user s browser an HTTP response with which a Vetuma request will be sent from the browser to Vetuma, the application shall make sure that there is an HTTPS connection between it and the user. The request url to Vetuma (which must be given in the action element of the form containing a Vetuma SAML request) begins with that is, the POST command will be sent to Vetuma over an HTTPS connection. Copyright Fujitsu Finland Oy 5 (25)

6 When Vetuma returns to the browser an HTTP response with which a Vetuma response will be sent from the browser to the application, this will take place over an HTTPS connection. The return urls given in Vetuma requests and metadata shall begin with for them to bring about an HTTPS connection for sending a POST command with a response from the browser to the application. In case of a request, Vetuma will verify that this is the case, and if it is not, it will reject the request and return the metadata file to a default url for invalid requests. (SAML status code Requester). The response contains a message describing the reason as to why the given url was invalid. The integrity of the exchanged messages and the authentication of the sender are verified using XML signatures. Vetuma accepts the following CA s as service provider certificates: VRK, VeriSign, Thawte and Symantec. The recipient of the messages shall verify the signatures included in the message and reject the message if the signatures do not match. If it so wishes, the application may assign a transaction ID to the Vetuma request, which the Vetuma service will return upon responding to said request. The purpose of a transaction code is to facilitate combining the request and response messages of a certain transaction. The application shall verify the integrity of the transaction ID by using a checksum, for example. The maximum length of a transaction ID is 80 bytes. Transaction ID is sent on the form in the field named RelayState. The e-service application may send a request to Vetuma through the user s browser, for example, by returning an HTML page to the browser with:... An HTML form with Vetuma SAML request parameters as prefilled hidden fields that are not displayed to the user. <form name= VETUMA method= POST action= > <input type= hidden name= SAMLRequest value= xdsdd... > <input type= hidden name= RelayState value= >... </form>... An automatically run script that sends the form to Vetuma, for example: var form = document.vetuma; form.submit(); A manual submit function on the form for switching to Vetuma, if running scripts is disabled in the browser, for example: <INPUT type="submit" value="siirry Vetuma-palveluun tunnistautumaan"> When Vetuma processes an authentication request received from an application, authentication may be successful or for different reasons not be performed. In its SAML authentication response, Vetuma returns information on whether the authentication was successful or for some reason not performed. Copyright Fujitsu Finland Oy 6 (25)

7 2.3 Parameter policies An authentication request sent to Vetuma via the SAML interface will be given in a SAML standard compliant authentication request (<AuthnRequest>). Majority of the control data of the authentication transaction will be determined in the configuration of the online service, which will be referred to in the authentication request. The online service can still in the authentication request determine the language Vetuma shall use in its authentication user interface. Besides the identity of an authenticated user, the application utilizing Vetuma authentication receives upon authentication certain details of the user and the actual authentication transaction: for example, the user s name, social security number from VTJ, or basic details based on a configured VTJ query product, and information on the used method of authentication. Vetumaspecific additional details on the authenticated person and the authentication transaction will be given in the appropriate elements of the SAML authentication response (<Response>) and the assertions (<Assertion>) it contains. Relaying Vetuma-specific payload information in SAML standard compliant authentication requests and responses is described later on in this document. UTF-8 symbols are used in the Vetuma SAML interface. For the application this means, among other things, that only UTF-8 symbols may appear in the parameter values of the Vetuma requests. 2.4 Creating an XML signature The XML signatures of the SAML messages used in Vetuma are created in accordance with the [SAML 2.0 standard], using RSAwithSHA256 as signature algorithm. Earlier RSAwithSHA1algorithm is also supported. Vetuma supports the following options to the XML signature standard: Digest SHA256 SHA1 Signature RSAwithSHA256 RSAwithSHA1 XML Canonicalization Transform KeyInfo Exclusive Canonicalization (with or without comments) Enveloped Signature <ds:keyinfo><ds:x509data><ds:x509certificate> Table 1: Summary of the options to the XML signature standard supported by Vetuma. The e-service application calling Vetuma shall form an XML signature to the request message in accordance with the SAML 2.0 standard. Vetuma forms the XML signature of the response message in the same manner. The e-service application calling Vetuma shall check the signatures it receives. The certificates used by the service providers in XML signatures will be registered upon joining the service. Vetuma accepts the following CA s as the service providers certificates: VRK, VeriSign, Thawte and Symantec. Note that new certificates should use updated algorithms related to deprecation of SHA-1 and the transition to SHA-256. Copyright Fujitsu Finland Oy 7 (25)

8 2.5 XML signatures in request and response messages All the SAML request and response messages used in Vetuma come with an XML signature or a signature. The recipient shall check the signature and make sure that it signs the root element of every message in accordance with the SAML 2.0 specification. In case of an authentication response (<Response>) also the signature of the assertion (<Assertion>) that is returned with the message shall be checked. Appendix 3 contains the SAML sample messages with the messages that contain signatures. 3. VETUMA SAML SINGLE SIGN-ON Vetuma single sign-on means that the single sign-on capability is available via an SAML interface between the service providers who have joined the Vetuma service. Single sign-on is implemented using SAML single sign-on profile Web Browser SSO Profile. Vetuma s SAML authentication request and SAML authentication responses are used in single sign-on. The table below presents a summary of the requests/responses specified for the Web Browser SSO Profile standard that are supported in Vetuma version 3.5. Profile Messages Binding Version 3.5 Web SSO Receiving <AuthnRequest> message HTTP redirect HTTP POST Supported Supported HTTP artifact Not supported Sending <Response> message HTTP POST Supported HTTP artifact Not supported Table 2: A summary of the Web Browser SSO Profile messages and bindings supported by Vetuma For an online service calling Vetuma, single sign-on means that the service seen by the user in Vetuma varies depending on whether the user has already, on the same browser, authenticated in Vetuma and arrived there through such an online service which called Vetuma in the SAML interface. If it is and the session is still valid, the user will not have to re-authenticate. The maximum duration of a single sign-on session from the last time the user joined in a session is 30 minutes. Upon first authentication, the user s social security number and name will be disclosed. These details will be saved in the single sign-on session for the following online services. Other online services that join the session next will receive these details without the user having to reauthenticate. 3.1 Authentication methods Vetuma offers a set of alternative methods to authenticate a user. These authentication methods are described in the document titled Suomalaisen julkishallinnon Vetuma-palvelu, sovelluksille tarjotun toiminnallisuuden kuvaus. The ID s of the methods and the user ID data type returned with each authentication method are listed in the table below. In all the authentication methods, the application also receives the user s HETU as an ID. Copyright Fujitsu Finland Oy 8 (25)

9 Method AuthnContextClassRef Data type used in establishing the user s identity Strong authentication as specified (Act on strong electronic authentication and signature, /617) Chip card based citizen certificate authentication (HST authentication) SIM card based mobile certificate authentication (ETSI) /vip/authncontext/strong /vip/authncontext/strong Tupas identification /vip/authncontext/strong SATU HETU HETU Table 3: Methods supported by Vetuma The banks used by Vetuma are listed in the Vetuma interface specification document. Examples of returning the selected authentication method in a response: (Authentication was conducted using a strong authentication method) 3.2 Payload parameters of an authentication request The structure of an SAML authentication request (<AuthnRequest>) is defined in the [SAML 2.0 standard]. This chapter describes how the SAML authentication request can be used to control Vetuma in executing an authentication transaction. When requesting authentication via Vetuma s SAML interface, the following payload details shall be given in the SAML authentication request (<AuthnRequest>). It is indicated in column R whether the parameter is required or optional. Information R Corresponding information in the old interface Timestamp of request r TIMESTMP User interface language o LG Return url o RETURL CANURL ERRURL Transaction ID o TRID Table 4: The payload parameters of a Vetuma SAML authentication request Copyright Fujitsu Finland Oy 9 (25)

10 Service entity ID Meaning in authentication request: ID of the online service calling Vetuma, as a reference to the configuration data of the online service in Vetuma. This value must be same than the value of the entityid attribute in the Service Provider metadata file. Location in authentication request: The <saml:issuer> value of the <AuthnRequest> element. Format: URL syntax based character string of max characters. Type: Required Example: Corresponding information in the old interface APPID Timestamp of request Meaning in authentication request: Defines the moment the request was created. Location in authentication request: Attribute IssueInstant of the <AuthnRequest> element Format: Character string of 24 characters. Of type xs:datetime W3C XML Schema, compliant with the data type specification [Schema2] Type: Required In the UTC format without time zone Example: T12:44:47.693Z Corresponding information in the old interface TIMESTMP User interface language Meaning in authentication request: The language of the user interface opened to the user. When calling the Vetuma service, the application may determine which supported language the Vetuma user interface shall use. This applies to the browser user interface. Vetuma offers a user interface in Finnish, Swedish and English. Vetuma aims to relay the language selection to the requested support services as well. In some cases, however, Vetuma cannot influence the user interface language used by the requested support service, for example: o o In the online services of certain banks, language is determined in the online service agreement between the citizen and the bank. Some SIM cards containing a mobile certificate do not support language choice, or they do not support all the languages supported in the Vetuma service. Location in authentication request: The <LG> value of the <samlp:extensions> element s <vetuma xmlns="urn:vetuma:saml:2.0:extensions"> element Format: A character string of 2 characters Type: Optional ISO 639-1standard compliant lower case 2-character language code. That is, either fi, sv or en Copyright Fujitsu Finland Oy 10 (25)

11 Example: fi Example of usage: <samlp:extensions><vetuma xmlns="urn:vetuma:saml:2.0:extensions"><lg>fi</lg></vetuma></sam lp:extensions> Return address Meaning in authentication request: The return url to the application after the processing of an authentication request. Location in authentication request: Attribute AssertionConsumerServiceURL of the <AuthnRequest> element, or a reference to the Metadata file url with attribute AssertionConsumerServiceIndex. Format: AssertionConsumerServiceURL: Of type xs:anyuri W3C XML Schema in compliance with the data type specification [Schema2] AssertionConsumerServiceIndex: Index referring to the AssertionConsumerService element of the metadata file. AssertionConsumerServiceURL s domain must match to the one in metadata. Type: Optional Example: AssertionConsumerServiceURL= or AssertionConsumerServiceIndex= 1 Transaction ID Meaning in authentication request: Enables the application calling Vetuma to store status information and get it back in a response. Location in authentication request: A separate RelayState field on a form containing an authentication request. Format: Max 80 bytes If the calling application uses a transaction ID, it shall ensure the integrity of the field by using a suitable checksum, for example. Type: Optional 3.3 Payload parameters of an authentication response The structure and usage of an SAML response (<Response>) in authentication responses is defined in the [SAML 2.0 standard]. The standard in question also defines the structure of the assertions (<Assertion>) returned in the authentication responses. This chapter describes how Vetuma returns the payload information characteristic to it on an authentication request and on the authenticated person. Vetuma returns the following details on the authenticated person and the authentication transaction in an SAML interface authentication response (<Response>): Copyright Fujitsu Finland Oy 11 (25)

12 Information R Corresponding information in the old interface Timestamp of response r TIMESTMP Authentication method r SO Transaction ID o TRID Identity r USERID, SUBJECTDATA, VTJDATA, EXTRADATA Provider of authentication service r SO Return status r STATUS Table 5:The payload parameters of a Vetuma SAML authentication response Timestamp of response Meaning in authentication response: Defines the moment the response was created. Location in authentication response: Attribute IssueInstant in the <Response> element Format: Character string of 24 characters. Of type xs:datetime W3C XML Schema, compliant with the data type specification [Schema2] In the UTC format without time zone Example: T12:50:47.693Z Authentication method Meaning in authentication response: The method of authentication with which the user authenticated. Location in authentication response: <saml:authnstatement>-elementin <saml:authncontext>-elementin elementti <saml:authncontextclassref> Format: The authentication method codes presented in section 3.1are used in an XML structure. The authentication method codes used in Vetuma are described in further detail in chapter Authentication methods of this document. Examples: <saml:authncontextclassref>urn:oasis:names:tc:saml:2.0:ac:classes:mobiletwofactorcont ract</saml:authncontextclassref> (Authentication was conducted using a chip card with a citizen certificate.) <saml:authncontextclassref> urn:oasis:names:tc:saml:2.0:ac:classes:textbasedchallengeresponse </saml:authncontextclassref> (Authentication was conducted using the Tupas method.) Transaction ID Meaning in authentication response: Enables the application calling Vetuma to store status information and get it back in a response. Location in authentication response: A separate RelayState field on a form containing an authentication response. Copyright Fujitsu Finland Oy 12 (25)

13 Format: Max 80 bytes Identity An identity ID, transient ID, is always returned as an identifier created by Vetuma for a session. In addition, the details that can be returned will be returned in an assertion (depending on the authentication method): Identity ID SATU (if authenticated using a method based on a citizen certificate) HETU (a VTJ search will be conducted, if authenticated on a method based on a citizen certificate) VTJDATA (basic user details based on VTJ query product, if the user authenticated, and a query product was configured and enabled) Name from the identity provider Meaning in response: An identity ID created by Vetuma for the session with which to log off. Location in authentication response The value <saml:nameid> of the <Response> element Format: Character string of max characters. Tyyppi: Required Example: <saml:nameid Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient">_adc07330da05-da9a2bf5-be98-47ca bba7f c23c3c88609c</saml:NameID> SATU Meaning in response: An electronic identification number of a used citizen certificate. Location in authentication response: In attribute, whose OID identifierentifier is , that is, in an <Attribute> element titled <AttributeStatement>-elementin urn:oid: Format: A character string following the SATU syntax on the syntax of the <Attribute>element. Copyright Fujitsu Finland Oy 13 (25)

14 Example: <saml:attribute FriendlyName="electronicIdentificationNumber" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue> c</saml:attributevalue> </saml:attribute> HETU Meaning in authentication response: The social security number (HETU) of an authenticated user, however: Not included in the response, if chosen method was based on a citizen certificate, and the VTJ query is not enabled. An error code returned by VTJ, if the query failed. Location in authentication response: In an attribute whose OID identifierentifier is , that is, in the <Attribute> element of an <AttributeStatement> element titled urn:oid: Format: A HETU syntax compliant character string, on the syntax of the <Attribute> element. Example: <saml:attribute FriendlyName="nationalIdentificationNumber" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue> n</saml:attributevalue> </saml:attribute> VTJDATA Meaning in authentication response: Basic user details in accordance with the VTJ query product of an authenticated user (VTJDATA), however: Included, if VTJ query product is configured and enabled, and the user authenticated Not included in response, if the user used a single sign-on session or VTJ query is not enabled An error code returned by VTJ if query failed Location in authentication response: In attribute titled urn:vetuma:saml:2.0:attributes:vtjdata, that is, in the <Attribute> element titled urn:vetuma:saml:2.0:attributes:vtjdata of the <AttributeStatement> element. Format: Character string of max characters, using the syntax of the <Attribute> element. Format is the same XML format as in the responses to the VTJ SoSo queries. However, in the return message of Vetuma, the XML data is URL coded. The response data of the VTJ query products containing a certain data permit is defined in connection with the data permit, and the exact format of the response of each product is described as an XML Schema specification. VRK has also released an XML Schema, defining the data types of VTJ data that appear in the XML schemas of the responses. Example: Further details on the VTJDATA parameter value can be found in the document titled Vetuma Sanomaesimerkit. Copyright Fujitsu Finland Oy 14 (25)

15 Subject data from identity provider Meaning in authentication response: The user s name received from an identity provider ( if available). In different authentication methods, subject data is derived from different providers: Authentication method Authentication methods based on a citizen certificate Tupas Mobile certificate Provider of name details Subject data in the Subject field of a certificate of an authenticated user. Client name in the bank s customer database. Subject data in the Subject field of a certificate of an authenticated user Table 6: Provider of subject data in different method types Location in authentication response: In attribute whose OID identifier is , that is, in the <Atribute element titled urn:oid: of the <AttributeStatement> element Format: The person s entire name in accordance with JHS 133. Examples: <saml:attribute FriendlyName="cn" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue>aallontie Armas Oskari</saml:AttributeValue> </saml:attribute> <saml:attribute FriendlyName="cn" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue>sinisalo-koskinen Maija</saml:AttributeValue> </saml:attribute> Authentication service provider Meaning in authentication response: URI, which identifies the provider of the used authentication service. Location in authentication response: In attribute whose OID identifier is , that is, the <Attribute> element titled urn:oid: of the <AttributeStatement> element Format: URI. Example: <saml:attribute FriendlyName="authenticationProvider" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrnameformat:uri"> <saml:attributevalue> </saml:attribute> Return status Meaning in authentication response: How authentication succeeded. In Vetuma s processing of an authentication request from an application, authentication may be successful or for some reason not be performed. In its SAML authentication response, Vetuma returns the Copyright Fujitsu Finland Oy 15 (25)

16 <StatusCode> element to report whether the authentication was success or for some reason not performed. Location in authentication response: The <Status> element of the <Response> element. Format: Vetuma may return the following return statuses in the <StatusCode> element of the <Status> element, which in the SAML 2.0 standard are specified in the name space urn:oasis:names:tc:saml:2.0:status: Status code defined in the SAML 2.0 standard Higher level status codes: Authentication status Corresponding return status in Vetuma s old interface Success Successful authentication SUCCESSFUL Requester Invalid request ERROR Responder Request processing failed FAILURE VersionMismatch Invalid version in request ERROR Complementary status codes: AuthnFailed Authentication failed CANCELLED, FAILURE RequestDenied Identity provider rejected authentication REJECTED Table 7: Return statuses returned by Vetuma The status element may include the <StatusMessage> element, providing further details on the error situation. 4. VETUMA SAML SINGLE LOGOUT An application using the Vetuma service with the SAML interface shall support the SAML Single Logout Profile via HTTP POST Binding. In terms of functionalities, required are both Vetuma logout (the service shall offer the user the opportunity to log out) and the processing of logout requests from Vetuma, and responding to them. Below there is a summary of the requests/responses and bindings supported in the standard specified for the Single Logout Profile in Vetuma version 3.5. Profile Messages Binding Version 3.5 Single Logout Sending and receiving a <LogoutRequest> message HTTP redirect HTTP POST Supported Supported HTTP artifact Not supported SOAP Not supported Sending and receiving a HTTP redirect Supported Copyright Fujitsu Finland Oy 16 (25)

17 <LogoutResponse> message HTTP POST HTTP artifact SOAP Supported Not supported Not supported Table 8: A summary of the Single Logout Profile messages and bindings supported by Vetuma. 4.1 Payload parameters of a logout request The structure of the SAML logout request (<LogoutRequest>) is defined in the [SAML 2.0 standard]. This chapter describes how, using an SAML logout request, Vetuma can be controlled in performing a logout. When requesting a logout via the SAML interface of Vetuma, the following payload details controlling the logout shall be given an SAML logout request (<LogoutRequest>). The logout request sent by Vetuma follows the same structure. Column R indicates whether the parameter is required (r) or optional (o). Information Timestamp of request Name ID User interface language Transaction ID R r r o o Table 9: The payload parameters of Vetuma SAML logout request Service entity ID Meaning in logout request: The ID of the online service calling Vetuma, as a reference to the configuration data of the online service in Vetuma. Location in logout request: The value of element <saml:issuer> of element <LogoutRequest> Format: URL syntax compliant character string maximum length 1024 characters. Type: Required Example: Timestamp of request Meaning in logout request: Defines the moment the request was created. Location in logout request: Attribute IssueInstant of element <LogoutRequest> Format: A character string, 24 characters. Of type xs:datetime W3C XML Schema, compliant with the data type specification [Schema2] Type: Required In the UTC format without time zone Example: T12:44:47.693Z Copyright Fujitsu Finland Oy 17 (25)

18 Name ID Meaning in logout request: Name ID returned by Vetuma in the authentication response in a certain single sign-on session (transient ID). Location in logout request: The value of element <saml:nameid> of element <LogoutRequest> Format: A character string of max characters. Type: Required Example: <saml:nameid Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient">_adc07330da05-da9a2bf5-be98-47ca bba7f c23c3c88609c</saml:NameID> User interface language Meaning in logout request: The language of the logout user interface opened to the user. When calling Vetuma, the application may determine which of the supported languages the Vetuma user interface shall use. This applies to the browser user interface. Vetuma offers a user interface in Finnish, Swedish and English. Vetuma aims to relay the language selection to the requested supporting services as well. In some cases, however, Vetuma cannot influence the user interface language used by the requested supporting service. Location in logout request: The <LG> value of the <samlp:extensions> element s <vetuma xmlns="urn:vetuma:saml:2.0:extensions"> element Format: Character string, 2 characters Type: Optional Example: fi ISO standard compliant 2-letter language code in lower case. That is, either fi, sv or en Example of usage: <samlp:extensions><vetuma xmlns="urn:vetuma:saml:2.0:extensions"><lg>fi</lg></vetuma></sam lp:extensions> Transaction ID Meaning in logout request: Allows an application calling Vetuma to keep status information and get it back in a response. Location in logout request: A separate RelayState field on a form containing a logout request. Format: Max 80 bytes If the calling application uses a transaction ID, it must ensure the integrity of the field by using a suitable checksum, for example. Type: Optional Copyright Fujitsu Finland Oy 18 (25)

19 4.2 Payload parameters of a logout response The structure of an SAML logout response (<LogoutResponse>) and how it is used in logout responses is defined in the [SAML 2.0 standard]. This chapter describes how Vetuma returns the payload information characteristic to it on a logout transaction. When responding to a logout request via Vetuma s SAML interface, the following payload details on the logout transaction shall be returned in the logout response (<LogoutResponse>). The logout request Vetuma sends follows the same structure. Information Timestamp of response Transaction ID Return status R r o r Table 10: The payload parameters of Vetuma s SAML logout response. Service entity ID Meaning in logout request: The ID of the online service calling Vetuma, as a reference to the configuration data of the online service in Vetuma. Location in logout request: The <saml:issuer> value of element <LogoutResponse>. Format: URL syntax compliant character string of max characters. Type: Required Example: Timestamp of response Meaning in logout response: Defines the moment the response was created. Location in logout response: Attribute IssueInstant of the <LogoutResponse> element Format: Character string, 24 characters. Of type xs:datetime W3C XML Schema compliant with the data type specification [Schema2] In the UTC format without time zone Example: T12:50:47.693Z Transaction ID Meaning in logout response: Allows an application calling Vetuma to keep status information and get it back in a response. Location in logout response: A separate RelayState field on a form containing a logout request Format: Max. 80 bytes Copyright Fujitsu Finland Oy 19 (25)

20 Return status Meaning in logout response: Logout status. In Vetuma s processing of a logout request from an application, logout may be successful or for some reason not be performed. In its SAML logout response, Vetuma returns the <StatusCode> element to report whether the logout was success or for some reason not performed. Location in logout response: The <Status> element of the <LogoutResponse> element. Format: Vetuma may return the following return statuses in the <StatusCode> element of the <Status> element, which in the SAML 2.0 standard are specified in the name space urn:oasis:names:tc:saml:2.0:status: Status code defined in the SAML 2.0 standard Upper level status codes: Success Requester Responder VersionMismatch Logout status Successful logout Invalid request Request processing failed Invalid version in request Complementary status codes: PartialLogout RequestDenied Logout failed The called service rejected the logout request Table 11: Return statuses returned by Vetuma The status element may include an optional <StatusMessage> element, for providing a more specific status code, and an optional <StatusDetail> element to give specific details of the error situation. 5. SAML IDENTITY PROVIDER DISCOVERY IN VETUMA A Vetuma identity provider discovery means that an active identity provider is requested for Vetuma via the SAML interface. An identity provider query is implemented using the SAML specification profile Identity Provider Discovery Service Protocol and Profile. [SAMLDisco] For an online service calling Vetuma, an identity provider discovery means that the service can find out whether the user has valid information on using the Vetuma authentication service before authenticating its user with the Vetuma-offered SAML standard compliant authentication. This allows the offering of services where the service displayed to the user varies depending on whether the user has already, on the same browser, authenticated in Vetuma and arrived there via such an online service that called Vetuma in the SAML interface. By focusing single sign-on to authenticated users and avoiding unnecessary authentication queries when it is unlikely that there is a session, it is possible to add more versatile content on the front pages of the services for the authenticated users. Copyright Fujitsu Finland Oy 20 (25)

21 5.1 Relaying identity provider discoveries and responses The relaying of an SAML identity provider request and response message is implemented as HTTP GET requests, that is, the user s browser is taken to a created url, which calls Vetuma in accordance with the specification. Correspondingly, the response message will be relayed to a return url created using the user s browser. 5.2 Identity provider discovery parameters The structure of the SAML identity provider discovery (HTTP GET) is defined in the [SAMLDisco standard]. This chapter describes how a discovery can be used to direct Vetuma in executing a discovery transaction. When sending a discovery via Vetuma s SAML interface, the following payload details shall be given in the request to control the authentication. Column R indicates whether the parameter is required (r) or optional (o). Detail R Name of parameter Service entity ID r entityid Return url o return Policy o policy Return parameter o returnidparam Passive processing o ispassive Table 12: The payload parameters of Vetuma SAML identity provider discovery Service entity ID Meaning in identity provider discovery: The ID of the online service calling Vetuma, as a reference to the configuration data of the online service in Vetuma. Format: URL syntax compliant character string, URL encoded, max characters. Type: Required Example: https%3a%2f%2fwww.example.org%2fapp1 Return url Meaning in identity provider discovery: Return url to the application after the processing of an identity provider discovery. Format: URL syntax compliant character string, URL encoded, max characters. Must not contain the returnidparam value, or when it is missing, the value entityid. Type: Optional Example: https%3a%2f%2fwww.example.org%2fapp1 Policy Meaning in identity provider discovery: The policy that determines the manner in which identity provider discoveries are implemented in the service. For now, only the default value is in use, so this parameter is unnecessary. Copyright Fujitsu Finland Oy 21 (25)

22 Format: URI syntax compliant character string. When the value is missing, the default value is "urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single. Type: Optional Example: urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single Return parameter Meaning in identity provider discovery: Allows the application calling Vetuma to assign a name to a returning attribute in which the authentication service entity ID received as a result of the query shall be given. If this value is not given, the default value entityid shall be used. Format: Max. 80 characters. Type: Optional Passive processing Meaning in identity provider discovery: Allowing the application calling Vetuma to indicate whether the user can be invited to operate in the user interface when discovering the identity provider. If this value is not given, the value false will be used by default. Format: Boolean. Type: Optional 5.3 Payload parameters of an identity provider response Creates a SAML standard compliant URL with parameters and complement it with information on the user s authentication service entity ID, if an identity provider was used. The return url shall be formed based on the value of the return parameter of the identity provider request. If an identity provider was not used or the discovery failed, the return will take place without a parameter containing an authentication service entity ID. The structure of the SAML identity provider response URL and its usage in the authentication responses is defined in the SAML 2.0 standard [SAMLDisco]. Vetuma returns the following details of the identity provider response (HTTP GET) on the identity provider transaction in the SAML interface: Information R Name of parameter Authentication service entity ID o entityid or the attribute value of request returnidparam Table 13: The payload parameters of the Vetuma SAML identity provider response Authentication service entity ID Meaning in identity provider response: The id of the authentication online service, if the identity provider discovery was successful. Format: URL syntax compliant character string, URL-encoded, max. length 1024 characters. Type: Optional Example: https%3a%2f%2ftunnistus.suomi.fi%2fvetumasso%2fapp Copyright Fujitsu Finland Oy 22 (25)

23 6. GENERAL PROCESSING OF EXCEPTIONS When processing a request received from an application, Vetuma may detect a variety of exceptions due to which the function requested in the request will not be executed. This chapter describes the processing of such exceptions. Also, in relaying request and response message there may occur such errors that cannot be detected by the e-service application, Vetuma or the supporting service called by Vetuma. Nevertheless, the developers of e-service applications must still be aware of this possibility. 6.1 Exceptions detected by Vetuma The following service-detected errors may occur in Vetuma: The request sent by an application is invalid either syntactically, according to message signature verification, or based on invalid parameter values. An example of the latter is a syntactically valid client ID which does not, however, refer to any client registered to Vetuma. The supporting service called by Vetuma rejects executing the function and returns information on this to Vetuma, for example, an online banking service rejects user authentication. Vetuma cannot, for some other reason, fulfil the request, for example: o o o There is some technical problem in the operational environment, for example, a request to a supporting service required in fulfilling the request cannot be sent. The requested support service does not respond. An error occurs in executing the function requested in the request, for example, the user fails to authenticate with a mobile certificate within the limit of the allowed attempts An end-user of the Vetuma service cancels the authentication. This may happen in the following ways: o o The user aborts or cancels a function in the Vetuma user interface. The user aborts or cancels a function in an identity provider called by Vetuma, and the identity provider (in an online banking service, for example) returns information on the cancellation to the Vetuma service Return to application in case of exceptions In all the exceptions detected by the Vetuma service, Vetuma returns in an authentication response it sends to the return url given in the request information on whether the authentication was successful or failed, if returning is possible Test environment support for troubleshooting request errors The test environment for the Vetuma service supports the testing of SAML authentication requests in a way that when detecting an invalid request, it will open to the user s (test engineer s) browser a user interface showing why the request is invalid (for example, a formal error or an invalid parameter value). In the production environment, this type of error messages will not be displayed, in other words, end-users will never be bothered with them. Copyright Fujitsu Finland Oy 23 (25)

24 6.2 Errors in relaying request and response messages Requests from e-service applications to the Vetuma service and responses from Vetuma to e- service applications are relayed via the user s workstation. Also requests from Vetuma to such interactive identity providers to which the user is transferred from Vetuma (such as online banking services), and responses from said services to Vetuma are relayed via the user s workstation. Relaying requests and responses via browser may fail, for example, if the user closes the browser, the workstation crashes or the connection from the sending or responding server to the workstation is lost. In this case, the intended recipient of the request or response message will not get the message, and neither will the sender (who delivered the message as an HTTP response to the browser) will not be informed of the failed relay Expiration of a Vetuma session A Vetuma session will be created for the user when he/she switches from the user interface of the e-service application to the Vetuma user interface. A Vetuma session may end in expiration for the following reasons: The user fails to enter the input Vetuma expects within within 30 minutes from requesting an input. Vetuma does not receive a response from the interactive identity provider it called within 30 minutes from sending the request. After a Vetuma session is terminated due to expiration, the e-service application will not get any response from Vetuma, but it has to prepare for detecting the expiration. If the user s browser still tries to send an HTTP request to Vetuma after the termination of the session: Overlapping requests The HTTP request in question will not be served, because the session no longer exists. A generic (independent of the e-service application) notification will be displayed to the user on the expiration of the session. Information on a rejected request will be saved to the Vetuma log data to be utilized in possible subsequent troubleshooting. As a rule, with browser-based applications, it is possible for the user to trigger more than one consecutive identical service request (POST command). For example, an application may return to the browser a response with both JavaScript for performing a POST command, and a submit button in case the use of scripts is disabled. However, getting a response to an automatically sent POST command may take so long that the user assumes the request failed and manually selects the submit button. In this case, in addition to the automatically sent request, an identical extra request will be sent to the application. The Vetuma service has sought to avoid sending unnecessary POST commands in the responses it returns. When Vetuma finds that the use of scripts is enabled in the browser, it will not include submit buttons on such http responses it returns to the browser the purpose of which is to trigger automatic transition to the url given in the response. Copyright Fujitsu Finland Oy 24 (25)

25 7. APPENDICES AND REFERENCES 7.1 Appendices 1. Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto (pdf) 2. Liite1_Vetuma_palvelinvarmenteet (pdf) 3. Liite3_Vetuma_SAML_sanomaesimerkit (pdf) 7.2 References [SAML 2.0-standardi] 1. [SAMLCore] S. Cantor et al. Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID saml-core-2.0- os [SAMLProfile] Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID saml-profiles-2.0-os [SAMLAuthnCxt] J. Kemp et al. Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID samlauthncontext-2.0-os [SAMLBind] S. Cantor et al. Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID saml-bindings-2.0-os [SAMLConform] P. Mishra et al. Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID samlconformance-2.0-os [SAMLGloss] J. Hodges et al. Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID saml-glossary-2.0-os [SAMLMeta] S. Cantor et al. Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March Document ID saml-metadata-2.0-os [Schema2] 4. P. V. Biron et al. XML Schema Part 2: Datatypes. World Wide Web Consortium Recommendation, May [xmldsig-core] W3C Recommendation, XML Signature Syntax and Processing, June [SAMLDisco] Identity Provider Discovery Service Protocol and Profile, OASIS Security Services TC, March [FinnishSAML2Profile] 11. SAML 2.0 protocol deployment profile for the Finnish public sector v.1.1, FinnishSAML2Profile pdf 12. SAML 2.0 Attribute Profile for the Finnish public sector v.1.1, FinnishAttributeProfile pdf Copyright Fujitsu Finland Oy 25 (25)