Person activation

Person Activation feature add additional verification step which must be performed in order to allow the end-user to actually start using his account. When enabled, every person's account will enter INACTIVE state after right after finishing sign-up. Every person who's account is in INACTIVE state is unable to successfully finish the login flow. This chapter will guide you though all steps that are required to fully configure and use an Person Activation feature with the Onegini IdP.

Prerequisites

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

  • Onegini IdP instance must be running, for the sake of this guide we assume it's available under http://idp-core.dev.onegini.me address
  • Onegini IdP extension instance must be running, for the sake of this guide we assume it's available under http://idp-extension.dev.onegini.me address
  • Onegini IdP must have the Username & password identity provider configured

Introduction

Before continuing with the topic guide please familiarize with below assumptions first.

Technical description

To get better understanding of the Person Activation feature please consider the following diagram. It illustrates the flow for the account created via an API call but it also applies for all the other use cases.

Person status lifecycle

Person account can enter INACTIVE state only in case the Person Activation feature is enabled.

NOTE Please note that enabling the feature affects how person API works - person status will follow the flow of the diagram above also for all api calls.

Supported flows

Person activation is supported in the following flows:

Configuration

Person activation feature is disabled by default. Configuration option is available under Configuration -> Feature management -> Person activation section. Currently the following flavours of person account activation are supported:

Activation via email

It allows to activate an account by visiting link delivered to the end-user via email. To enable it select the Activate via email option and define the link's TTL (time to live) / expiration time.

Activation via externally delivered code

Allows to activate an account by entering code sent to user's address. To enable it please select Activate via externally delivered code checkbox and provide few configuration properties:

  • allow resending code after period: time after which user is allowed to resend the code, the resend operation is triggered from the web interface
  • unavailability time: initial time during which the activation code is not allowed to be used
  • activation code expiration: time after which code is marked as invalid / expired
  • force activation after accepting invitation: forces activation after accepting invitation

Having the configuration done in the Onegini IdP it is also required to implementation additional changes in the actual customer specific Extension application.

Extension is responsible to process generated code and provide it to the user. To be able to do it extension needs to have DeliverExternalCodeExtension bean available.

Activation via API

Onegini IdP gives additional flexibility to activate the user via an API call thanks to which it can be easily integrated with external services. The Onegini IdP exposes three endpoints which are realising this functionality:

  • POST /api/persons/{person_id}/activate/email
  • POST /api/persons/{person_id}/activate/code
  • POST /api/persons/{person_id}/activate (direct)

All activation types (email, code, direct) are described in the API reference.

Direct activation via API

Direct activation is a special type of activation that makes it possible to activate user directly from CREATED state. To learn more please check flow diagram from "Technical description" section.

AutoActivation

The Onegini IdP also gives possibility to enable autoActivation for specific identity provider. This behaviour can be controlled by changing the state of AutoActivation checkbox in identity provider configuration form in the Onegini IdP admin console. Option should be used only used for trusted providers.

When AutoActivation is enabled the person account status will be change from INACTIVE to ACTIVATED whenever coupled with an identity provider instance that has this feature enabled will occur.

Possible AutoActivation scenarios:

  • user signs up by logging in with external identity provider with AutoActivation enabled
  • user signs up by performing Automated External Identity Coupling via identity provider with AutoActivation enabled (account is created autoamtically during login with external IdP)
  • user has already signed up and is in INACTIVE state and logs in to the system via external identity provider instance with AutoActivation enabled and his account gets automatically coupled (Automated External Identity Coupling)
  • user account is already created (via manual signup or API call) and is currently in the INACTIVE state then another API call is made to couple it with external identity provider instance that has AutoActivation enabled
  • user account is already created (via manual signup or API call) and is currently in the INACTIVE state then an Action Token of type COUPLE is being executed which couples the user's account with external identity provider instance that has AutoActivation enabled

NOTE Please note that only API in version 2 or newer does support AutoActivation feature.

Testing

Both flavours of Person Activation feature can be tested in the same way. Please sign up by entering http://idp-core.dev.onegini.me page. In case the activation via email has been selected you will be prompted to visit the activation link sent via email. In case activation via code is configured you will be prompted to enter the actual code value which was delivered to you via different channel (can be SMS, letter or other). Once activation is completed successfully you will be redirected to the dashboard page or back to the SAML Service Provider.