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:
LOGIN
(optional
) logs person into the applicationCOUPLE_EXTERNAL_IDP_FROM_PARAMETERS
(optional
) couples the external identity with given the person's account, all required parameters (the external identityexternal_id
and Identity Provider identifieridp_id
) must be provided within the REST API call body. This action requires an action ofLOGIN
typeCOUPLE_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 bysession_management_token
. This action requiresLOGIN
actionPERSON_ACTIVATION
(optional
) activates the related person's account. Can be used in combination with theLOGIN
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 tabexternal_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 areEMAIL
orEXTERNALLY_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