irmajs
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.
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])
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. - 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)