doc/login

   1 Log in specification
   2 =====================
   3
   4 Source: Provozní řád ISDS, version 2011-02-05, Pages 11–13, 17
   5 Source: Vyhláška o stanovení podrobností užívání a provozování ISDS (194/2009
   6     Coll.)
   7 Source: Webové služby ISDS pro manipulaci s datovými zprávami,
   8     version 2 (2009-06-25)
   9 Source: Podpora OTP autentizace v ISDS, version 1.5 (2011-10-14)
  10 Source: Přihlášení bezpečným kódem,
  11     <https://www.mojedatovaschranka.cz/static/pages/prihlasovani_bezp_kod.html>
  12     (2012-01-03)
  13 Source: Podpora authentizace Mobilním klíčem v rozhraní WS v ISDS, version 1.1
  14     (2019-06-06)
  15
  16
  17 There are three authentication methods. One is a stateless HTTP Basic method
  18 (assured by X.509 client certificate in some cases). Another one is
  19 a state-full HTTP non-standard hotp or totpsendsms/totp method. The third one
  20 is a state-full HTTP non-standard mobile key method.
  21
  22
  23 Stateless HTTP Basic Method
  24 ===========================
  25
  26 HTTP client must attach authentication data to each request by Basic method.
  27
  28 Allowed log in methods:
  29
  30     – HTTPS connection, server authenticated using SSL server certificate,
  31     user authenticated using HTTP 1.1 basic authentication with user name and
  32     password.
  33
  34     – SSL connection, user authenticated using `commercial' client
  35     certificate AND user name and password. The client certificate must be
  36     preregistered in web (browser) interface.
  37
  38     – SSL connection, user authenticated using `system' client certificate.
  39     Client certificate must be preregistered to the box.
  40
  41     – SSL connection, user authenticated using `system' client certificate of
  42     third party AND using HTTP 1.1 basic authentication (user name is box ID,
  43     password is empty). This case is intended for hosted software as service
  44     solutions.
  45
  46 Note: Certificate attributes `commercial' and `system' are defined in Czech
  47 Electronic Signature Act.
  48
  49 Once client certificate is registered, user cannot log in with HTTP basic
  50 authentication only.
  51
  52 Client private key must be stored in cryptographic device in non-exportable way.
  53 The device driver must provide any of the APIs in addition:
  54
  55     – Microsoft CryptoAPI
  56     – PKCS#11 API through libp11 library.
  57
  58 Desktop applications accessing ISDS must log in only on manual request of
  59 a user. Daemon implementations can log in automatically, but they are forbidden
  60 to abuse ISDS (e.g. redownloading old messages).
  61
  62
  63 HTTP OTP Methods
  64 ================
  65
  66 SOAP services are relocated to
  67 <https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT> URL.
  68
  69 Server HTTP header `X-Response-message-text' value is encoded according to RFC
  70 2047, method B (Base64) in UTF-8.
  71
  72 Authentication process is sequence of challenge-response HTTP messages that
  73 differ for HMAC-Based One-Time Password (HOTP) and Time-based One-Time Password
  74 (TOTP) methods. They are described bellow.
  75
  76 After successful OTP authentication, client obtains a cookie named
  77 IPCZ-X-COOKIE that must be sent with each subsequent HTTP request. The cookie
  78 is valid for 30 minutes of inactivity.
  79
  80 Client is supposed to ask server to invalidate the cookie before closing
  81 session by sending GET request to
  82 <https://DOMAINNAME/as/processLogout?uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>.
  83
  84 The DOMAINNAME variable is one from server locators (e.g.
  85 `www.mojedatovaschranka.cz'). WEB_SERVICE_ENDPOINT is request-URI postfix
  86 specific for family of requested SOAP service (e.g `dz').
  87
  88 Specification requires client to send first POST request without
  89 WWW-Authenticate header and to receive 401 response and to resend the request
  90 with the authentication header delivering credentials again.
  91
  92
  93 HTTP HOTP Method
  94 ================
  95
  96 Client sends a POST request to
  97 <https://DOMAINNAME/as/processLogin?type=hotp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>
  98 with credentials in HTTP Basic header. The credentials are user name, password
  99 and OTP code in form USERNAME ":" PASSWORD OTP_CODE. All four fields are
 100 concatenated and encoded into Base64 as in standard HTTP Basic method. So the
 101 only difference is the password is augmented with OTP code.
 102
 103 If authentication does not succeed, server will return 401 response
 104 with headers like these:
 105
 106 WWW-Authenticate: hotp
 107 X-Response-message-code: authentication.error.userIsNotAuthenticated
 108 X-Response-message-text: =?UTF-
 109     8?B?Q2h5YmEgcMWZaWhsw6HFoWVuw60sIHpub3Z1IHphZGVqdGUgw7pkYWplLg==?=
 110
 111 The X-Response-message-code header carries machine readable code,
 112 X-Response-message-text is user readable text and they have following
 113 meaning:
 114
 115 X-Response-message-Code                         Meaning
 116 -----------------------------------------------------------------------------
 117 authentication.error.userIsNotAuthenticated     Bad log-in, retry
 118 authentication.error.intruderDetected           Access blocked for 60 minutes
 119 authentication.error.paswordExpired             Password has expired
 120 authentication.error.badRole                    User name is not permitted to
 121                                                 access requested URI
 122
 123 If authentication succeeds, server will return 302 response:
 124
 125 Set-Cookie:IPCZ-X-COOKIE=01-5c1047cb9f3545f68cf987e6750acac4;
 126     Domain=.mojedatovaschranka.cz; secure, HttpOnly
 127 Location: https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT
 128
 129 With cookie used to track session and redirects to new URL where client should
 130 resubmit its original POST request.
 131
 132 Non-normative: The HMAC-based code is computed as specified in RFC 4226 (HOTP:
 133 An HMAC-Based One-Time Password Algorithm).
 134
 135
 136 HTTP TOTP Method
 137 ================
 138
 139 Client sends POST request to
 140 <https://DOMAINNAME/as/processLogin?type=totp&sendSms=true&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>
 141 with user name and password in standard HTTP Basic authentication header.
 142
 143 If credentials are valid, ISDS generates one-time code and sends it through
 144 SMS GSM gateway to user's predefined phone number (the phone number can be set
 145 on interactive web portal) and returns 302 response with redirect:
 146
 147 302 Found
 148 X-Response-message-code: authentication.info.totpSended
 149 X-Response-message-text: =?UTF-8?B?SmVkbm9yw6F6b3bDvSBrw7NkIG9kZXNsw6FuLg==?=
 150 Location: https://DOMAINNAME/as/processLogin?type=totp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT
 151
 152 Otherwise 401 response is returned:
 153
 154 WWW-Authenticate: totpsendsms
 155 X-Response-message-code: authentication.error.userIsNotAuthenticated
 156 X-Response-message-text: =?UTF-8?B?Q2h5YmEgcMWZaWhsw6HFoWVuw60sIHpub3Z1IHphZGVqdGUgw7pkYWplLg==?=
 157
 158 X-Response-message-code defines machine parsable reason and
 159 X-Response-message-text human readable text:
 160
 161 X-Response-message-code                         Meaning
 162 -------------------------------------------------------------------------------
 163 authentication.info.totpSended                  OTP has been sent by ISDS
 164 authentication.error.userIsNotAuthenticated     Bad log-in, retry
 165 authentication.error.intruderDetected           Access blocked for 60 minutes
 166 authentication.error.paswordExpired             Password has expired
 167 authentication.info.cannotSendQuickly           OTP cannot be sent repeatedly
 168                                                 at this rate (minimal delay
 169                                                 depends on TOTP window setting)
 170 authentication.error.badRole                    User name is not permitted to
 171                                                 access requested URI
 172 authentication.info.totpNotSended               OTP could not been sent. Retry
 173                                                 later.
 174
 175 If 302 response has been received, then once user receives SMS message with
 176 the OTP code, client can continue by sending POST request with credentials
 177 USERNAME ":" PASSWORD OTP_CODE concatenated into one string and Base64
 178 encoded to new location
 179 <https://DOMAINNAME/as/processLogin?type=totp&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>.
 180
 181 If authentication succeeds, another 302 response with setting IPCZ-X-COOKIE
 182 cookie and redirecting to final SOAP service URL will be sent by server.
 183 Client can resubmit its original SOAP request to the new URL together with
 184 the cookie.
 185
 186 Otherwise 401 response with WWW-Authenticate: totp header and
 187 X-Response-message-code header with one of values defined above in HOTP method
 188 will be delivered to client.
 189
 190 Non-normative: The premium SMS costs CZK 3. The user can send `HELP' text to
 191 get more details or `STOP LOGINDEV' text to disable sending more codes. The
 192 destination SMS phone number is `90201' (available from Czech celular phone
 193 networks only). If the user sends the stop-message or looses his receiver or
 194 capability to receive premium messages, he will lose access to his data box
 195 effectively and the only remedy will be to ask for resetting credentials on
 196 Czech POINT meeting place.
 197
 198
 199 HTTP mobile key method
 200 ======================
 201
 202 A client sends a POST request to
 203 <https://DOMAINNAME/as/processLogin?type=mep-ws&applicationName=NAME&uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>
 204 with a user name and a special authentication code in a standard HTTP Basic
 205 authentication header. The NAME is an arbitrary string that will be displayed to
 206 a user on his mobile phone and it should identify the client process.
 207
 208 If the authentication succeeds, the server sends the NAME to an application in
 209 the user's mobile phone and asks the user for an confirmation. Otherwise it
 210 responds with a 401 error code. In the mean time, the server responds with
 211 a redirection to the client:
 212
 213 302 Found
 214 Set-Cookie: S-COOKIE=VALUE;
 215 Location: https://DOMAINNAME/as/mepWsStateUpdate
 216
 217 The client is supposed periodically request that location while sending the
 218 S-COOKIE cookie. The server will reply with a plain-text document consisting
 219 of "-1" string if an error occurred, or "1" if the user has not yet finished
 220 the confirmation. Or "3" if the confirmation process timed out.
 221
 222 In the mean time, the user is supposed to accept the confirmation request
 223 through the mobile application. Then the server sends a "2" text to the client.
 224
 225 Once the client receives "2" text, it repeats the first POST request including
 226 the Basic authentication header. This time it also attached the S-COOKIE
 227 cookie. Then the server sends a final 302 redirect:
 228
 229 302 Found
 230 Set-Cookie: IPCZ-X-COOKIE=VALUE2;
 231 Location: https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT
 232
 233 Then the client can send requests to normal ISDS API end point. The requests
 234 will be authenticated with the IPCZ-X-COOKIE cookie. The cookie is valid for
 235 30 minutes. The cookie can be invalidated by sending a GET request to
 236 <https://DOMAINNAME/as/processLogout?uri=https://DOMAINNAME/apps/DS/WEB_SERVICE_ENDPOINT>.
 237
 238 Non-normative: The mobile phone application is available for selected
 239 operating systems from the phone vendor application store only. The
 240 application and its protocol is proprietary.
 241
 242
 243 ISDS unavailability
 244 ===================
 245
 246 If server cannot serve clients, it returns SOAP Fault with HTTP code 503:
 247
 248 HTTP/1.1 503 Service Temporarily Unavailable
 249 Content-Length: 645
 250 Connection: close
 251 Content-Type: text/xml; charset=utf-8
 252
 253 <?xml version='1.0' encoding='UTF-8'?>
 254 <SOAP-ENV:Envelope
 255   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 256   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
 257   xmlns:xsd="http://www.w3.org/1999/XMLSchema">
 258   <SOAP-ENV:Body>
 259     <SOAP-ENV:Fault>
 260       <faultcode xsi:type="xsd:string">Probíhá plánovaná údržba</faultcode>
 261       <faultstring xsi:type="xsd:string">Omlouváme se všem uživatelům datových
 262 schránek za dočasné omezení přístupu do systému datových schránek z důvodu plánované
 263 údržby systému. Děkujeme za pochopení.</faultstring>
 264     </SOAP-ENV:Fault>
 265   </SOAP-ENV:Body>
 266 </SOAP-ENV:Envelope>