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.sqrl  -or-  /nut.sqrl?{1-9}PUBLIC
Purpose:Obtain an authentication nonce, known through SQRL's documentation as a “nut”, and cancellation URL for this browser session and logon page.
Opt Params:
1-9=May optionally provide a single digit 1-9 ('0' is equivalent to none) which invokes SQRL's path extension feature for the authentication. This creates separate authentication domains within a single host domain. This is useful if a single domain hosts separate services where visitors have separate identities.
sin={ a string naming a “secret index” for the server (see semantics spec.) }
ask={ a string specification for a SQRL client ask prompt (see semantics spec.) }
Returns:nut={ 12-character nonce }&can={ base64url-encoded version of the query's Referer header }
May Return:x=n&nut={ 12-char nonce }&can={ encoded Referer header } when path extension is present and 'n' will be the parameter digit provided to query.
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” when no page change is needed, Or a “200 OK” with the 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={ comma-delimited list of zero or more tokens }
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.
The stat= parameter's tokens are defined below under “API parameter notes.”
 
/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={ comma-delimited list of zero or more tokens }
name={ up to 64-character username handle }
Returns:The updated list of SQRL users associated with the account.
Usage:If the SQRL user is not already known to the system, SQRL authentication creates a unique but temporary SQRL ID for a user. If the webserver wishes to make this SQRL ID permanent or to create a permanent association with its own account, it must issue this /add.sqrl? query with a non-null acct= parameter which does not need to be unique.
   In normal use, 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 Param:
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.
Note that SQRL associations should be removed with this /rem.sqrl? query when the associated website account is deleted. This releases resources for this user in the SSP API database.
 
/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={ comma-delimited list of zero or more tokens }
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.

The stat= parameter's value consists of a comma-delimiter list of zero or more string tokens each of whose presence or absence conveys user SQRL client or user account status to and from the hosting website. The list of standard tokens, and their meaning is:

• sqrlonly:The user's SQRL client has been configured to ask websites to disable all other non-SQRL means of visitor identification and logon.
• hardlock:The user's SQRL client has been configured to ask websites and website staff refuse any and all requests to help the user recover ANY means of identity authentication (both SQRL and non-SQRL).
• disabled:The user has disabled SQRL logon access to this website. This status will be received from the /cps.sqrl? query. The website should display an acknowledgement to the user and the user's logged-on state is not changed by this: If the user is currently logged-on they remain logged on.
• remove:The user has requested a removal of their SQRL identity from this website. This status will be received from the /cps.sqrl? query. The website should display an acknowledgement to the user. The website should usually comply with the user's request, but if the user has no backup means of authenticating and signing into the website the site may allow the user to choose to abort the removal at this time. If the web server removes the user's SQRL association it must also issue a /rem.sqrl? query to the SSP API to delete the user from the SSP database.
 • rekeyed:The user's SQRL identity has been rekeyed since its previous authentication. This may be significant to high-security websites which might ask the user if they wish to invalidate other web browser sessions.
• acctownr:This user is the “owner” of the account. This is used to support SQRL's managed shared access (MSA) features.
• acctmngr:This user is a “manager” of the account. This is used to support SQRL's managed shared access (MSA) features.

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: Mar 07, 2019 at 14:20 (12.35 days ago)Viewed 12 times per day