Action Token

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

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.
  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.
  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

Every single action can be defined individually for one Action Token or they can be grouped in every possible combination. All defined actions will be performed when Action Token is processed. In case of error at any step whole operation will be rolled back and proper error message will be returned. Each action may require additional parameters that will be used during processing time. Detailed information about each of them can be found in the Login Action section.

Configuration

Enabling the feature

The Action Token feature toggle can be found in Onegini IDP admin console in Configuration > Features tab.

  1. To enable token based login functionality simply select the Action Token Login enabled checkbox.
  2. To enable token based coupling functionality select the Action Token Coupling enabled checkbox
  3. To enable token based activation via email is essential - select activation enabled and Activation via email checkboxes.

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.

Redirect URI

Each Action Token can have a redirect URI assigned which will be either used to redirect the user (Web flow) during the token processing or returned as part of the success response (API flow) upon the validation call.

Redirect URI calculation

The Onegini IDP can also return redirect URL even in case none was explicitly assigned to the Action Token itself. Please take a look at below list representing the order and hierarchy when it comes calculating the redirect URI in various scenarios:

  1. Redirect URI explicitly assigned to the Action Token when it was created POST /api/persons/{person_id}/tokens. Please note that the redirect URI assigned to the Action Token MUST be whitelisted. You will learn more about whitelisting redirect URIs in the following section.
  2. Redirect URI provided as part of the Onegini IDP general configuration [Configuration -> General Information] for the token's last processed action. Please note that each Action Token can refer to multiple actions, they are processed by the Onegini IDP one by one in the following order (Activation -> Coupling -> Login).
  3. Can only happen when the token is processed in the Web flow When the redirect URI cannot be calculated based on the above two conditions the Onegini IDP will redirect the user to the default home page (http://idp-core.dev.onegini.me/login).

In case action token is consumed in Web flow and both return_url and redirect URI is specified then redirect URI has precedence over return_url.

Redirect URI whitelisting

In order to be able to assign a redirect URI to the Action Token you need to define a whitelist that will match the address/es that you want to use. The whitelist can be configured in the Onegini IDP admin console under Configuration -> Feature management -> Action Tokens section. The form allows you to define one or more addresses or regular expressions that will be used afterwards to validate the redirection URI.

Supported actions

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.

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 or PERSON_ACTIVATION 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
redirect_uri no Uri to which CIM is redirected after action token usage. It needs to be validated using action token whitelist in the admin panel.

If not provided and LOGIN type is used in actions, value of Redirect to URL after login from admin's Configuration -> General Information config is used.
If PERSON_ACTIVATION is used as action Redirect to URL after activation from admin's Configuration -> General Information config is used.
If both actions LOGIN and PERSON_ACTIVATION are used and redirect_uri is not provided then Redirect to URL after login is used if it's defined. By default all actions redirect to the Login page.
send_notification no Flag to determine if email notification should be send to user after generating the token.

Example

{
  "session_management_token": "string",
  "redirect_uri" : "http://idp-core.dev.onegini.me",
  "send_notification" : true,
  "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"
      }
    }
  ]
}

Action Token consuming via Credentials API

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.

Process Action Token via API

Having action token created it is possible to consume it and execute all the actions stored within it. It is possible by executing the following request:

URL
  POST http://idp-core.dev.onegini.me:8081/api/credentials/token

As an example let's assume that action token with id 30ba6d18-b070-4fc2-9e2a-11786bf23230 has been registered and it contains two actions LOGIN and COUPLE_EXTERNAL_IDP_FROM_PARAMETERS. By executing following request

{
    "profile": {
        ...
    },
    "results": [
        {
            "type": "COUPLE_EXTERNAL_IDP_FROM_PARAMETERS",
            "parameters": {
                "idp_id": "1234",
                "external_id": "1234567890"
            }
            "execution_status": "SUCCESS"
        },
        {
            "type": "LOGIN"
            "execution_status": "SUCCESS"
        }
    ]
    "redirect_uri": "https://mypage.com/dashboard"
}

session for the user is created and external identity provider is coupled with user's account. More information about the endpoint is available in credentials api documentation.

Processing through the web browser

The Onegini IDP allows to validate and process 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 usage 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

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