GrandID API Swedish BankID - Svensk e

 GrandID API Swedish BankID Developer documentation Version Date Author Comments 0.1 2014­03­25 Mikael Westöö Document is created 0.2 2014­03­26 Jang Kee First draft done. 0.3 2014­04­06 Mikael Westöö SOAP version 1.6 0.4 2014­12­15 Mikael Westöö JSON REST spec. 0.5 2015­01­19 Patrik Grinsvall Changed endpoints 0.6 2015­01­20 Patrik Grinsvall Fixed spelling errors 0.7 2015­02­20 Patrik Grinsvall Added Bankid Sign 0.8 2015­04­24 Patrik Grinsvall Changed JSON endpoint to version 1.1 Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (1/8) Table of contents 1 ­ Introduction 1.1 ­ What you should already know 2 ­ GrandID API with BankID Authentication 2.1 ­ Prerequisites for BankID Authentication 2.2 ­ Process schematics over GrandID API with BankID Authentication 2.3 ­ Explanation of schematics over GrandID API with BankID Authentication 2.4 ­ GrandID API with BankID Authentication Demo application for Mobile applications 3 ­ GrandID API BankID Sign 3.1 ­ Prerequisites for BankID Sign 3.2 ­ Process schematics over GrandID Client with BankID Sign 3.3 ­ Explanation of schematics over GrandID API with BankID Sign 3.4 ­ GrandID Sign Endpoint Parameters 3.5 ­ GrandID Sign GetSession Response 4 ­ API documentation for GrandID Client Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (2/8) 1 ­ Introduction In this document, we specify the API and flow of events that will cover the functions of GrandID API ­ Swedish BankID. Our API will enable your Native phone app or browser to access our federated login services via Svensk e­identitet. 1.1 ­ What you should already know Before you read this document, if you intend to work with mobile development you should have a basic understanding of a web programming language or a programming language for iOS or Android as well as JSON. 2 ­ GrandID API with BankID Authentication Implementing Swedish BankID Authentication is fairly easy. The client app needs to do two REST request to GrandID API services as described below. 2.1 ­ Prerequisites for BankID Authentication Before starting ●
●
●
BankID ­ available from appstore. apiKey ­ Will be sent to you by mail authenticateServiceKey ­ Will be sent together with your apiKey Before you try to build our demo or starting to implement in your own app you will need to download BankID from app store or from https://install.bankid.com. This application is free. All users using your app will also be needing BankID. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (3/8) 2.2 ­ Process schematics over GrandID API with BankID Authentication 2.3 ­ ​
Explanation of schematics over GrandID API with ​
BankID Authentication 1) HTTP GET request to https://client.grandid.com/json1.1/FederatedLogin with your apiKey, authenticateServiceKey and callbackUrl as GET parameters. For apps, leave callbackUrl empty. 2) JSON response containing a redirectUrl and a sessionId is returned. 3) The redirectUrl is launched which in turn will launch the BankID software. 4) The user is asked to enter the PIN code for the BankID and the input is authenticated. 5) The authentication response is returned to BankID . 6) BankID closes and app switches the user back to the original application Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (4/8) 7) The original application calls the method GetSession at https://client.grandid.com/json1.1/GetSession​
together with apiKey, authenticateServiceKey and the sessionId returned from FederatedLogin 8) The response from GetSession is returning the user information. 2.4 ­ GrandID API with BankID Authentication Demo application for Mobile applications We have built demo applications that use our services. Here are the repositories for those applications. Android repository: https://bitbucket.org/grandid/swedish­mobile­bankid­android/ iOS repository: https://bitbucket.org/grandid/swedish­mobile­bankid­ios/ IMPORTANT: Make sure that you change the change the apiKey and the authenticateServiceKey in the confg­file for each repository before you run the demo. 3 ­ GrandID API BankID Sign Using GrandidID API BankID Sign is not so different from using Authentication, instad of the initial GET request to FederatedLogin you need to POST the data that should be signed to the same endpoint in the parameter userNonVisibleData. 3.1 ­ Prerequisites for BankID Sign Before starting ●
●
●
BankID ­ available from appstore or from https://install.bankid.com apiKey ­ Will be sent to you by mail. authenticateServiceKey ­ Will be sent together with your apiKey. Before you try to build our demo or starting to implement in your own app you will need to download BankID from app store. This application is free. All users using your app will also be needing BankID. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (5/8) 3.2 ­ Process schematics over GrandID Client with BankID Sign 3.3 ­ ​
Explanation of schematics over GrandID API with ​
BankID Sign 1. HTTP POST request to GrandID FederatesLogin with your apiKey, authenticateServiceKey and a callbackUrl as parameters. See 3.4 GrandID Sign Endpoint Parameters for the post parameters that should be provided. ​
Note!​
If the signing should be carried out on another device then an extra parameter, pnr, containing the Swedish personal number should be provided in 12 digits and no spaces or extra characters. 2. JSON response containing a redirectUrl and a sessionId is returned. 3. The redirectUrl is launched which in turn will launch the BankID software. 4. The user is shown the data to sign and is asked to enter the PIN code for the BankID and the input is authenticated. 5. The authentication response is returned to BankID . Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (6/8) 6. BankID closes and app switches the user back to GrandID or order to wait for the signing to be completed. 7. The users browser is redirected to the callbackUrl specified in the first POST request. If no callbackUrl is specified bankid will be closed without any redirect and the calling application will be in focus. 8. The original application calls the method GetSession at https://client.grandid.com/json1.1/GetSession​
together with apiKey, authenticateServiceKey and the sessionId returned from FederatedLogin 9. The response from GetSession is returning the signed data and user information. 3.4 ­ GrandID Sign Endpoint Parameters When POST­ing to GrandID FederatedLogin API­endpoint you will need to provide parameters containing data to sign and the callbackUrl for which we will redirect the user after the signing is complete. For test: https://client­test.grandid.com/json1.1/FederatedLogin?apiKey=xxx&authenticateServiceKey=xx
x​
&callbackUrl=xxx For production: https://client.grandid.com/json/FederatedLogin?apiKey=xxx&authenticateServiceKey=xxx&callb
ackUrl=xxx POST Parameter Explanation userNonVisibleData The actual data to sign. ­ ​
Required! userVisibleData The data displayed to the user in the BankID app. ­ ​
Optional, will be set to userNonVisibleData if not provided pnr Optional​
, the swedish personal number for the user with 12 digits and no spaces or hypens. Example: 190001011234. This is used if the signing should be completed on another device, eg. mobile. 3.5 ­ GrandID Sign GetSession Response Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (7/8) The response will be in JSON. Except for the user information there will be a JSON key, “Signature”. The signature is a base64 encoded XML response. You will need to base64 decode this key in order to get the complete signature. 4 ­ API documentation for GrandID Client Please, read our generic ​
GrandID Client documentation​
. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
​
Page (8/8)