irmajs
This concerns documentation of a deprecated library. Please use
irma-frontend
instead. If you are looking for a library to manage yourirma server
using Node.js, you can use the JavaScript packages fromirma-backend
.
irmajs
can be used in the browser:
<script src="irma.js" defer></script>
as well as in Node or Webpack:
// ES modules
import * as irma from '@privacybydesign/irmajs';
// CommonJS
const irma = require('@privacybydesign/irmajs');
Its primary functions are startSession()
, which can start an IRMA session by sending a (unsigned or JWT) session request to an IRMA server, and handleSession()
, which given the output of startSession()
handles the remainder of an IRMA session.
Since version 0.2.0, irmajs
is converted into a wrapper of irma-core
and several irma-frontend-packages
plugins that makes it
backwards compatible with the irmajs
API. This makes it possible to update to the irma-frontend-packages
look and feel
without having to change your software.
Deprecated API features
Due to technical changes in IRMA, we had to make breaking changes when introducing version 0.2.0.
All changes are related to the function call handleSession
.
- Method
canvas
is not supported anymore. Please use the moduleirma-frontend
instead or make your own composition of plugins and layouts usingirma-core
. This also means the canvas related optionselement
andshowConnectedIcon
are deprecated. - Method
mobile
has the same behaviour as methodpopup
now. On mobile devices, the popup mode automatically detects whether a mobile device is used and then shows the user the option to open the IRMA app installed on the mobile device itself. It is now an explicit choice, so users can also get a QR on mobile devices instead (useful for tablets). - The option
disableMobile
is not useful anymore. This module does not have automatic redirects to other apps anymore without explicit user interaction. The option is therefore deprecated. - Because the explicit methods for mobile devices are deprecated, the undocumented exported function
detectUserAgent
and the undocumented exported structUserAgent
are also deprecated. An explicit distinction based on user agent is not necessary anymore. This is all handled internally now. - The option
returnStatus
is deprecated. Instead you can use the functionswaitConnected
andwaitDone
to detect yourself whether the session reached a certain status.
API reference
SessionStatus
A enum containing possible IRMA session statuses, defined as follows:
const SessionStatus = {
Initialized: 'INITIALIZED', // The session has been started and is waiting for the client to connect (scan the QR)
Connected : 'CONNECTED', // The client has retrieved the session request, we wait for its response
Cancelled : 'CANCELLED', // The session is cancelled, possibly due to an error
Done : 'DONE', // The session has completed successfully
Timeout : 'TIMEOUT', // Session timed out
};
handleSession()
irma.handleSession(qr, [options])
Please check the deprecated API features to see which options are deprecated since version 0.2.0.
Handle an IRMA session after it has been created at an IRMA server, given the QR contents obtained from the IRMA server (e.g. using startSession()
) to be sent to the IRMA app. This function can
- draw an IRMA QR,
- wait for the phone to connect,
- wait for the session to complete,
- retrieve the session result afterwards from the irma server.
Returns a promise that can resolve at any of these phases, depending on the options:
Option | Default | Effect |
---|---|---|
method | 'popup' | Supported methods: 'popup' , 'canvas' , 'mobile' (only browser), 'console' (only node), 'url' (both) |
element | 'irmaqr' | HTML id of the canvas to draw to if method === 'canvas' |
language | 'en' | Popup language when method === 'popup' |
showConnectedIcon | true | When method is 'popup' or 'canvas' , replace QR with a phone icon when phone connects |
returnStatus | SessionStatus.Done | When the session reaches this status control is returned to the caller |
server | '' | Server URL to fetch the session result when session is done. Implies returnStatus === SessionStatus.Done |
token | '' | Session token required to fetch the session result when session is done |
resultJwt | false | Retrieve signed session result from the irma server |
disableMobile | false | Disable automatic navigation to IRMA app on mobile |
The following method
s are supported:
popup
: Draw a popup overlay with the QR and a cancel button in it.canvas
: Draw the QR into the HTMLcanvas
specified by theelement
option.mobile
: For mobile browsers, open the IRMA app directly instead of drawing a QR. Note that this mode is default when runningirmajs
in a mobile browser, even if you specify another method. You can disable this behavior and use your ownmethod
by settingdisableMobile
to true.console
: Draw the QR into the console.url
: Return the QR as a data URL (for in animg
HTML tag). ImpliesreturnStatus = SessionStatus.Initialized
.
What the promise returned by this function receives depends on the options as follows:
- If the
server
andtoken
options are not provided then the session status is returned. - If the
server
andtoken
parameters are given, containing a URL to an IRMA server and the session token at the IRMA server, respectively, then the session result is retrieved from the IRMA server. In that case, the promise returned by this function receives one of the following:- If
resultJwt
isfalse
(default), aSessionResult
message as returned by theGET /session/{token}/result
endpoint of theirma server
. - Otherwise, a session result JWT as returned by the
GET /session/{token}/result-jwt
endpoint of theirma server
.
- If
If the session is not successful, an exception is thrown. If the session is cancelled or times out, the message will be SessionStatus.Cancelled
or SessionStatus.Timeout
.
The session is cancelled and receives status
SessionStatus.Cancelled
not only when the IRMA app user refuses, but also when the session is aborted due to an error. In each of these cases an exception is thrown. Check its error argument.
If the session is cancelled due to the user aborting, it is (by design) not possible to distinguish between (1) the user had the requested attributes but refused to disclose them, and (2) the session was aborted by the user's IRMA app because (s)he did not have the required attributes.
startSession()
irma.startSession(server, request[, method, [key[, name]]])
Start an IRMA session at an IRMA server. This function supports all authentication methods of the POST /session
endpoint of the irma server
. It returns a promise with the response (the session QR contents) from the IRMA server (which can be handled by handleSession()
).
Parameters:
server
: URL to IRMA server at which to start the session.request
: Session request, either a JWT or an (extended) session request (see below).method
: authentication method (supported:none
,token
,hmac
,publickey
; default isnone
).key
: API token or JWT key.name
: name of the requestor (only forhmac
andpublickey
mode).
The authentication method is determined by the request
and method
parameters as follows.
- If
request
is astring
then it is posted as a session request JWT to the IRMA server. In this case, themethod
parameter needs to be set appropriately (hmac
orpublickey
). - Otherwise it should be an
object
containing an (extended) session request. How it is handled depends onmethod
:none
: it is POSTed as JSON to the IRMA server (which must be configured to accept unauthorized session requests).token
: it is POSTed as JSON to the IRMA server along with thekey
parameter as an API token in a HTTP header.publickey
: it is first signed into a JWT with the specified RSA privatekey
in PEM, usingname
as the requestor name, and then POSTed to the IRMA server.hmac
: it is first signed into a JWT with the specified symmetric HMACkey
, usingname
as the requestor name, and then POSTed to the IRMA server.
signSessionRequest()
signSessionRequest(request, method, key, name)
waitConnected()
waitConnected(url)
waitDone()
waitDone(url)