Action Token login

This guide will walk you through the process of generating and logging in with the use of the Action Token functionality.

What is required?

To successfully complete this topic guide you need to ensure following prerequisites:

  • Onegini IDP instance must to be running, for the sake of this guide we assume it's available under http://idp-core.dev.onegini.me address
  • access to Onegini IDP admin console
  • at least one user must be registered within Onegini IDP instance

Configuration

Enabling the feature

The Action Token feature toggle can be found in Onegini IDP admin console in Configuration > Features tab. To enable token based login functionality simply select the Action Token Login enabled checkbox.

Setting the Action Token validity time

Every Action Token that you generate has a predefined validity time (TTL) which needs to be defined in the admin panel. You can adjust this property value to the one that suits your use case most. Please note that the modified validity will have impact only on the newly generated tokens.

Defining the authentication level for the Action Token

Since the Action Token functionality allows users to log into the Onegini IDP system it also carries an information about the Authentication Level that is associated with it. By default the Action Token will derive this value from the Identity Provider instance configuration that it is related with the Username & Password Identity Provider, or Identity Provider instance that is pointed by the idp_id optional parameter when COUPLE_EXTERNAL_IDP_FROM_PARAMETERS action is performed. It is also possibly to define a custom Authentication Level specific to the Action Token. You can choose one of four Authentication Levels.

Action Token capabilities

Action Token was designed in a way which allows performing additional generic actions during Action Token validation easy.

Currently Action token can be used with a number of actions:

  1. LOGIN (optional) logs person into the application
  2. COUPLE_EXTERNAL_IDP_FROM_PARAMETERS (optional) couples the external identity with given the person's account, all required parameters (the external identity external_id and Identity Provider identifier idp_id) must be provided within the REST API call body. This action requires an action of LOGIN type
  3. COUPLE_EXTERNAL_IDP_FROM_SESSION (optional) couples the external identity with the given person's account, all required parameters are obtained from the existing person's session identified by session_management_token. This action requires LOGIN action
  4. PERSON_ACTIVATION (optional) activates the related person's account. Can be used in combination with the LOGIN in case you want the activation link to also log use into the application

It is required that at least and action of LOGIN and/or PERSON_ACTIVATION are defined when Action Token is created. Each action may require additional parameters that will be used during processing time. Detailed information about each of them can be found below.

Login Action

Action type : LOGIN

Simplest action that results in a web session creation for the person once token processing is finished. No configuration parameters are required. This action must be specified in API call when PERSON_ACTIVATION is not used.

External identity coupling from parameters

Action type : COUPLE_EXTERNAL_IDP_FROM_PARAMETERS

Action instructs the Onegini IDP application to perform external identity coupling once token processing is finished. Typical use case will be to connect generated token with some social account identity like Facebook or Google.

This action requires two extra parameters:

  • idp_id : Identity Provider identifier available in the Onegini IDP application. This Id may be found in the Onegini IDP admin console under Configuration > Identity Providers tab
  • external_id : Person's Social Identity from external Identity Provider like Facebook or Google

External identity coupling from session

Action type : COUPLE_EXTERNAL_IDP_FROM_SESSION

Action instructs the Onegini IDP application to perform external identity coupling based on the actual session state once token processing is finished. Typical use case will be to connect generated token with some social account identity like Facebook or Google.

This action requires session_management_token value to be set on Action Token creation time. For more information about session_management_token and how to obtain it please refer to Session API

Person Activation Action

Action type : PERSON_ACTIVATION

Person Activation Action allows changing the person's account status from INACTIVE to ACTIVATED. Therefore the account that is pointed by the provided person_id must be in the INACTIVE state. Defining this action will have same result as using dedication API for person activation

This action requires one extra parameter:

  • activation_method: Type of the activation method to be used to activate an account. Supported types are EMAIL or EXTERNALLY_DELIVERED_CODE.

Generate new Action Token

To create a new Action Token you need to execute the following request:

  POST http://idp-core.dev.onegini.me:8081/api/persons/<person_id>/tokens

Path parameter

The Actions Token is always related with some specific person, therefore you need to provide the person_id within the request path.

Body parameters

Parameter name Required Description
actions yes Actions that should be executed during token processing time. It is required to specify at least an action with LOGIN type.
session_​management_​token no Indicates whether the token can be used to get user related data from session, for more info please see the Session API section

Example

{
  "session_management_token": "string",
  "actions": [
    {
      "type": "LOGIN"
    }   
  ]
}
Actions definition
Parameter name Required Description
type yes Type of an action
parameters no Action configuration parameters

Examples

Simplest possible body:

{
  "actions": [ 
    {
      "type": "LOGIN"
    }
  ]
}

Body with multiple actions:

{
  "session_management_token": "string",
  "actions": [
    {
      "type": "LOGIN"
    },
    {
      "type": "COUPLE_EXTERNAL_IDP_FROM_PARAMETERS",
      "parameters": {
        "idp_id": "idp_id_from_cim",
        "external_id": "socialId"
      }
    }
  ]
}

Deprecation

The old Action Token API is now considered as deprecated.

URL
  POST http://idp-core.dev.onegini.me:8081/api/persons/<person_id>/tokens/login

The Actions Token is always related with a single user, therefore you need to provide the person_id as a request path parameter.

Revoke all tokens for a person

You can revoke all person's Action Tokens by executing the following request:

URL
  DELETE http://idp-core.dev.onegini.me:8081/api/persons/<person_id>/tokens

Validate the Action Token

The Onegini IDP's gives possibility to validate Action Token through the API and web browser.

Validation through the API

The Onegini IDP's Credentials API exposes an endpoint which allows Action Token validation. It means that you need to have the Credentials API feature enabled in the Onegini IDP's admin console in order to use this functionality.

Please have a look at the API documentation to learn more about how to validate Action Tokens.

Validation through the web browser

The Onegini IDP allows to validate Action Token through the web browser by visiting http://idp-code.dev.onegini.me:8080/login/token. To execute the validation please add token param to the request for example to validate token E88F7F06ACCF378EB5816EFB908BFF70D6E42DD2F4B9948C1DC9C119CA8E87FB user needs to visit http://idp-core.dev.onegini.me:8080/login/token/?token=E88F7F06ACCF378EB5816EFB908BFF70D6E42DD2F4B9948C1DC9C119CA8E87FB in the web browser. User is redirected to the page linked with the action or to the login page if validation failed.

Action Token properties

  • Action Tokens are single use only, and will be removed upon successful logging in or upon expiration
  • Using action token will always execute all actions linked to it
  • each person can have one or multiple (0-N) Action Tokens assigned