BankID Relying Party Guidelines

Transcription

1 BankID Page 1(25) BankID Relying Party Guidelines Version:

2 BankID Page 2(25) 1 Introduction Versions Terms and definition How it Works Client Platforms Use Cases Basic Use cases Flow of events Exceptions Launching Launching the BankID app from a browser Behavior in Different Browsers Chrome Internet Explorer Parameters in the start URL Launching the BankID app from Native App on Mobile Device Android ios Windows Phone Technical Requirements Recommended User Messages Production Environment Test Environment Information regarding the Web Service API SSL certificates Versions Test Environment No soapaction Support Recommended Terminology File Signing RP Interface Description Method Auth In parameters Return value Method Sign In Parameters Return value Method FileSign - Deprecated PersonalNumberType EndUserInfoType RequirementAlternativesType... 19

3 BankID Page 3(25) OrderResponseType Error codes for Auth/Sign/FileSign Method Collect In Parameters Return Value ProgressStatusType UserInfoType Error codes Collect More information about requirement alternatives Syntax Examples... 24

4 BankID Page 4(25) 1 Introduction This document contains guidelines for Relying Parties (RP, Förlitande Part in Swedish) when using BankID in their own services. Please check and verify that you have the latest version of this document. 1.1 Versions Version Date Change 1.x Historical versions Possible to use the interface to access BankID on file, BankID on smart cards as well as Mobile BankID New name of document New version of RP-Interface Changes in the instructions for launching the ios and Windows Phone BankID app. Changes in the user message requirements. Added information in the Test Environment chapter regarding how the BankID Security Application should be configured for test Details on how to configure the PC-client for test. We recommend the autostarttoken to be used. The redirect parameter must be used together with autostarttoken on PC:s. Minor change in the recommended text RFA How to start: The parameters must be in lower case. How to start: Error message if client started multiple times User message RFA17: updated with link to install.bankid.com Test environment: You need to remove the config file if the selector file is changed. Web Service: Validity time for previous versions of the web service API. Appendix RP Interface: max file size is 5 Mb Added REQ_BLOCKED (Not used) and ALREADY_COLLECTED (Not Used) as error codes for collect Parameters in the start URL: Removed the note for redirect in ios, it was not reliable. The general recommendation is to use redirect=null when it is possible. A clarification in the note for Windows and Mac OS X. Technical Requirements: New requirement RFT11 describing which cert to be configured as trusted. User Message Requirements: Changed RFA14 and RFA15 to two different texts depending on if the user access the service using a PC or a mobile device. Test Environment: Updated how to configure the PC-client for test. Error Codes Collect: RFA3 should be used for CANCELLED Method filesign is deprecated. Changed the examples of requirementalternatives to include Nordea E-leg Launching from browser: The start URL for mobile devices shall include three backslash (bankid:///). Launching from native app (Android): intent.addcategory and intent.settype not needed to launch in Android. Three backslash in the URI. Launching from native app (ios): Three backslash in the URL. Launching from native app (WP): Three backslash in the URI. More information about requirement alternatives: Added one more example. Commented the examples Parameters in the start URL: It is possible to use a new parameter rpref. Production Environment: The client also uses IP address and

5 BankID Page 5(25) Test Environment: The client also uses IP address and Use Cases: RP:s should consider to offer manual start of BankID app if the automatic start fails. RequirementAlternativesType: typing error; type changed to key How to Start: The href should be as close to the user event as possible. When to hide the href. Behavior in Different Browsers: Updated Chrome information. Recommended User Messages: RFA1 Also used for NO_CLIENT, RFA8 Inform the user how to get a BankID, RF14, RF15 STARTED is not a final state. Adjusted the messages accordingly. ProgressStatusType: STARTED is not a final state. The reason for STARTED explained in more detail. The RP should keep on polling How to Start: The recommendation to use a zero size window removed. It is up to RP to design their own solutions. Launching from Android: startactivity is not guaranteed to return a valid result. Network information: correction of address used from desktop clients. The Web Service API: Some notes related to trust store and key store. Removed information related to previous versions of the BankID solution (plugins and old versions of RP Interface). Test environment: How to get test apps and BankID for test is described in separate document. Removed from this document. Appendix: RP Interface Description: Removed the details of method FileSign. It is deprecated. Editorial. 1.2 Terms and definition Term BankID Security Application BankID app RP Description The client software that needs to be installed in the end users mobile device or personal computer (PC). The same term is used for PCs and mobile platforms. BankID app is the short form used in this document. In Swedish the client software installed on PCs is called BankID säkerhetsprogram. In Swedish the client software installed on mobile platforms is called BankID säkerhetsapp Relying Party that uses the BankID web service to provide login and signing functionality to the end user. 1.3 How it Works To be able to use BankID s identification and signature features users must install BankID Security Application (the BankID app) in a mobile device or PC. They also need to order a BankID from their bank. An RP uses the identification or signature service of BankID via a web service API provided by BankID (see Appendix: RP Interface Description). The web service API can only be accessed by an RP that has a valid SSL client certificate (an RP certificate). The RP certificate is obtained from the bank that the RP has purchased the BankID service from. If the BankID app is installed in the same device as the RP service executes in, the BankID app can be launched automatically by the RP service. In this case the users do not need to enter their ID number in the RP service. If, on the other hand, the RP service is used in a web browser on a PC and the users want to use a Mobile BankID the users will have to manually launch the BankID app in their mobile device. In this case the users need to provide their ID number in the RP service.

6 BankID Page 6(25) 1.4 Client Platforms BankID is supported in PCs running Windows, Mac OS X, mobile phones and tablet computers running Android and ios and mobile phones running Windows Phone 8. Up to date information on platform support can be found at Login Sign BankID Security Application for mobile devices BankID Security Application for PCs filesign - NOTE Support for multiple users Support for smart cards - User does not need to enter ID number at login NOTE: filesign is deprecated and will not be included in future versions of the RP Service API. We strongly recommend RP not to use filesign. See chapter 11 - File Signing for more information. 2 Use Cases There are a number of use cases that can be implemented using the new BankID solution. In this document we describe the most common use cases to keep it simple and to give the reader a basic understanding of the solution. If the BankID app is installed on the same device the user uses to access the service the RP should help the user to start the BankID app automatically. A description is found in Launching. In this case the users do not need to provide their ID number. If the BankID app is installed on another device the users must provide their ID number and manually start the BankID app. If the BankID app is installed on the same device the user uses to access the service, but the BankID app cannot be automatically started, the user must provide their ID number and manually start the BankID app on the same device. RP:s should consider this use case as a fallback in case the automatic start fails. To make the user experience consistent the RP must use the recommended messages and error messages in Recommended User Messages. The possibilities to restrict the types of BankID that can be used and how to define other requirements are described in RequirementAlternativesType. 2.1 Basic Use cases The following basic use cases exist: A. The user access the service using a browser on a personal computer. Users should be asked if they want to login or sign using BankID on this computer or Mobile BankID. Message RFA19 should be used. a. Users that select to use BankID on this computer does not need to enter their ID number and the RP must start the BankID app on the computer. b. Users that select Mobile BankID must enter their ID number and the RP must give the instruction to manually start the BankID app on their mobile device. B. The user access the service using a browser on a mobile device. Users should be asked if they want to login or sign using Mobile BankID on this device or Mobile BankID on another device. Message RFA20 should be used. a. Users that select to use this device do not need to enter their ID number and the RP must start the BankID app on the mobile device. b. Users that select to use another device must enter their ID number and the RP must give the instruction to manually start the BankID app on the other device.

7 BankID Page 7(25) C. The user access the service using a native app on a mobile device. In this case the user most likely wants to use a BankID on the same device. The RP may however provide possibilities to use another device in this case as well. a. The users do not need to enter their ID number and the RP app launches BankID App programmatically (see Native App on Mobile Device). b. Users that select to use another device must enter their ID number and the RP App must give the instruction to manually start the BankID app on the other device. In some cases it may be impossible to automatically start the BankID app. The reason could be browsers blocking it or that the RP app does not have the capabilities to launch external URL:s. In this case the users always can start the BankID app manually. In this case the users need to enter their ID number. 2.2 Flow of events 1. Users that select another device are asked to enter their ID number if it s not already saved or known by the RP. 2. The RP uses the Authenticate or Sign call of the web service API. The web service returns an autostarttoken and an orderreference. If the user selected another device RP should set condition certificatepolicies to to restrict the transaction to mobile devices only. 3. If the user selected same device the RP tries to start the BankID app. The autostarttoken must be used in the start command if the ID number is not provided in the web service call, see Launching. Once the BankID app has finished execution, focus will be returned to the browser/app. 4. If the user selected another device the RP informs the user to start the BankID app manually. 5. The RP service displays a progress indicator. 6. The login or sign transaction is displayed in the BankID app. The RP name (as stated in the RP certificate) is displayed. The user enters personal security code or cancels. 7. The RP periodically uses the Collect call of the web service API, until a final response is received and continuously updates the message displayed to the user. See Recommended User Messages. 8. RP removes the progress indicator. 2.3 Exceptions 1. The web service call in step 2 fails. The use case is cancelled and the RP shall instruct the user according to Recommended User Messages. The RP must not try to start the BankID app. 2. The Collect call in 7 fails. The use case is cancelled and RP shall instruct the user according to Recommended User Messages. 3. The automatic start in 3 fails due to different reasons: o The user has not installed the BankID app o Erroneous start command o User did not allow the browser to launch the URL The web browser will inform the user that the URL cannot be opened. Status START_FAILED will be delivered to the RP as response to the Collect call in 7 if the automatic start of the BankID app has not been completed within a certain time limit. The RP shall instruct the user according to Recommended User Messages. 4. The automatic start in 3 is successful but the user has no BankID of correct type. The BankID app will display an error message. Status STARTED will be delivered to the RP as response to the Collect call in 7. RP shall instruct the user according to Recommended User Messages. 5. In step 4, the user fails to manually start the BankID app or no BankID of correct type exists in the started client. Different status codes will be delivered to RP as response to the Collect call in 7. The RP shall instruct the user according to Recommended User Messages. 3 Launching 3.1 Launching the BankID app from a browser When the BankID app is installed the schema bankid is registered in the operating system. When the bankid schema is requested from the browser the operating system launches the BankID app. The URL works in Android, ios and Windows Phone 8 when the built-in web browser is used. The URL works in PCs with all commonly used browsers. Some differences exist on different platforms. The URL syntax is: bankid:///?autostarttoken=[token]&redirect=[returnurl]

8 BankID Page 8(25) Note that the redirect parameter must be last in the parameter list. The autostarttoken, filehash and rpref parameters are optional. Note that the parameter names must be lower case. Note that if the BankID app is started but no matching call to Authenticate or Sign has been done, an error message will be displayed in the app. 3.2 Behavior in Different Browsers Chrome In various version of Chrome (prior to version 40) a known problem blocks BankID from being started from a frame. Using the recommended method above solves the problem, see Internet Explorer Internet Explorer manipulates the URL in the redirect parameter. In this specification we state that the RETURNURL must be URL-encoded. However, Internet Explorer decodes the content prior passing it to the BankID app. This is why it must be last in the list of parameters. In the same way, Internet Explorer may decode the content of the RETURNURL when the BankID app passes the return URL back to the browser. If the RP includes session information that is affected by URL-encoders/decoders problems may occur. It is recommended to use only URL-encoding safe characters in the parameters Parameters in the start URL Parameter autostarttoken filehash redirect rpref Description Optional. Holds the autostarttoken that was returned from the web service call. If the user ID number was not included in the web service call the autostarttoken must be provided. We strongly recommend to always use the autostarttoken when the URL is used to start the client. If it is not included and the user reloads the page or if the page erroneously repeats the start command the user may get an error claiming that the BankID is missing. The likelihood of this to happen is reduced if autostarttoken is used. Deprecated. Mandatory. The BankID app uses the request parameter redirect to launch the RP web app after completed (including cancelled) authenticate or sign. The redirect URL must be UTF-8 and URL encoded and should match the web address the user is visiting when RP web app launches the BankID app. It may include parameters to be passed to the browser. For ios and Windows Phone the redirect must have a value. For all other platforms it may be empty ( redirect= ), or set to null ( redirect=null ). If it is empty or null the BankID app will terminate without launching any URL and the calling application will be in focus. The general recommendation is to use redirect=null when it is possible. Note for Windows and Mac OS X If redirect has a value the redirect parameter must be used together with autostarttoken. If autostarttoken is excluded, the content of redirect will be ignored and the behavior will be as if redirect=null. Note for Android If the user has several browsers installed on an Android device the user is sometimes presented with a question asking what browser to use. BankID recommends that redirect=null is used on Android. This ensures the user will return to the browser previously used. Note for Windows Phone When the browser on Windows Phone is started from an app it is considered a new session by the browser, hence any previous transient (session) cookies are unavailable. RP can use a persistent cookie or the RETURNURL to control the session. Relying Party Reference. Optional. Not supported in mobile devices.

9 BankID Page 9(25) Any reference the RP wants to use. The value will be included in the resulting signature. A typical use case is to protect a file when it is transported from a client to a server (compute hashsum of the file content in the client, include the hashsum as rpref, compare it (server side) with a hashsum of the file content computed in the server). The value must be base64 encoded and URL encoded and bytes (after encoding). rpref must be used together with autostarttoken. If autostarttoken is excluded, the content of rpref will be ignored. If the client software version is too old the parameter is not supported. An error will be displayed in the client Examples The RP wants the BankID app to open a browser with the following URL after finishing execution: The autostarttoken is included. The start URL is: bankid:///?autostarttoken=a4904c4c-3bb4-4e3f-8ac3-0e950e529e5f& redirect=https%3a%2f%2fdemo.bankid.com%2fnyademobanken%2fcavaclientredirreceiver.aspx%3forder Ref%3dbedea56d-7b46-47b1-890bf787c650bc93%26returnUrl%3d.%2fCavaClientAuth.aspx%26Environment%3dKundtest 3.3 Launching the BankID app from Native App on Mobile Device Android Intent intent = new Intent(); intent.setpackage("com.bankid.bus"); intent.setaction(intent.action_view); intent.setdata(uri.parse("bankid:///?autostarttoken=<insert AUTOSTARTTOKEN HERE>&redirect=null ")) ; startactivity(intent); ios In Android, the RP app does not need to register a URL scheme to be successfully re-launched by the BankID app. onresume() will be called when RP app is re-launched. A valid result is not guaranteed to be returned back from the BankID app to the RP app's Activity. The RP app should rely on the Collect call to obtain the result of the login or sign transaction. If the BankID app is not present on the device an android.content.activitynotfoundexception is thrown. RP must inform the user. Message RFA2 should be used. openurl:[nsurl bankid:///? autostarttoken=<insert AUTOSTARTTOKEN HERE>&redirect=fp_app_x:// ] If the BankID app is not present on the device NO is returned. RP must inform the user. Message RFA2 should be used. The RP app must register a unique URL scheme to make it possible for the BankID app to re-launch RP app. In Xcode select the project and in the Info tab expand URL Types and add the URL scheme rp_app_x. Note: rp_app_x is an example. The RP should use its own unique URL scheme. The RP must implement the following function that will be called when the RP app is re-launched. - (BOOL)application:(UIApplication *)application openurl:(nsurl *)url sourceapplication:(nsstring *)sourceapplication annotation:(id)annotation

10 BankID Page 10(25) Windows Phone // Create the URI string var uritolaunch = string.format( "bankid:/// <INSERT AUTOSTARTTOKEN HERE>, Uri.EscapeDataString("fp-app-x://bank_x")); // Create the URI to launch from a string. var uri = new Uri(uriToLaunch); // Launch the URI. bool success = await Windows.System.Launcher.LaunchUriAsync(uri); If the BankID app is not present on the device the operating system presents a dialogue asking to open Windows Phone store. RP must inform the user. Message RFA2 should be used. The RP app must register a unique URL scheme to make it possible for the BankID app to re-launch RP app. In Visual Studio: 1. Open Package.appxmanifest 2. Open the tab Declarations. 3. Add a "Protocol". Under name enter rp_app_x. 4. Enter a logo and a "Display name". Note: rp_app_x is an example, RP should use its own unique URL scheme. RP must also implement the following to be successfully re-launched by BankID Security App. In Visual Studio add the class AssociationUriMapper: /// <summary> /// The association uri mapper. /// </summary> internal class AssociationUriMapper : UriMapperBase { /// <summary> /// When overridden in a derived class, converts a requested uniform resource identifier (URI) to a new URI. /// </summary> /// <returns> /// A URI to use for the request instead of the value in the <paramref name="uri"/> parameter. /// </returns> /// <param name="uri">the original URI value to be mapped to a new URI.</param> public override Uri MapUri(Uri uri) { var tempuri = System.Net.HttpUtility.UrlDecode(uri.ToString()); // URI association launch. if (tempuri.startswith("/protocol")) { // Here we can redirect to the correct page, but for now we don't return new Uri("/MainPage.xaml", UriKind.Relative);

11 BankID Page 11(25) } } } // Otherwise perform normal launch. return uri; In App.xaml.cs, add AssociationUriMapper as UriMapper by adding the following line to the method InitializePhoneApplication: // Assign the URI-mapper class to the application frame. RootFrame.UriMapper = new AssociationUriMapper(); 4 Technical Requirements Short Name RFT1 RFT2 RFT3 RFT4 RFT5 RFT6 RFT7 RFT8 RFT9 RFT10 RFT11 Requirement When the BankID app is launched with a URL the content of the request parameter redirect must be UTF-8 and URL encoded. When the BankID app is launched with a URL the URL must not exceed 2000 characters. When the BankID app is launched with a URL the redirect URL should use HTTPS. The ID number in the RP web service API must be 12 characters (YYYYMMDDNNNN). When Collect returns COMPLETE RP shall read and store the parameters signature, userinfo and ocspresponse. RP does not need to verify the signature. BankID verifies the signature. Collect should be called every two seconds and must not be called more frequent than once per second. RP should display a progress indicator in its web app when waiting for the final response from Collect. RP must contact BankID s web service API from RP s backend server. RP must NOT contact BankID s web service API from RP s client app. RP should always use the latest version of the web service API, see Information regarding the Web Service API. If the user selects to use Mobile BankID only, the certificatepolicies condition must be set to RP must use the issuer of the server cert as trusted root. If the server cert is used as trusted, the RP service will not be able to access the BankID server when the server cert is changed. 5 Recommended User Messages Short Name Swedish Text English Text Event or API Code Mapping RFA1 Starta BankID-programmet. Start your BankID App. OUTSTANDING_ TRANSACTION, NO_CLIENT RFA2 Du har inte BankID-appen installerad. Kontakta din bank. The BankID app is not installed. Please contact your bank. The BankID app is not installed in the mobile device. RFA3 Åtgärden avbruten. Fo rso k igen. Action cancelled. Please try again. ALREADY_IN_P ROGRESS, CANCELLED RFA5 Internt tekniskt fel. Försök igen. Internal error. Please try again. RETRY, INTERNAL_ERR OR, CLIENT_ERR

12 BankID Page 12(25) RFA6 A tgärden avbruten. Action cancelled. USER_CANCEL RFA8 RFA9 RFA12 RFA13 RFA14 (A) RFA14 (B) RFA15 (A) RFA15 (B) BankID-programmet svarar inte. Kontrollera att det är startat och att du har internetanslutning. Om du inte har något giltigt BankID kan du hämta ett hos din Bank. Försök sedan igen. Skriv in din säkerhetskod i BankIDprogrammet och välj Legitimera eller Skriv under. Internt tekniskt fel. Uppdatera BankID-programmet och försök igen. Försöker starta BankIDprogrammet. Söker efter BankID, det kan ta en liten stund Om det har gått några sekunder och inget BankID har hittats, så har du sannolikt inget BankID i den här datorn, som går att använda för den aktuella inloggningen/underskriften. Om du har ett BankID på kort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta ditt BankID-program där. Söker efter BankID, det kan ta en liten stund Om det har gått några sekunder och inget BankID har hittats, så har du sannolikt inget BankID i den här enheten, som går att använda för den aktuella inloggningen/underskriften. Om du inte har något BankID kan du hämta ett hos din internetbank. Om du har ett BankID på en annan enhet kan du starta ditt BankIDprogram där. Söker efter BankID, det kan ta en liten stund Om det har gått några sekunder och inget BankID har hittats, så har du sannolikt inget BankID i den här datorn, som går att använda för den aktuella inloggningen/underskriften. Om du har ett BankID på kort, sätt in det i kortläsaren. Om du inte har något BankID kan du hämta ett hos din internetbank. Söker efter BankID, det kan ta en liten stund The BankID App is not responding. Please check that the program is started and that you have internet access. If you don t have a valid BankID you can get one from your bank. Try again. Enter your security code in the BankID App and select Identify or Sign. Internal error. Update your BankID App and try again. Trying to start your BankID App. Searching for BankID:s, it may take a little while If a few seconds have passed and still no BankID has been found, you probably don t have a BankID which can be used for this login/signature on this computer. If you have a BankID on card, please insert it into your card reader. If you don t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID App on that device. Searching for BankID:s, it may take a little while If a few seconds have passed and still no BankID has been found, you probably don t have a BankID which can be used for this login/signature on this device. If you don t have a BankID you can order one from your internet bank. If you have a BankID on another device you can start the BankID App on that device. Searching for BankID:s, it may take a little while If a few seconds have passed and still no BankID has been found, you probably don t have a BankID which can be used for this login/signature on this computer. If you have a BankID on card, please insert it into your card reader. If you don t have a BankID you can order one from your internet bank. Searching for BankID:s, it may take a little while EXPIRED_TRAN SACTION USER_SIGN CLIENT_ERR OUTSTANDING_ TRANSACTION STARTED The RP provided the ID number in the web service call (without using AutoStartTokenRe quired). The user accesses the service using a personal computer. STARTED The RP provided the ID number in the web service call (without using AutoStartTokenRe quired). The user accesses the service using a mobile device. STARTED The RP did not provide the ID number in the web service call. The user accesses the service using a personal computer. STARTED

13 BankID Page 13(25) RFA16 RFA17 Om det har gått några sekunder och inget BankID har hittats, så har du sannolikt inget BankID i den här enheten, som går att använda för den aktuella inloggningen/underskriften. Om du inte har något BankID kan du hämta ett hos din internetbank. Det BankID du försöker använda är för gammalt eller spärrat. Använd ett annat BankID eller hämta ett nytt hos din bank. BankID-programmet verkar inte finnas i din dator eller telefon. Installera det och hämta ett BankID hos din bank. Installera programmet från install.bankid.com. If a few seconds have passed and still no BankID has been found, you probably don t have a BankID which can be used for this login/signature on this device. If you don t have a BankID you can order one from your internet bank The BankID you are trying to use is revoked or too old. Please use another BankID or order a new one from your bank. The BankID App couldn t be found on your computer or mobile device. Please install it and order a BankID from your bank. Install the app from install.bankid.com. The RP did not provide the ID number in the web service call. The user accesses the service using a mobile device. CERTIFICATE_E RR START_FAILED RFA18 Starta BankID-programmet Start the BankID App The name of link or button used to start the BankID App RFA19 RFA20 Vill du logga in eller skriva under med BankID på den här datorn eller med ett Mobilt BankID? Vill du logga in eller skriva under med ett BankID på den här enheten eller med ett BankID på en annan enhet? Would you like to login or sign with a BankID on this computer or with a Mobile BankID? Would you like to login or sign with a BankID on this computer or with a BankID on another device? The user access the service using a browser on a personal computer. The user access the service using a browser on a mobile device. NB: RFA4, RFA7, RFA10 and RFA11 are deprecated and intentionally removed.

14 BankID Page 14(25) 6 Production Environment Description SSL certificate (RP certificate) Web service URL Web service API specification Issuer of server certificate Network information Information Provided by the bank that RP purchases the BankID service from. See section SSL certificates below. The server certificate is issued by the following CA. See section SSL certificates CN = BankID SSL Root Certification Authority OU = Infrastructure CA O = Finansiell ID-Teknik BID AB Certificate: -----BEGIN CERTIFICATE----- MIID6jCCAtKgAwIBAgIQSvZNAy61UF6qO2zWqvN/3zANBgkqhkiG9w0BAQUFADB0 MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQgQUIxGjAYBgNVBAsM EUluZnJhc3RydWN0dXJlIENBMTAwLgYDVQQDDCdCYW5rSUQgU1NMIFJvb3QgQ2Vy dglmawnhdglvbibbdxrob3jpdhkwhhcnmdgxmje5mdg1otaxwhcnmtkwnjaxmje0 NTAwWjB0MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQgQUIxGjAY BgNVBAsMEUluZnJhc3RydWN0dXJlIENBMTAwLgYDVQQDDCdCYW5rSUQgU1NMIFJv b3qgq2vydglmawnhdglvbibbdxrob3jpdhkwggeima0gcsqgsib3dqebaquaa4ib DwAwggEKAoIBAQCzqv7Rn43VFyTGicb+qjSGNeJga6GWQkMEXn9NvqCfknpaz4kf RbNHoQvtmw7CsiL83hMNU5y0EI6wC45Whn8ZXJ5/eqj1zBSu7QqKctEbMjWf6sf2 VUyE7lns6FxRFAgbhM2RS5LnWCfRsSgjKLXbJk7S2O/qVWdlxU1fAYfjbja1xhQm jartvcyv9d2f8mbgh9sosabvdlektixj9npbixii+c9dupzvy1qny02dssudvwm3 IwJlEljLfjcBQDtJlm/7TbKsnqvW8s+NT6JBputUZT8Mqsv63meEbhxcq6vNcNKZ SgeHZDmr9lY2hmmVK9TcgfWHHkymUAWTGRQzAgMBAAGjeDB2MA8GA1UdEwEB/wQF MAMBAf8wEwYDVR0gBAwwCjAIBgYqhXBOAQQwDgYDVR0PAQH/BAQDAgEGMB0GA1Ud DgQWBBS2GCMB5GeakO2/WOqKJJXGAop6tTAfBgNVHSMEGDAWgBS2GCMB5GeakO2/ WOqKJJXGAop6tTANBgkqhkiG9w0BAQUFAAOCAQEAe4vukBbEjzsYC8Mv1xLcUQVD gytgnqvp8lr8yabfnfhh+iiofk7qvvd3z+bibngegutb5k78utadkinittska4t4 3Uy/p/blqew8Sqhv0I5MVlW71++HiPth4xwHAoxfe4oyTQaJRgls1CCsCBnuT9IF 6nGUNziC46RqIlhiY7zDzROtBWjqJzq+QvO07s73m+GPk8kZVwQrtyFT2IuYMH23 od/sre2w5gclo2d62sbrzywyjzaabny9yl6wemdqwrqjz0myzhrvlcq1xrq4nvpl bmdfs1wd3vctsxlbffbu9qw+cytbn4uj7bhqw1r2kgeajm5grkl7z7lqztwsqw== -----END CERTIFICATE----- The BankID app for Windows Phone in production connects to the BankID server on the IP address using the ports 4710, 443, 80, in the order mentioned. The BankID Security Application for Android, ios, OS X and Windows in production connects to the BankID server on the IP address using port 443 and address using port 80. The BankID Security Application for OS X and Windows also connects to using port Test Environment BankID provides a test environment for an RP to use when developing and testing its service. To be able to use the test environment the RP will need: 1. An SSL certificate (RP certificate) for authorisation with the BankID web service API. 2. The URL for BankID s web service API. 3. Trust the issuer of the SSL certificate. 4. A test version of BankID Security App and/or BankID Security Program

15 BankID Page 15(25) 5. A BankID for test. Description SSL certificate (RP certificate for test) Passphrase for above certificate Web service URL Web service API specification Issuer of server certificate Test version of BankID Security App for mobile devices and PCs BankID for test Network information Information See section SSL certificates below. qwerty123 rp/v4 See section SSL certificates below. CN = BankID SSL Root Certification Authority TEST OU = Infrastructure CA O = Finansiell ID-Teknik BID AB Certificate: -----BEGIN CERTIFICATE----- MIID8zCCAtugAwIBAgIRAODr4WfulmxifqSx8UEMbyIwDQYJKoZIhvcNAQEFBQAw etekmciga1uecgwbrmluyw5zawvsbcbjrc1uzwtuawsgqkleiefcmrowgaydvqql DBFJbmZyYXN0cnVjdHVyZSBDQTE1MDMGA1UEAwwsQmFua0lEIFNTTCBSb290IENl cnrpzmljyxrpb24gqxv0ag9yaxr5ifrfu1qwhhcnmdgxmja0mtmyntu1whcnmtkw NjAxMTIxODAwWjB5MSQwIgYDVQQKDBtGaW5hbnNpZWxsIElELVRla25payBCSUQg QUIxGjAYBgNVBAsMEUluZnJhc3RydWN0dXJlIENBMTUwMwYDVQQDDCxCYW5rSUQg U1NMIFJvb3QgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkgVEVTVDCCASIwDQYJKoZI hvcnaqebbqadggepadccaqocggebaozh4y7akqrgb4ll/hcnqx0amcdahxkmjqbt NyIE3ppEnWYR6hGrZcSKRAYkU8ShS0Sf647Bj4tXiVQYg1msIvYgZ8h4QJqkqMYY 2nwJC2cDbtc3TL6ppXQVmIiS6wZewV1GL2xKUEPbKgDPiSgFyh3W1d/QihUwnwoa CGQ/crivftaNTnp4ZqQod9k35WfBy8xdB7cLHFeznfHoP1ZLOHza9bprT0F8YzEa u5cocmxwpe0sy9aqc8oo3gkyohjrxnxtldy2cmlxtciuwiyh+ubybz3hqw1yfeme 4IyiGyT9+LUChFhM0p53eR3GRUU7laxFVbVLuVdbIV0ZRL+0Eb8CAwEAAaN2MHQw DwYDVR0TAQH/BAUwAwEB/zARBgNVHSAECjAIMAYGBCoDBAUwDgYDVR0PAQH/BAQD AgEGMB0GA1UdDgQWBBSlaUGnPvmNu9R9LsDgulauQCwrvTAfBgNVHSMEGDAWgBSl augnpvmnu9r9lsdgulauqcwrvtanbgkqhkig9w0baqufaaocaqeay1zwz1ov3zmc 78uhGYA+j6Zktps9IXzIw3v1T3wtYclUoJI594w7vmTMqFY9z2mnms+gKTxCO/70 MpCNMgKSLj2bGsrMWHCvnDWpmYY5ZkDP2GWB6aqy+ehRmlYjUbPhjD44Xfjh/Stq 1yXCUfesLUHZDcBxpDspOwldWl7rhkE7QPj5hdSP85l04oIcnYiMyOPTt+4LNYN+ ncb0a/zkjcul7q9ngjfmehamhccpk8j1cosh36d8jmesblvtbewpnbmp5zxkakzf OzZLGyy9RnV51NhRMRnQtDOFCZ9vQuuyCE/TZeOp4IgZctEvt2Aab23fx5jWBbzC EtEmq/VqaQ== -----END CERTIFICATE----- See How to get a test BankID at See How to get a test BankID at The BankID app for Windows Phone for test connects to the BankID server on the IP address using the ports 4710, 443, 80, in the order mentioned. The BankID Security Application for Android, ios, OS X and Windows for test connects to the BankID server on the IP address using port 443 and address using port 80. The BankID Security Application for OS X and Windows also connects to using port 80.

16 BankID Page 16(25) 8 Information regarding the Web Service API 8.1 SSL certificates The RP certificate must be installed/configured in your key store. It does not need to be verified by your application and the issuer of the RP-certificate is not needed. The RP-certificate is verified by the BankID server when the channel is established. The BankID server will then present its server certificate to your application. The server certificate needs to be verified by you. To make that verification possible the issuer of the server certificate needs to be installed/configured in your trust store. Key stores and trust stores are managed differently depending on your environment and is not explained in this document. Note that different certificates are used for production and test. Note that the certificates may need to be converted to a different file format to be accepted by your environment. Note that your application needs access to your key store and trust store and your application needs to use correct key store and trust store. 8.2 Versions A new version of the web service API will be published on a new URL every time there is a change in the API. RP should always use the latest version of the API. The general rule is that old versions will shut down 2 years after the release of the successor. As new functionality is introduced to the system the behavior of an existing version of the interface may change, e.g. existing faults may also be used in new situations. This document is written for version 4 of the interface. V URL Changes Release date 1 ceejb/rpservice/rpservice 2 /RpServiceEjb/RpService/v2/RpSer vice The first version Added new types and parameters to existing methods. Added new fault to handle the new RP cancel functionality September 2011 May Not for public use October Mobile BankID, BankID on file, BankID on Card and Nordea e-leg merged to one solution. 4 Method filesign in 1) Extended Decision to deprecate method filesign January 2014 End of life January Janaury 2016 January 2016 June 2014 June Test Environment New versions and release candidates are used in the test environment prior to being taken into use in the production environment. Due to this the content and functionality in the test environment and production environment may temporarily differ. 8.4 No soapaction The service uses URLs to specify the action to use. The soapaction header must be or excluded all together. 9 Support In technical matters please contact [email protected]. In any other business, please contact the bank through which you have purchased the BankID service. Requirement

17 BankID Page 17(25) RFS1 RFS2 RFS3 RP should inform the user what to do in case of lost or forgotten security code (contact the issuer). RP must provide support for its own service. When the user is having problems the RP should redirect the user to test.bankid.com. Users that cannot successfully use their BankID at test.bankid.com should be redirected to the issuing bank in case of a BankID related problem and in case of network error to mobile phone carrier or the internet service provider. If the user can successfully identify and sign at test.bankid.com the user should be redirected to the RP support. 10 Recommended Terminology Description Recommended terminology in Swedish Mobile BankID Mobilt BankID Mobile BankID BankID Security Application for mobile devices BankID Security Application for PCs BankID säkerhetsapp BankID säkerhetsprogram Security code, password, PIN Säkerhetskod Security code Sign Underteckna Sign Signature Underskrift Signature Identify Legitimera sig Identify Identification/authentication Legitimering Identification 11 File Signing Recommended terminology in English BankID Security Application BankID Security Application The method filesign is deprecated and we strongly recommend RP not to use it. It will not be included in future versions of the RP Service API. The main reasons are: It is impossible to support filesign in a proper manner for Mobile devices Only pdf supported Size restrictions Our recommendation is to use the sign method with the following notes: 1. Present the document to be signed to the user using your own application/website. 2. Compute a message digest of the binary representation of the document. 3. Compile an abstract of the content of the document. 4. Use method sign with uservisibledata set to abstract and usernonvisibledata set to the message digest. The benefits of using this method are that it is available for PC:s and mobile devices, that there is no sizelimitation and that all types of documents can be signed.

18 BankID Page 18(25) 12 RP Interface Description 12.1 Method Auth Request an authentication order. The Collect method is used to query the status of the order In parameters Name personalnumber enduserinfo requirementalternatives Value PersonalNumberType - The ID number of the user trying to be authenticated (optional). If the ID number is omitted the user must use the same device and the client must be started with the autostarttoken returned in orderresponse. List of EndUserInfoType (optional). Used to provide information related to the user and the user s computer/device to the BankID-server. RequirementAlternativesType (optional). Used by RP to set requirements how the authentication or sign operation must be performed. Default rules are applied if omitted Return value Returns an orderresponse of type OrderResponseType or error Method Sign Request a signing order. The Collect method is used to query the status of the order In Parameters Name personalnumber enduserinfo requirementalternatives uservisibledata Value PersonalNumberType - The ID number of the user trying to sign (optional). If the ID number is omitted the user must use the same device and the client must be started with the autostarttoken returned inorderresponse. List of EndUserInfoType (optional). Used to provide information related to the user and the user s computer/device to the BankID-server. RequirementAlternativesType (optional). Used by RP to set requirements how the login or sign operation must be performed. Default rules are applied if omitted. The text to be displayed and signed. Must be UTF-8 encoded. The value must be base 64-encoded characters (after base 64-encoding). The text can be formatted using CR = new line, LF = new line and CRLF = new line usernonvisibledata Data not displayed to the user (optional). The value must be base 64-encoded characters (after base 64-encoding) Return value Returns an orderresponse of type OrderResponseType or error Method FileSign - Deprecated 12.4 PersonalNumberType Example with personal number ( personnummer ) <!-- ID number--> <!-- 12 digits. Century must be included -->

19 BankID Page 19(25) <personalnumber> </personalnumber> 12.5 EndUserInfoType Used to pass information related to the user and the user s computer/device to the BankID server. A list of types and values. Allowed types are: IP_ADDR. used to include the users IP-address as seen by RP. It is recommended to use this parameter to enable future controls of the IP-address (no controls are done in the current solution). Example with ip address <enduserinfo> <type>ip_addr</type> <value> </value> </enduserinfo> 12.6 RequirementAlternativesType A list of alternative requirements. Used by RP to put one or more requirement on how the order must be created and verified. A requirement consists of one or more conditions. Every condition has a type/key and can have one or more values. If no requirement is included a set of default conditions is applied. The order of the requirement is significant. The first requirement where all conditions are true will be used. The used requirement is included in the resulting signature. <requirementalternatives> <requirement> <condition> <key>type OF CONDITION</key> <value>value FOR THE CONDITION</value> </condition> </requirement> </requirementalternatives> Type of conditions and values Type of condition Values Default CardReader "class1" - (default). The transaction must be performed using a card reader where the PIN-code is entered on the computers keyboard, or a card reader of higher class. "class2" - The transaction must be performed using a card reader where the PIN-code is entered on the reader, or a reader of higher class. <no value> - defaults to "class1". This condition should be combined with a CertificatePolicies for a smart card to avoid undefined behavior. No special type of card reader required. CertificatePolicies The oid in certificatepolicies in the user certificate. One wildcard * is allowed from position 5 and forward ie * The values for production BankIDs are: " " - BankID on file " " - BankID on smart card " " - Mobile BankID If no certificatepolicies is set the following are default in the production system: , , , The following are default in the test system:

20 BankID Page 20(25) Type of condition Values Default " " - Nordea e-id on file and on smart card. The values for test BankIDs are: " " - BankID on file " " - BankID on smart card , , , , If one certificatepolicy is set all the default policies are dismissed. IssuerCn " " - Mobile BankID " " - Nordea e-id on file and on smart card Test BankID for some BankID Banks The cn (common name) of the issuer. Wildcards are not allowed. Nordea values for production: "Nordea CA for Smartcard users 12" - E-id on smart card issued by Nordea CA. "Nordea CA for Softcert users 13" - E-id on file issued by Nordea CA If issuer is not defined all relevant BankID and Nordea issuers are allowed. AutoStartTokenRequired Example Nordea values for test: "Nordea Test CA for Smartcard users 12" - E-id on smart card issued by Nordea CA. "Nordea Test CA for Softcert users 13" - E-id on file issued by Nordea CA If set to Yes, the client must have been started using the autostarttoken. To be used if it is important that the BankID App is on the same device as the RP service. If omitted, the client does not need to be started using the autostarttoken. It does not work to set it to No. If omitted, the client does not need to be started using the autostarttoken. Additional information related to RequirementAlternatives is given in More information about requirement alternatives OrderResponseType Return value from auth/sign/filesign OrderRef must be used by RP when using the collect method. UUID-string: characters. AutoStartToken must be used when the user ID is not provided. UUID-string: characters. Example, response from Auth <AuthResponse> <orderref>8e4dd041-e38f-463b-b286-a6c5e35d462d</orderref> <autostarttoken>a5312da3-0c71-4a74-a14d-28bc11d6ed3a</autostarttoken> </AuthResponse>

21 BankID Page 21(25) 12.7 Error codes for Auth/Sign/FileSign Code Reason Action by RP INVALID_PARAMETERS ALREADY_IN_PROGRESS INTERNAL_ERROR RETRY ACCESS_DENIED_RP Invalid parameter. Invalid use of method An order for this user is already in progress. The order is aborted. No order is created. Internal technical error in the BankID system. Internal technical error in the BankID system. RP does not have access to the service or requested operation. RP must not try the same request again. This is an internal error within RP's system and must not be communicated to the user as a BankIDerror. RP must inform the user that a login or signing operation is already initiated for this user. Message RFA3 should be used. RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used. RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used. RP must not try the same request again. This is an internal error within RP's system and must not be communicated to the user as a BankIDerror Method Collect In Parameters Name orderref Value The orderreference in the orderresponse received from Auth, Sign or SignFile. (UUID-string) Return Value Name progressstatus signature userinfo ocspresponse Type ProgressStatusType String (b64). XML-signature. (If the order is COMPLETE). The content of the signature is described in BankID Signature Profile specification. UserInfoType (If the order is COMPLETE) String (b64). OCSP-response (If the order is COMPLETE). The OCSP 0 response is signed by a certificate that has the same issuer as the certificate being verified. The OSCP response has an extension for Nonce. The nonce is calculated as: SHA-1 hash over the base 64 XML signature encoded as UTF-8. This is the value in the signature element in Collect output. 12 random bytes is added after the hash The nonce is 32 bytes ( )

22 BankID Page 22(25) ProgressStatusType Status Reason Action by RP OUTSTANDING_T RANSACTION NO_CLIENT STARTED The order is being processed. The client has not yet received the order. The status will later change to NO_CLIENT, STARTED or USER_SIGN. The order is being processed. The client has not yet received the order. If the user did not provide her ID number the error START_FAILED will be returned in this situation. A client has been started with the autostarttoken but a usable ID has not yet been found in the started client. When the client starts there may be a short delay until all ID:s are registered. The user may not have any usable ID:s at all, or has not yet inserted their smart card. If RP tried to start the client automatically, the RP should inform the user that the app is starting. Message RFA13 should be used. If RP did not try to start the client automatically, the RP should inform the user that she needs to start the app. Message RFA1 should be used. If RP tried to start the client automatically: This status indicates that the start failed or the users BankID was not available in the started client. RP should inform the user. Message RFA1 should be used. If RP did not try to start the client automatically: This status indicates that the user not yet has started her client. RP should inform the user. Message RFA1 should be used. If RP does not require the autostarttoken to be used and the user provided her ID number the RP should inform the user of possible solutions. Message RFA14 should be used. If RP require the autostarttoken to be used or the user did not provide her ID number the RP should inform the user of possible solutions. Message RFA15 should be used. Note: STARTED is not an error, RP should keep on polling using collect. USER_SIGN The client has received the order. The RP should inform the user. Message RFA9 should be used. USER_REQ COMPLETE Not used The user has provided the security code and completed the order. Collect response includes the signature, user information and the ocsp response. RP should control the user information returned in userinfo and continue their process UserInfoType Name personalnumber givenname surname name notbefore notafter Value PersonalNumberType - ID number (swe personnummer) The given name of the user The surname of the user The given name and surname of the user Start of validity of the users BankID End of validity of the Users BankID

23 BankID Page 23(25) Name ipaddress Value The IP-address of the user agent as the BankID server discovers it Error codes Collect Error code Reason Action by RP INVALID_PARAM ETERS REQ_PRECOND REQ_ERROR REQ_BLOCKED INTERNAL_ERRO R Invalid parameter. Invalid use of method. Using an orderref that previously resulted in COMPLETE. The order cannot be collected twice. Not used. Not used. Not used. Internal technical error in the BankID system. RP must not try the same request again. This is an internal error within RP's system and must not be communicated to the user as a BankID-error. RP must not automatically try again. RP must inform the user. Message RFA5. RETRY Internal technical error in the BankID system. RP must not automatically try again. RP must inform the user. Message RFA5. ACCESS_DENIED _RP CLIENT_ERR RP does not have access to the service or requested operation. Internal technical error. It was not possible to create or verify the transaction. RP must not try the same request again. This is an internal error within RP's system and must not be communicated to the user as a BankID-error. RP must not automatically try again. RP must inform the user. Message RFA12. EXPIRED_TRANS ACTION CERTIFICATE_ER R The order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late. This error is returned if: 1) The user has entered wrong security code too many times in her mobile device. The Mobile BankID cannot be used. 2) The users BankID is revoked. 3) The users BankID is invalid. RP must inform the user. Message RFA8. RP must inform the user. Message RFA16. USER_CANCEL The user decided to cancel the order. RP must inform the user. Message RFA6. CANCELLED START_FAILED The order was cancelled. The system received a new order for the user. The user did not provide her ID, or the RP requires autostarttoken to be used, but the client did not start within a certain time limit. The reason may be:: RP must inform the user. Message RFA3. 1) The RP must use autostarttoken when starting the client

24 BankID Page 24(25) Error code Reason Action by RP 1) RP did not use autostarttoken when starting BankID security program/app. 2) The RP must inform the user. Message RFA17. 2) The client software was not installed or other problem with the user s computer. ALREADY_COLL ECTED Not used More information about requirement alternatives Syntax It is possible to use several alternative requirements. Each requirement has one or more condition(s). Each condition in a requirement must be fulfilled. A condition can have one or more alternative values of which one must be fulfilled. requirement(s) (OR) condition(s) (AND) key value(s) (OR) Examples Mobile BankID <requirementalternatives> <requirement> <condition> <key>certificatepolicies</key> <value> </value> </condition> </requirement> </requirementalternatives> // The first requirement, all following // conditions must be fulfilled // The certificate policy must be // (Mobile BankID) Mobile BankID OR Nordea E-leg OR BankID on Card <requirementalternatives> <requirement> <condition> <Key>CertificatePolicies</key> <value> </value> <value> </value> <value> </value> </condition> </requirement> </requirementalternatives> // The certificate policy must be // Mobile BankID OR // Nordea E-leg OR // BankID on Card BankID on Card in a Class2 Reader or Nordea E-leg on Card in a Class2 Reader Different types of Nordea e-id cannot be separated using certificatepolicy only. Their smart card issuer needs to be included as a condition as well. <requirementalternatives> <requirement> <condition> <key>certificatepolicies</key> <value> </value> </condition> <condition> <key>cardreader</key> <value>class2</value> // The first requirement // The certificate policy must be // BankID on Card // AND cardreader class2 must be used

25 BankID Page 25(25) </condition> </requirement> <requirement> // OR The second requirement <condition> <key>certificatepolicies</key> // The certificate policy must be <value> </value> // Nordea e-leg </condition> <condition> <key>issuercn</key> // AND The issuer must be Nordea 12 <value>nordea CA for Smartcard users 12</value> </condition> <condition> <key>cardreader</key> // AND cardreader class2 must be used <value>class2</value> </condition> </requirement> </requirementalternatives>