uaa-singular v1.45.0

UAA Singular Login for Web Applications

Singular is a Javascript module that enables web applications to easily identify a user via their authenticated browser session at the UAA identity server. Singular has no external client-side dependencies, and the latest version of Singular will work with UAA 4.10.0 and later.

License

Singular is licensed under the Apache License, Version 2.0.

Compatibility

Singular should work with any web browser which supports Javascript localStorage, postMessage, and DOMContentLoaded, which includes these versions of major desktop browsers.

41+ ✔	17+ ✔	11+ ✔	28+ ✔	9+ ✔	12.0+ ✔

Server-side Prerequisites

OAuth client setup

Singular requires a configured OAuth client in the UAA which requires at least the following properties. For more information about creating clients in the UAA, see the API documentation.

For the example index.html, you will also need to add http://<singular-domain>/index.html to the redirect_uri configuration. /PATH/TO/SINGULAR/ should be updated to reflect the path to your singularLocation, which is the static assets directory where singular.js and associated html files are served from your app.

Alternatively, you can provide http://<singular-domain>/** as the redirect_uri if you believe you will not have any concerns about redirecting users to any path location within your domain.

UAA version compatibility

Installing Singular

The uaa-singular package can be downloaded with the command: npm install uaa-singular

This will create the node_modules directory in your current directory (if one doesn't exist yet) and will download the package to that directory.

Using Singular

To enable Singular login on a page, include the main script in the header:

    <script type="application/javascript" src="node_modules/uaa-singular/singular/singular.js"></script>

Then use the Singular.init method to configure and start the authentication. The call to Singular.init can occur anywhere in the DOM.

<script type="application/javascript">
  Singular.init({
    // Static assets directory where singular.js and associated html files are served from your app
    singularLocation: './node_modules/uaa-singular/singular/',
    clientId: 'exampleClient',
    uaaLocation: 'https://login.example.com',
    onIdentityChange: function (identity) {
      // perform custom login behavior
    },
    onLogout: function () {
      // perform logout behavior
    }
  });
</script>

Getting an access token

It is possible to obtain an access token using sungular library. Use Singular.access function to do that. This function returns a promise

var tokenPromise = Singular.access('resource.read,someotherscope');
    tokenPromise
      .then(function(token){
        console.log("Access token with resource.read and someotherscope scopes: " + token )
      })
      .catch(function(error){
        console.log("Error: " + error )
      })

Make sure client has scopes resource.read and someotherscope.

Define all custom behavior for the application in onIdentityChange. The argument passed to this callback will either be an object containing the identity claims of the logged-in user, or null indicating a logout. The application should treat this identity idempotently, as this callback may be invoked many times in the lifetime of the page as users log in and out of the UAA. The properties available for configuration in Singular can all be passed as fields in the argument of init.

Running the tests

npm run get-uaa
npm run start-uaa
npm run start-singular-app
npm test

start-uaa and start-singular-app spawn background processes. Be sure to run npm run stop-uaa and npm run stop-singular-app when finished.