Skip to content

Latest commit

 

History

History
178 lines (160 loc) · 8.5 KB

redirectless.md

File metadata and controls

178 lines (160 loc) · 8.5 KB
Raw

Redirectless support

In PingFederate, you can configure mobile applications to authenticate through REST APIs as OAuth clients without needing to handle HTTP redirections. When authentication is complete, the applications receive an OAuth authorization code or access token, and possibly an OpenID Connect ID token.

Single-page web applications can also use redirectless mode if administrators configure them in PingFederate as authentication applications.

PingFederate configuration

  1. Follow the instructions at README.md to configure the Authentication API in PingFederate.
  2. In the administrative console, go to Applications > OAuth > Clients and add a new OAuth 2.0 client.
  3. On the new client, select the 'Allow Authentication API Redirectless Mode' check box ('Allow Authentication API OAuth Initiation' prior to 11.0).
  4. Select the 'Restrict Common Scopes' check box and the client's restricted scopes.
  5. Select the client's 'Allowed Grant Types'.

Usage

To use the redirectless flow:

  • Create an instance of the widget by providing PingFederate's base URL and the necessary options.
  • Create a configuration object to provide the necessary redirectless settings.
  • Call initRedirectless and pass the configuration object as an argument.

Here's an example:

var authnWidget = new PfAuthnWidget("https://localhost", { divId: 'authnwidget' });
var config = {
  client_id: 'test',
  response_type: 'token id_token',
  onAuthorizationSuccess: function (response) {
    console.log(response);
  },
  onAuthorizationFailed: function (response) {
      console.log(response);
  }
};
authnWidget.initRedirectless(config);

Configuration object

There are multiple options for creating the configuration object to initiate the redirectless flow:

Simple

Create a configuration object that contains the onAuthorizationSuccess function and the required attributes (such as client_id, response_type, etc.) used by the internal authorization request function. This option should support majority of deployments.

Advanced

Create a configuration object that contains the onAuthorizationRequest and onAuthorizationSuccess functions. This option is for advanced use-cases.

OAuth 2.0 Device Authorization Grant

Create a configuration object containing the onAuthorizationSuccess function and a flowType attribute set to PfAuthnWidget.FLOW_TYPE_USER_AUTHZ. This configuration initializes the Authentication API Widget to interact with PingFederate's user authorization endpoint. Optionally, the user_code attribute can be provided. If provided, it is passed to the user authorization endpoint as a query parameter, which will trigger a state where the user must confirm the code (rather than having to enter it). An example is present here.

Cookieless

The cookieless configuration allows the widget to operate without using HTTP cookies. The PingFederate OAuth 2.0 client must be configured appropriatly in order for this mode to work correctly.

By enabling this mode, the widget will handle the state management required by the cookieless functionality. The cookieless and stateHeaderName are attributes controlling this mode.

  • cookieless attribute is boolean, defaulting to false
  • stateHeaderName attribute specifices the header name to send the state back to PingFederate. If not specified the default X-Pf-Authn-Api-State value will be used.

An example of the cookieless configuration can be found below:

var config = {
  client_id: 'test',
  response_type: 'token',
  cookieless: true,
  stateHeaderName: 'X-Pf-Authn-Api-State',
  onAuthorizationSuccess: function (response) {
    console.log(response);
  },
  onAuthorizationFailed: function (response) {
      console.log(response);
  }
};

Callback function descriptions

onAuthorizationRequest function

This callback function is called during the authorization request. It has no arguments and it's expected to return a JavaScript Promise, which completes the authorization request call to PingFederate. PingAccess redirectless support.

Here's an example:

var config = {
  onAuthorizationRequest: function () {
    var url = 'https://localhost:9031/as/authorization.oauth2?client_id=test&response_type=token&response_mode=pi.flow'
    var options = {
      method: 'GET',
      credentials: 'include'
    }
    return fetch(url, options);
  }
}

The options attribute credentials: 'include' is required to ensure the browser correctly handles PingFederate's session cookie.

onAuthorizationSuccess function

This callback function returns the result of the transaction to the webpage containing the Authentication API widget. The protocol response is passed to this function as the first argument when the Authentication API widget calls it. PingAccess redirectless support.

Here is an example:

var config = {
  onAuthorizationSuccess: function (response) {
    console.log(response.access_token);
  }
};

onAuthorizationFailed function

This callback function returns the state of the Authentication API to the webpage containing the Authentication API widget when the authorization fails. The entire API state is passed to this function as the first argument when the Authentication API widget calls it. PingAccess redirectless support.

Here is an example:

var config = {
  onAuthorizationFailed: function (response) {
    console.log(response);
  }
};

Supported attributes

The internal implementation of onAuthorizationRequest function supports the following attributes: client_id, response_type, code_challenge, code_challenge_method, redirect_uri, scope, state, idp, pfidpadapterid, access_token_manager_id, aud, nonce, prompt, acr_values, max_age, login_hint, ui_locales, id_token_hint, claims_locales.

The client_id and response_type attributes are required if onAuthorizationRequest is not present or the flowType value is not PfAuthnWidget.FLOW_TYPE_USER_AUTHZ.

The key-value pairs will be appended to the authorization request URL, their values will be URL encoded, and arrays will be concatenated and URL encoded into one string.

Configuration object examples

OAuth 2.0 implicit

This code snippet demonstrates a simple OAuth 2.0 configuration used by the Authentication API widget redirectless flow.

var config = {
  client_id: 'test',
  response_type: 'token',
  scopes: ['a', 'b', 'c'],
  onAuthorizationSuccess: function (response) {
    console.log(response.access_token);
  },
  onAuthorizationFailed: function (response) {
      console.log(response);
  }
};

OpenID Connect

This code snippet demonstrates a simple OpenID Connect configuration used by the Authentication API widget redirectless flow.

var config = {
  scope: ['openid', 'profile', 'email', 'address', 'phone'],
  state: '3f05dd88-3e97-496f-ba04-50e36e7ee1a5', // must be generated per each request.
  client_id: 'test',
  response_type: 'id_token',
  onAuthorizationSuccess: function (response) {
    console.log(response.id_token);
  },
  onAuthorizationFailed: function (response) {
    console.log(response);
  }
};

OAuth 2.0 Device Authorization

This code snippet demonstrates how to configure the Authentication API Widget to interact with PingFederate's User Authorization endpoint

var pingfederateUrl = 'https://localhost'
var authnWidget = new PfAuthnWidget(pingfederateUrl, { divId: 'authnwidget' });
var config = {
  flowType: PfAuthnWidget.FLOW_TYPE_USER_AUTHZ,
  // the optional user_code parameter
  // user_code: "A1B2-C3D4",
  onAuthorizationSuccess: function (response) {
    console.log('success');
  },
  onAuthorizationFailed: function (response) {
    console.log('fail');
  }
};
authnWidget.initRedirectless(config);

Starting webpack-dev-server with redirectless support

To configure and start the webpack-dev-server with redirectless support:

  1. Update the demo server's index template file with a configuration object. Configuration object examples are available in the Configuration object examples section of this document.
  2. Execute the following command to start the webpack-dev-server and initialize the widget in redirectless mode: 
    OPERATIONMODE=redirectless npm run start
  3. In your browser, go to https://localhost:8443 to see the widget in action.