national_digital_identity__ndi___asp_api

NationalDigitalIdentityNdiAspApi - JavaScript client for national_digital_identity__ndi___asp_api This is the API store where you can discover everything about integrating with the National Digital Identity (NDI) platform. To try out the API, first go to the token endpoint section to learn how to obtain an access token to access the API. # Release Notes * 0.3.2 (Release Date) * Initial release of API # Overview The Authentication Service Provider (ASP) is a key component of the NDI platform which performs authentication and authorization. Client apps accessing resources (API, data) in protected domains (e.g. Government agency, bank systems) may invoke the ASP to authenticate the end-user and obtain the access tokens to access the protected resources. Client apps invoke the ASP through an interface and interaction flows based on the widely supported OpenID Connect (OIDC) specifications. The ASP can be federated - it may be run and operated independently from the Government NDI cluster, e.g. a financial institution may run an instance of ASP on its platform to serve the needs of its applications.

The ASP may be operated in the 2 modes - as an OIDC Provider, or as a pure-play authenticator. The operating modes will decide how relying parties (i.e. the client app) and the Authorization Server of the federated site interact with the ASP. In both modes, the ASP is only responsible for authenticating the user and generates the ID token, it is the organization's Authorization Server which determines whether the relying party and the user are authorized to access its protected resources and issues the access token accordingly. ## Mode 1: ASP as an OpenID Connect Provider <img style="width:50%; margin-left:auto; margin-right:auto; display:block" src="../img/openIDProvider.png"/> The ASP acts as an OIDC Provider, handling the OIDC flow with the relying party. This operating mode is useful for organizations which are planning to expose their capabilities through API and may not have a OAuth 2.0/OIDC enabled Authorization Server. During the OIDC flow, the ASP performs user authentication with the user's NDI form factor, on successful authentication, it calls the organization's Authorization Server to obtain an access token. The Authorization Server determines whether the relying party and user has proper access (based on the organization's access policy) and generates the access token accordingly. The ASP returns the access token to the relying party which may then use it to access protected resources.

In this operating mode, the ASP integrates with the Authorization Server of the organization through the Domain Authorization Interface. ## Mode 2: ASP as an Authenticator <img style="width:50%; margin-left:auto; margin-right:auto; display:block" src="../img/authenticator.png"/> The ASP acts as an authenticator service which the Authorization Server calls to perform user authentication with the user's NDI form factor. This operation mode is applicable for organizations which are already offering OAuth 2.0 or OIDC based authorization to relying parties accessing their protected resources. In this scenario, organizations typically use an Authorization Server (or IAM) module to handle the OAuth 2.0/OIDC flows with relying parties. During the OAuth 2.0/OIDC flow, the Authorization Server module calls the ASP authentication API to perform user authentication with the user's NDI form factor. On successful user authentication, the Authorization Server determines whether the relying party and user have the proper access (based on the organization's access policies), then generates and returns an access token to the relying party which it uses to access protected resources.

In this operating mode, the Authorization Server of the organization will integrate with the ASP through the ASP Authentication API. This SDK is automatically generated by the Swagger Codegen project:

• API version: 0.3.2
• Package version: 0.3.2
• Build package: io.swagger.codegen.languages.JavascriptClientCodegen

Installation

For Node.js

npm

To publish the library as a npm, please follow the procedure in "Publishing npm packages".

Then install it via:

npm install national_digital_identity__ndi___asp_api --save

Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

Finally, switch to the directory you want to use your national_digital_identity__ndi___asp_api from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

You should now be able to require('national_digital_identity__ndi___asp_api') in javascript files from the directory you ran the last command above from.

git

If the library is hosted at a git repository, e.g. https://github.com/YOUR_USERNAME/national_digital_identity__ndi___asp_api then install it via:

    npm install YOUR_USERNAME/national_digital_identity__ndi___asp_api --save

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file, that's to say your javascript file where you actually use this library):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Getting Started

Please follow the installation instruction and execute the following JS code:

var NationalDigitalIdentityNdiAspApi = require('national_digital_identity__ndi___asp_api');

var api = new NationalDigitalIdentityNdiAspApi.AuthenticationApi()

var clientId = new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(); // {ERRORUNKNOWN} The client id of the calling client app.

var nonce = new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(); // {ERRORUNKNOWN} A random unqiue reference generated by the client, which will be included in the ID token returned by the ASP on successful user authentication. The client may use this to tie the ID token to a particular authenticated session.

var opts = { 
  'scope': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} The scope of access requested for, this is a string of space- delimited references representing protected resources;
  'responseType': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} The response type, may be code or idtoken. Default to code if not specified.
  'state': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} The random string generated by the client to counter CSRF, if specified, the ASP will include it as part of the redirect url when returning the authorization code to the client's redirect uri.  The client is to match the value of the state returned with its copy to ensure the redirect is from the ASP.
  'acrValues': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} {Description to be added}
  'ndiId': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} {Description to be added}
  'prompt': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN(), // {ERRORUNKNOWN} {Description to be added}
  'display': new NationalDigitalIdentityNdiAspApi.ERRORUNKNOWN() // {ERRORUNKNOWN} {Description to be added}
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
};
api.initiateAuth(clientId, nonce, opts, callback);

Documentation for API Endpoints

All URIs are relative to https://localhost

Class	Method	HTTP request	Description
NationalDigitalIdentityNdiAspApi.AuthenticationApi	initiateAuth	GET /v1/asp/auth	Initiate user authentication or authorization (GET)
NationalDigitalIdentityNdiAspApi.AuthenticationApi	initiateQRAuth	POST /v1/asp/responses/qrcodes	QR Code Authentication
NationalDigitalIdentityNdiAspApi.AuthenticationApi	responses	POST /v1/asp/responses	Callback endpoint called by form factor
NationalDigitalIdentityNdiAspApi.AuthenticationApi	v1AspAuthLoginPost	POST /v1/asp/auth/login	Endpoint called by the NDI Login page
NationalDigitalIdentityNdiAspApi.CertificatesTokenConfigurationsApi	getJwks	GET /v1/asp/certs	Get the JWK Set containing the ASP signing keys.
NationalDigitalIdentityNdiAspApi.CertificatesTokenConfigurationsApi	getOpenidConfig	GET /v1/asp/.well-known/openid-configuration	Get OpenID Connect Discovery document of this ASP
NationalDigitalIdentityNdiAspApi.CertificatesTokenConfigurationsApi	v1AspTokenPost	POST /v1/asp/token	Exchange for the security tokens (ID token and access token) with the authorization code obtained from the authorization endpoint.

Documentation for Models

Documentation for Authorization

All endpoints do not require authorization.