Interfaces – Overview

Abbreviations and naming conventions in this documentation:
NiA = Net iD Access (The App used for login and signing)
NiAS = Net iD Access Server (The Web Service communicating with the service and with Net iD Access)
The Service = The heart of the solution with webserver, applications server, databases etc.

Overview


Step-by-step

Here you find the recommendations for the different use cases. A full description of the interface can be found in:
Net iD Access Interface Details“.

Login
1. Call NiAS with method “Authenticate”

2. The SOAP-framwork responds that the call itself was OK. The login operation is now handled by NiA and NiAS.

Sign
1. Call NiAS with method “Sign”
The text in the parameter “userVisibleData” will be shown to the user.
To format the text CR, LF and CRLF can be used and will all result in a (1) linefeed. Not other formatting can be done.

2. The SOAP-framwork responds that the call itself was OK. The login operation is now handled by NiA and NiAS.

Common process for Login and Sign
3. Call NiAS with method “Collect” to receive final status of the login/sign-process. The call should be repeated until the status code “COMPLETE” is returned. If “Collect” returns an error code the login/sign-process must be cancelled and the service must not continue to call “Collect”.

4. Collect returns the status ” login/sign-process is finished. Info about the user is returned in the parameter “userInfo” and can be used by the service.

In a typical flow OUTSTANDING_TRANSACTION is returned first (the user have not yet started NiA), then USER_SIGN (login or sign is shown on the phone/tablet) and at last COMPLETE if the user did right or error code USER_CANCEL om användaren valde att avbryta.

Status codes

Status code What has happend?
OUTSTANDING_TRANSACTION NiA not yet stated
USER_SIGN NiA has received the request
COMPLETE The user has completed the login or sign process

Error codes

If an error is returned the service must stop calling “Collect”.

Error code What has happend?
INVALID_PARAMETERS  
ACCESS_DENIED_RP  
SIGN_VALIDATION_FAILED  
RETRY  
INTERNAL_ERROR  
UNKNOWN_USER  
ALREADY_COLLECTED  
EXPIRED_TRANSACTION  
INVALID_DEVICESW  
ALREADY_IN_PROGRESS  
USER_CANCEL  
CANCELLED

Requirements/Recommendations

No: Requirement
1 När NiA anropas med hjälp av en URL skall query-delen av URL:en vara kodad med URL UTF-8-formatet.
2 När NiA anropas med hjälp av en URL skall request-parametern redirect inte vara längre än 2048 tecken.
3 När NiA anropas med hjälp av en URL bör redirect innehålla schemat https (dvs använda SSL).
4 Text-to-be-signed i interface kan formateras genom att inkludera tecknet \n som kommer att visas som radbrytning
5 När Collect returnerar COMPLETE kan parametrarna signature, verificationStatus, userInfo och ocspResonse läsas ut och arkiveras av tjänsten. Tjänsten kan verifiera verifiera signaturen själv om så önskas.
6 Collect should not be called more often than once per second.
7 The service should show some “waiting symbole” in the web application while waiting for answer from Collect.

Recommendations for messages

Maybe we add recommendations for messages…

Information regarding basic connectivity

Description Value
Certificate used for connections to
Net iD Access Server from the service
Of your choice
URL to Web services (SecMakers reference setup) https://access.www.secmaker.com/nias/
Specification (SecMakers reference setup) https://access.www.secmaker.com/nias/ServiceServer.asmx?WSDL
Firewall information The Net iD Access App always contacts the
configured service-URL on TCP/443 or TCP/4711.