Action Token¶

About Action Tokens¶

An Action Token is a special kind of token. An Action Token permits its bearer to perform an action, e.g., to reset a password or validate an email address. Action Tokens are sent to users most of the time, usually as links that point to an endpoint that processes Action Tokens to allow access to specific information on a website or in an app.

To create an Action Token for a user, Onegini has an Action Token functionality.

Prerequisites¶

Ensure the following prerequisites:

the Onegini IdP must be running,
access to the Onegini IdP admin portal,
at least one user must be registered within the Onegini IdP.

Action Token capabilities¶

The Action Token functionality makes additional generic actions during Action Token validation easy and can be used for the following actions:

Action	Description
`LOGIN` (`optional`)	This action logs a person into the application.
`COUPLE_EXTERNAL_IDP_FROM_PARAMETERS` (`optional`)	This action couples the external identity with 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.
`COUPLE_EXTERNAL_IDP_FROM_SESSION` (`optional`)	This action 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`.
`PERSON_ACTIVATION` (`optional`)	This action activates the related person's account. This action can be used in combination with the `LOGIN` in case you want the activation link to also log use into the application.
`LOGIN_APP2WEB` - (`optional`)	This action logs a person into the application via App to Web.

You can define every single action individually for one Action Token, or they can be grouped.
The actions LOGIN and LOGIN_APP2WEB provide similar functionality and thus can not be used together. All defined actions will be performed when the token is processed.
If an error occurs in any step, the whole operation rolls back, and a proper error message returns.
Each action may require additional parameters that will be used during processing time. Detailed information can be found under supported actions.

Configuration¶

Enabling the feature¶

The Action Token feature toggles can be found in Onegini IdP admin console in Configuration > Feature management tab.

To enable token-based login functionality, use the Action Token Login enabled checkbox.
To enable token-based login with the app to web functionality, use the App to Web via Action Token enabled checkbox.
To enable token-based coupling functionality, use the Action Token Coupling enabled checkbox.
To enable token-based activation via email is essential, use the activation enabled and Activation via email checkboxes.

Setting the Action Token validity time¶

Every Action Token has a predefined validity time (TTL) which needs to be defined in the admin panel. You can adjust this value to the one that suits your use case the most. Please note that the modified value will only impact 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. It is possible to define Authentication Level specific to the Action Token type. 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:

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

Note

If an action token is used within a SAML flow the redirect URI will be ignored

Supported actions¶

Action type : LOGIN

This is the simplest action that results in a web session for the person once the token processing is finished. No configuration parameters are required.

Action type : LOGIN_APP2WEB

This action is very similar to the LOGIN action but has its own configuration. A web session will be created for a given person once the token processing is finished. No configuration parameters are required. The Onegini Token Server uses this action for the App To Web Single Sign On feature.

NOTE: LOGIN and LOGIN_APP2WEB cannot be used at the same time.

External identity coupling from parameters¶

Action type : COUPLE_EXTERNAL_IDP_FROM_PARAMETERS

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

This action requires two parameters:

idp_id : The 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 : The person's social identity from external Identity Provider like Facebook or Google

External identity coupling from session¶

Action type : COUPLE_EXTERNAL_IDP_FROM_SESSION

This action instructs the Onegini IdP application to perform external identity coupling based on the actual session state once the 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 the session_management_token value to be set on the 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

This action allows changing the person's account status from INACTIVE to ACTIVATED. Therefore the account linked to 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 information please see the Session API section
redirect_uri	no	Uri to which the Onegini IdP will redirect the users after the action token is used. It needs to be validated using action token whitelist in the admin panel.
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¶

If you have created an action token you can use it to execute all the actions stored within it. You can do this by executing the following request:

URL¶

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

As an example let's assume that the 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 sending the 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"
}

The 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/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/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

Action Token¶

About Action Tokens¶

Prerequisites¶

Action Token capabilities¶

Configuration¶

Enabling the feature¶

Setting the Action Token validity time¶

Defining the authentication level for the Action Token¶

Redirect URI¶

Redirect URI calculation¶

Redirect URI whitelisting¶

Supported actions¶

Login Action¶

Login App To Web Action¶

External identity coupling from parameters¶

External identity coupling from session¶

Person Activation Action¶

Generate new Action Token¶

Path parameter¶

Body parameters¶

Actions definition¶

Action Token consuming via Credentials API¶

Validation through the API¶

Process Action Token via API¶

URL¶

Processing through the web browser¶

Action Token properties¶

Deprecation¶

URL¶

Revoke all tokens for a person¶

URL¶

Defining the authentication level for the `Action Token`¶