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?
- Action Token capabilities
- Configuration
- Supported actions
- Generate new Action Token
Action Token
consuming via Credentials API- Process
Action Token
via API - Processing through the web browser
Action Token
properties- Revoke all tokens for a person
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:
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.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 bysession_management_token
.PERSON_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 applicationLOGIN_APP2WEB
- (optional
) logs a person into the application via App to Web.
Every single action can be defined individually for one Action Token or they can be grouped. LOGIN
and LOGIN_APP2WEB
provide similar functionality and thus
cannot be used together. All defined actions will be performed when the token is processed.
If an error occurs in any step, the whole operation will be rolled back and a proper error message 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
supported actions section.
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 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
andActivation via email
checkboxes.
Setting the Action Token validity time
Every Action Token
that is generated 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.
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 possible to define a custom
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 theAction 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 eachAction 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.
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.
Login App To Web Action
Action type
: LOGIN_APP2WEB
It 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 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 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