SQRLSQRL
100x100 SQRL Logo   Secure Quick Reliable Login
A highly secure, comprehensive, easy-to-use replacement
for usernames, passwords, reminders, one-time-code
authenticators . . . and everything else.
divider
SQRL Service Provider API

SQRL's Service Provider (SSP) API defines a proven application programming interface to support the externalization of SQRL services from the relying website. Although it is foreseeable that server-specific add-ons will also be created to allow web servers to provide native support for SQRL, there will be instances where SQRL authentication services are more naturally provided by an external API server.

ssapi diagram

As shown in the diagram above, each of the four components communicates with the others. The SQRL SSP API server may reside on the same domain as the website server, fielding all queries for objects with the .sqrl extension, it may reside on a subdomain as shown in the example above, or it may reside on an entirely separate domain.

SSP API Overview

The SSP API minimizes the work required to add SQRL support to an existing web server. The API replies to web browser queries for SQRL assets on sign-in pages, performs all SQRL protocol transactions with SQRL clients, and uniquely identifies authenticated SQRL users to web servers.

The API also maintains a database that can be used to associate SQRL users to the web server's accounts. When this is done, a SQRL authentication of any previously associated user will return the web server's account directly, eliminating the need for a web server's database to be altered to accommodate SQRL authentication.

The SSP API fully supports SQRL's Managed Shared Access (MSA) feature set with invitations and many-to-one SQRL-to-account mapping with permissions and user management. These features can be explored at the MSA demonstration site: https://sqrl.grc.com/msa which was entirely built using this SSP API.

Using the SSP API, authentication proceeds as follows:

1trA login webpage is delivered to the user's browser by the website's server. This will usually include a unique session cookie to identity the user's browser to the web server.
1trThe logon webpage contains SQRL support javascript (a sample is here) which issues an SSP query for /nut.sqrl to initiate an authentication session and obtain a nonce (the SQRL “nut”) to use in referencing the forthcoming authentication.
   The javascript adds the “nut” parameter to the /png.sqrl query to display a corresponding SQRL QR code image. It also dynamically sets the URL of the page's “Click to sign in with SQRL” button.
   Once this is done, the page's javascript begins polling the SSP server with periodic /pag.sqrl queries for any post-authentication page to display.
1trAt this point, authentication begins when the user either clicks the sign in button or scans the displayed QR code with a smartphone:
  • Clicking the sign in button invokes the user's locally-installed SQRL client using the sqrl:// scheme, which the client registers with its operating system. This causes the web browser page to jump to the SQRL client's localhost web server which listens on port 25519. This allows the web browser to eventually receive an HTTP 302 Redirect to the web server containing the 24-character client provided session (CPS) token received at successful authentication.
       This CPS token passing—from the SSP server to the user's local SQRL client to the user's local web browser and finally to the web server—eliminates any possible man-in-the-middle to prevent logon spoofing and interception attacks.
  • Scanning the QR code with a SQRL smartphone client picks up the URL of the SSP server and causes the authentication to proceed between smartphone and SSP server. Once successful, the logon page's periodic probes for /pag.sqrl will finally return a 24-character token causing the user's browser to jump to the web server to display a logged-on page to the user.
1trStepping back a bit to point #3 above... Once authentication is initiated, a locally installed or smartphone SQRL client interacts with the SSP server using SQRL's authentication protocol to establish the logging-on user's identity.
   Upon successful authentication with a local SQRL client, the SSP API returns a 24-character CPS (Client Provided Session) authentication token to the SQRL client. The client then responds to the user's waiting browser with a 302 Redirect to a previously configured web server URL, supplying the 24-character token to the web server. This provides a secure assertion of the user of this web browser since the only way the browser could have received the CPS token was from the local SQRL client.
   Upon successful authentication with a mobile client, the browser's periodic /pag.sqrl query returns the same previously configured URL, with the 24-character authentication token, to which the browser should jump.
   
1trUpon receiving the incoming authentication query from a web browser, the web server forwards the 24-character authentication token it received in the browser query to the SSP server by issuing an /cps.sqrl query containing the token. The SSP server replies with the authenticated identity information it has for the user, including any web server account which might be associated with the user. This ends the authentication session and the transient transaction is deleted from the SSP server. The web server can then sign this user in and jump their browser to any signed-in landing page.
SSP API Protocol Diagram

The diagram below depicts the sequential interaction among the four network components described above. You may click this link to view a full-size much more legible diagram. The diagram is split horizontally into four bands, with the top and bottom sections always executed, and either the second or third section used depending upon whether the authentication is with a locally installed or a mobile SQRL client, respectively.

ProtoFlow
SSP API Details

The SSP API uses a standard HTTP query/reply interface with URL-safe parameters, when required, appended to the query as standard application/x-www-form-urlencoded name=value pairs. Each of the queries is defined and described below:

To aid understanding, the four SSP API sections below are presented in the approximate order of their use during a SQRL authentication process:

Web Browser  to  SSP Server
/nut.sqrlPUBLIC
Purpose:Obtain an authentication nonce, known through SQRL's documentation as a “nut”, and cancellation URL for this browser session and logon page.
Params:None.
Returns:nut={ 12-character nonce }&can={ base64url-encoded version of the query's Referer header }
Usage:The logon page's javascript issues this query once upon loading to obtain the parameter string which is added to the “Click to sign in with SQRL” URL and the page's CPS-trigger query. (See the SQRL protocol specification for more background and sample javascript here.)
   The “nut={ 12-character nonce }” portion, which uniquely identifies this new authentication session, is also extracted from the returned string and used as the session “nut” parameter for the following two browser queries:
 
/png.sqrl?{ 12-char nut }PUBLIC
Purpose:Obtain an optical QR code image encoded with the authentication nut for this browser session.
Param:nut={ 12-character nut }
Returns:A binary object with a mime type of image/png.
Usage:SQRL logon pages typically offer a QR code for use with smartphone-based SQRL clients. This image reference should be embedded into a page to display the QR code.
 
/pag.sqrl?{ 12-char nut }PUBLIC
Purpose:Periodically query the SSP server for a new page to display.
Param:nut={ 12-character nut }
Returns:Either an HTML “404 Not Found” or a URL for the page's javascript to jump the browser to.
Usage:The logon page's javascript periodically issues this query while waiting for a SQRL authentication to succeed. A return of 404 Not Found causes a reissue of the same query after a delay. (See the sample javascript here.)
 
SQRL Client  to  SSP Server
/cli.sqrl?{ 12-character nut }PUBLIC
Purpose:This is the SQRL client query URL used with HTTP POSTs for the SQRL protocol. SQRL clients send their authentication queries to this URL.
Param:nut={ 12-character nut }
Returns:A multiline block of HTML form-encoded data following the SQRL protocol.
Usage:SQRL clients use this query for their transactions with the SSP server. The initial nut used is the value returned by the /nut.sqrl query and embedded within the /png.sqrl image. The logon page's javascript uses the nut returned by the /nut.sqrl query to form the sqrl:// URL assigned to the page's “Click to sign in with SQRL” button. (See the SQRL protocol specification for more background and sample javascript here.)
 
Web Browser  to  Web Server
{ configured URL }?{ 24-character authentication token }PUBLIC
Purpose:The web browser jumps to the pre-configured URL on the web server to inform the web server of a successful SQRL authentication.
Param:nut={ 24-character authentication nonce }
Returns:An HTTP 302 Redirect reply to the web browser.
Usage:When the web server receives this query, the user has successfully authenticated with SQRL and the user's web browser is waiting to receive the URL of a logged-on landing page. The web server uses the SSP API /cps.sqrl query (see next item below), passing it the 24-character nonce it received from the browser's query, to obtain the SQRL user's account information. This allows the web server to sign the user into an account, and the web server then replies with an HTTP 302 Redirect to the logged-on page.
 
Web Server  to  SSP Server
/cps.sqrl?{ 24-character CPS nonce } PRIVATE 
Purpose:The web server obtains SQRL user and account information with this query.
Param:The 24-character authentication nonce obtained from the web browser.
Returns:user={ 12-character unique user identifier }
stat={ up to 64-character general purpose string }
name={ base64url-encoded URL of the authentication logon page }
May Return:acct={ up to 64-character web server account ID }
Usage:When SQRL authentication is successful, the web browser jumps to the web server carrying a 24-character authentication nonce. The web server then issues this /cps.sqrl?... query to the SSP server with the 24-character nonce as its sole parameter. The SSP server replies with either the three or four parameters to identify the authenticated user. This allows the web server to log the user on and then reply to it with an HTTP 302 Redirect to a logged on page.
 
/add.sqrl?{ parameter list described below } PRIVATE 
Purpose:Add or update associations between SQRL user and web server account.
Req Params:
acct={ up to 64-character web server account ID }
Opt Params:
user={ 12-character unique user identifier }
stat={ up to 64-character general purpose string }
name={ up to 64-character username handle }
Returns:The updated list of SQRL users associated with the account.
Usage:This query will almost always be used to add SQRL user and web server account associations. So both the acct= and user= parameters will be present. However, to support managed shared access, it can also be used before a SQRL user has been associated to the web server account. In that case, the user= parameter will be omitted and the name= parameter will be used in its place.
   If an existing entry is being updated when the stat= or name= parameters are not present, their values will not be changed. But if they are present with a null value, their values will be set to null. An association's SQRL user cannot be changed once set. In the unlikely event that a SQRL user would be changing their account association, they would first be removed (see the /rem.sqrl query) then re-associated.
 
/rem.sqrl?{ parameter list described below } PRIVATE 
Purpose:Remove one or more SQRL / web server account associations.
Req Params:
user={ 12-character unique user identifier }
-or-
acct={ up to 64-character web server account ID }
Opt Params:
name={ up to 64-character username handle }
Returns:The updated list of SQRL users associated with the account.
Usage:This query can be called in any one of three ways:
  • If the user= parameter is present its specification is guaranteed to be unique so that SQRL user's account association will be deleted. If no user= parameter is present, the acct= and optional name= parameters will be used.
  • If name= is not present, all SQRL associations for that account will be removed. This is useful when a web server's account is being deleted so that all of its possible SQRL associations will also be deleted.
  • If a name= is present along with acct= then only the matching named SQRL association will be removed. This is useful for operations supporting SQRL's managed shared access.
 
/lst.sqrl?{ one of the three parameters below } PRIVATE 
Purpose:List all SQRL users associated with the indicated web server account, the SQRL user or a pending invitation.
Req Params:
acct={ up to 64-character web server account ID }
-or-
user={ 12-character unique user identifier }
-or-
invt={ 20-digit outstanding invitation code }
Opt Params:None
Returns:If acct= is provided, returns the current list of SQRL users associated with the account. Otherwise, if user= is provided, return the user's association record, if any. It invt= is provided, return any record with a matching outstanding invitation.
Usage:This query may be of interest to the web server for various purposes. However, it is primarily intended to support SQRL's managed shared access features where a list of all SQRL users with associations to a given account need to be known and displayed. The return for this, as for the /add.sqrl and /rem.sqrl queries, is a textual list containing one entry per line having this format:
     user={...}&acct={...}&name={...}&stat={...}&invt={...}
 
/inv.sqrl?{ parameter list described below } PRIVATE 
Purpose:Create and register a new pending invitation for a SQRL user to join the indicated web server account.
Req Params:
acct={ up to 64-character web server account ID }
name={ up to 64-character username handle }
stat={ up to 64-character general purpose string }
Opt Params:None
Returns:The 20-digit invitation assigned to the pending account.
Usage:This query is used strictly for SQRL's managed shared access. An account manager issues an invitation to a SQRL user, receiving a 20-digit invitation code which is sent to the invitee out-of-band. The invitee authenticates with SQRL and rather than creating an account, provides the 20-digit invitation which authenticates their elligibility for addition to the existing account. This facility can be seen and explored at: https://sqrl.grc.com/msa
API Parameter Notes
 PUBLIC  versus  PRIVATE 
As noted above, the five web server to SSP server queries must be private and accessible only to the web server. This can be easily accomplished in any number of ways. The SSP private service might be bound to a network interface on a private, internal, non-public network. Or the SSP service could be bound to a non-standard firewalled port (55219 is the recommended default) with the assurance that this port is not publicly available. Alternatively or additionally this could be arranged by having the SSP API server check the IP address of the requesting machine ensure that it is the related web server, or that the query is coming from a machine on a non-routable (private) IP network.

Additionally:

SSP Configuration
The SSP API server requires the following configuration: The Web Server requires the following configuration:
Developer Responsibilities
Website developers who wish to add SQRL support to their existing servers need to:
  1. Establish an instance of the SQRL SSP API server so that it is privately web query-accessible to the web server, and so that the SSP API server is publicly accessible.
  2. Add to the web server's logon page: A SQRL QR code image asset (/png.sqrl) and javascript which sets the /png.sqrl's URL and “Click to sign in with SQRL” button, support local SQRL client usage and page auto-update polling (sample javascript is here).
  3. Add web server support for a browser URL which forwards the 24-character authentication nonce to the SSP server then redirects the web browser to a logged-on page.
  4. For account management, either add web server support for SQRL identity association or add support for those functions provided by the SSP API.
And that's it.
In Summary
Availability of the API


Secure QR Login (SQRL) Documentation:

Jump to top of page
Gibson Research Corporation is owned and operated by Steve Gibson.  The contents
of this page are Copyright (c) 2016 Gibson Research Corporation. SpinRite, ShieldsUP,
NanoProbe, and any other indicated trademarks are registered trademarks of Gibson
Research Corporation, Laguna Hills, CA, USA. GRC's web and customer privacy policy.
Jump to top of page

Last Edit: Jan 12, 2019 at 12:53 (3.58 days ago)Viewed 66 times per day