Visit Nexus to get an overview of Nexus' solutions, read customer cases, access the latest news, and more.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1

This article describes how to implement Nexus GO Authentication. Nexus provides authentication libraries for easier integration to the authentication service from your online application.

There is a demo application where you can try out the service. 

Step-by-step instruction

Link to Nexus GO

You can either add a link to Nexus GO authentication in a separate page, or insert the link in an iframe.

  1. Insert a link to the Method URL generated by Nexus GO.

    Link to Method URL
    <a href="{Method URL}">Log in</a>

Swedish BankID

If you want to use logotypes for Swedish BankID or Swedish Mobile BankID, you need to follow the BankID guidelines for logotypes: BankID - Logotyper (In Swedish).


With Safari on iOS version 13.4.1, Apple released an update regarding privacy. The browser will now block all third-party cookies, independent from the SameSite configuration. For more information, see

Due to this change, authentication with Nexus GO will not be usable within an iFrame anymore. 

The JavaScript library iFrame Resizer is required to change the height of the iframe in order to fit any messages. The height can be expected to change less than 100px.

  1. Download the library, and save it in your JavaScript file folder:
    File for download: iframeResizer.min.js
  2. On the login page, add code to insert an iframe, using the Method URL generated by Nexus GO. The iframe has a minimum width of 260px, and no maximum width. Also add code to use the JavaScript library to handle resizing of the iframe.

    Login page: Insert iframe
    <!DOCTYPE html>
            <meta charset="utf-8">
            <title>Log in</title>
            <!-- Handle resizing of the iframe using the JavaScript library -->
            <script src="js/iframeResizer.min.js"></script>
            <!-- Insert iframe -->
            <iframe src="{Method URL}" width="260" scrolling="no" onload="iFrameResize()"></iframe>
  3. Add a separate page that will be returned as the response from the Validation URL page. This page will break out of the iframe by redirecting the top frame to the welcome page, where logged-in users will be sent.

    Break out of iframe page
    <!DOCTYPE html>
            <meta charset="utf-8">
            <!-- Break out of iframe -->
            <script type="text/javascript">
       = "{Welcome page}";
  4. If you want to get messages from the iframe to the login page, use the setup in the following example. This enables hiding and showing a loading indicator animation, and viewing the state of the authentication process. See also the example in the demo application.

    Example: Advanced iframe settings using jQuery
    $(function () {
      'use strict';
      function registerIframeCallbacksWhenReady() {
        $('.nexus-iframe').on('load', registerIframeCallbacksOnce);
      function registerIframeCallbacksOnce() {
        $('.nexus-iframe').off('load', registerIframeCallbacksOnce);
      function registerIframeCallbacks() {
          messageCallback: function (messageData) {
            if (typeof messageData !== 'undefined'
                && typeof messageData.message !== 'undefined') {
              if (messageData.message.event === 'submitForm') {
                // "nexus-iframe" is about to reload
                // Hide the iframe and show the loading indicator
              } else if (messageData.message.event === 'log') {
          resizedCallback: function () {
            // "nexus-iframe" has initialized completely
            // Show the iframe and hide the loading indicator
        }, '.nexus-iframe');
      function handleLogMessage(message) {
        // State that the authentication process is currently in (see below for details)
        console.log('message.state        ' + message.state);
        // Text that is being presented to the user, if applicable
        console.log('       .text         ' + message.text);
        if (message.state === 'requesterror') {
          // Possibly more specific error reason from the Ajax request, if applicable
          console.log('       .ajaxReason   ' + message.ajaxReason);
          // HTTP response status code for the Ajax request, if applicable
          console.log('       .httpStatus   ' + message.httpStatus);
          // HTTP response body for the erroneous Ajax request, if applicable
          console.log('       .httpResponse ' + message.httpResponse);
        Possible "log" event states:
        initerror     An error was received by the server upon loading the page;
                        this error will be shown to the user
        requesterror  A request to the server couldn't be completed normally;
                        an "initerror" state will follow
        autostart     An attempt will be made to automatically launch the
                        BankID app on this device
        startfailed   The BankID app was not started on this mobile device in the
                        allotted time; the user will be allowed to enter their
                        personal number manually
        continue      Waiting for the user to launch their BankID app manually
        started       A BankID app was launched following the "autostart" state, but the
                        app has not yet found a usable BankID profile on the device
        sign          Waiting for the user to authenticate with their BankID profile
        done          Authentication completed, either successfully or not;
                        if unsuccessful, an "initerror" state will follow
    // The actual iframe:
    // <iframe class="nexus-iframe" width="260" scrolling="no" src="{Method URL}"></iframe>
  5. Because the Method URL page which is on the domain is separate from the login page and needs to use cookies during the authentication, placing it inside an iframe means that its cookies will be seen as third-party cookies by the browser. Some browsers with stricter privacy settings may reject these cookies if it doesn't already have a first-party cookie from that domain. So to improve reliability across different browsers we recommend login links to go via our bounce page, which will set a first-party cookie and immediately redirect the end-user to the actual login page. There are a few approaches to achieve this.

    1. Use the bounce page in all links to the login page containing the iframe.[note 1]

      Link to Login page URL via Nexus GO bounce page
      <a href="{Login page URL}">Log in</a>
    2. Use a server-side HTTP redirect to send the end-user to the login page via the bounce page. Example flow:
      1. End-user requests the login page at
      2. Server examines the path seeing that no query parameter is present, the server responds with a HTTP redirection[note 1]

        Server side redirect via Nexus GO bounce page
        HTTP/1.1 302 Found
      3. End-user reaches the bounce page, which sets the first-party cookie and immediately redirects back to the destination URL given
      4. End-user reaches the destination URL, which is the page
      5. Server examines the path seeing that the query parameter is present, it displays the page as normal, which includes the iframe
    3. Use a client-side JavaScript redirect to send the end-user to the login page via the bounce page.[note 1] This approach is the same as for b. above, except that the logic is instead performed by JavaScript, which decides whether to display the login page or redirect via the bounce page.

      JavaScript redirect via Nexus GO bounce page
      (function () {
        'use strict';
        function isBounced() {
          var params = parseQueryString();
          return params.showLoginForm === 'true';
        function parseQueryString() {
          var plusPattern = /\+/g;  // Plus character is a space in application/x-www-form-urlencoded
          var keyvalPattern = /([^&=]+)=?([^&]*)/g;
          var decode = function (s) { return decodeURIComponent(s.replace(plusPattern, ' ')); };
          var query =;
          var keyvals = {};
          var match = keyvalPattern.exec(query);
          while (match) {
            keyvals[decode(match[1])] = decode(match[2]);
            match = keyvalPattern.exec(query);
          return keyvals;
        if (isBounced()) {
          // Show the iframe containing the login form
        } else {
          window.location = '';

    Note 1

    The destination query argument should have all characters with delimiting roles for the query component (& and #) percent-encoded (%26 and %23, respectively), as they would otherwise have ambiguous delimiting roles. Alternatively, encode the entire destination query argument using application/x-www-form-urlencoded.

Swedish BankID

If you want to use logotypes for Swedish BankID or Swedish Mobile BankID, you need to follow the BankID guidelines for logotypes: BankID - Logotyper (In Swedish).

The Nexus GO authentication uses cookies, to handle the session to the back-end system.

  1. If you do not already inform your end-users about the use of cookies, you must do that to follow the EU legislation on cookies

Validate response from Nexus GO

  1. Download the Authentication library that suits your platform.
  2. Unzip the library package and save the library file in your developing environment, for example the PHP project folder.

    Each package contains:
    • Nexus GO authentication library
    • API documentation
    • Demo application - For testing the libraries in .NET and PHP
    • Readme file - Contains detailed information on files, folders, and how to use the demo application
  1. In Nexus GO, go to Services and then Authentication.
  2. Click on the environment that you want to protect with authentication, and then How to implement.
  3. Download the metadata XML files: sp.xml and idp.xml. Save the files in the metadata folder in the developing environment.
  1. Initialize the authentication library with the metadata files. The method reads sp.xml and idp.xml from the folder metadata, as specified in the argument.

    Java example
    try {
        Path conf = Paths.get("metadata");
        librarySamlEngine = LibrarySamlEngine.initialize(conf);
    } catch (SamlEngineException e) {
        logger.error("Failed to initialize SAML engine", e);

    .NET example
        SamlEngine = LibrarySamlEngine.Initialize("metadata");
    catch (SamlEngineException e)
        WriteToEventLog(e.Message, EventLogEntryType.Error);

    require_once 'saml-validation.phar';
    final class LibrarySamlEngineHolder
        public static function Instance()
            static $inst = null;
            if ($inst === null)
                $inst = LibrarySamlEngine::initialize("metadata");
            return $inst;
        private function __construct()

    For a list of possible initiation errors and proposed solutions, see Initiation errors.

When the end-user has authenticated using the Method URL, the authentication response will be sent to the Validation URL as a HTTP POST request.

  1. On the Validation URL, add code to validate the authentication response.

    Java example
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        String samlResponse = req.getParameter("SAMLResponse");
        try {
            Result result = librarySamlEngine.validateSamlResponse(samlResponse);
            HttpSession session = req.getSession(true);
            session.setAttribute("userId", result.getNameID());
            session.setAttribute("method", result.getAuthnContextClassRef());
            // SAML attributes
            for (String key : result.getAttributes().keySet()) {
                session.setAttribute(key, result.getAttributes().get(key));
            String contextPath = req.getServletContext().getContextPath();
            // If an iframe is used, link to the "iframe break-out" page here
            resp.sendRedirect(contextPath + "/welcome");
        } catch (SamlEngineException e) {
            resp.sendError(HttpServletResponse.SC_BAD_REQUEST, e.getMessage());

    .NET example
    public async Task<ActionResult> Login(LoginViewModel model, string returnUrl)
        if (!ModelState.IsValid)
            return View(model);
            Result result = SamlEngine.ValidateSamlResponse(model.SAMLResponse);
            var ident = new ClaimsIdentity(
                new[] {
                        new Claim(ClaimTypes.Name,result.NameID),
                        new Claim(ClaimTypes.AuthenticationMethod, result.AuthnContextClassRef)
                new AuthenticationProperties { IsPersistent = false }, ident);
                Session["AssertionID"] = result.AssertionID;
            Session["InResponseTo"] = result.InResponseTo;
            Session["ExpireTime"] = result.ExpireTime;
            // SAML attributes
            foreach (KeyValuePair<string, object[]> item in result.Attributes)
                Session[item.Key] = item.Value;
            // If an iframe is used, link to the "iframe break-out" page here
            return RedirectToLocal(returnUrl);
        catch (SamlEngineException e)
            LastError = e;
    1. Call the method validateSamlResponse() to process the authentication response. The method reads the response from the HTTP POST request and returns a result. A positive result is stored in the $result variable. If the validation of the authentication response fails, the method will throw an exception. Insert any links and error messages for successful and non-successful validations.

      PHP example
      require_once 'saml-validation.phar';
          require_once 'init.php';
          $result = LibrarySamlEngineHolder::Instance()->validateSamlResponse();
          setcookie("Result", serialize($result));
          // SAML attributes
          foreach (array_keys($result->getAttributes()) as $key)
              $_SESSION[$key] = $result->getAttributes()[$key];
          // If an iframe is used, link to the "iframe break-out" page here
          header('Location: '.$uri.'index.php');
      catch (Exception $e)
          echo "[", $e->getCode(), "] ", $e->getMessage(), "\n";
          if ($e->getPrevious())
              echo " - ", $e->getPrevious()->getMessage();

    Example of a successful result:

    Example: Successful SAML response in .NET
    Name ID: 198901023286
    Authn context:
    Assertion ID: _7c8d6bdc3822afcebf0d93465a97a134
    Expiretime: 1485938846
    InResponseTo: _7d62a8736643eee397f4feae033ff0e6
    Relay state: abc12345
    commonName: Agda Andersson
    givenName: Agda
    surname: Andersson
    serialNumber: 198901023286
    countryName: SE
    issuerCommonName: Example Bank
    issuerOrganizationName: Example Bank AB
    issuerCountryName: SE

    The following attributes are available in the result:



    Common name


    Given name


    serialNumberPersonal identification number


    Country name


    Common name of the client certificate issuer


    Organization name of the client certificate issuer


    Country name of the client certificate issuer

For a list of possible validation errors and proposed solutions, see Validation errors.

Brand the login page or iframe

The Nexus GO login page or iframe can be branded, by providing a .css style sheet to Nexus.

Without a provided style sheet, then you will get an error message in the browser console:

Example: 404 error message
Failed to load resource: the server responded with a status of 404 (File Not Found)

To provide a .css style sheet with overridden rules for branding the login page or iframe:

  1. Create your own .css style sheet.
    See the default style sheet here:
  2. Give the file the same filename as mentioned in the 404 error message, for example:

    Example: .css file name Swedish Mobile BankID dga5st2nq6s4nvq.css
  3. Provide the .css file to Nexus. Ask your Nexus contact person for details.
  • No labels