Identity Service

Build Status Dependencies Coverage Status

A microservice for identity management.

Features

  • Management of User Account and Role entities

  • User-to-Role associations with arbitrary scoping

  • User account creation using any of the following options: self-service, by privileged user, by invitation

  • Password change as self-service

  • Password recovery as self-service

  • Un-registration as self-service

  • Customizable, optional email notifications to drive processes

  • Access token management service

  • Authentication log audit log

Configuration

The following service specific configuration properties are available:

  • uniqueEmailConstraint [true]: name and email fields for registering/ creating user are unique, if set to false it allows to register/ create users with same email identifier, however name must always be unique.

  • loginIdentifierProperty [name, email]: list of identifiers to enable user to login, if the config is missing then by default user can login with either name or email.

  • userActivationRequired [true]: if set to false, users do not require account activation to be able to log in and use their account.

  • register [true]: if set to false, the Register endpoint is disabled and users cannot self sign up but only be created through the bulk creation method Create which is usually only available to adminstrative user roles.

  • enableEmail [true]: if set to true, emails are sent out upon specific events, like account creation and email change.

  • activationURL: URL used for link in activation email to activate the account.

  • inactivatedAccountExpiry in seconds [undefined]: if set to a number of seconds, the account will completely be removed from the system (log date will be retained) if no activation has been performed since the given number of seconds.

  • emailConfirmationURL: URL used for link in confirmation email to confirm email address change.

  • invitationURL: URL used for link in invitation email to accept invitation.

  • data: additional fields can be provided inside data. These fields can then be used inside the hbs templates.

  • hbsTemplates: contains URLs for externally served Handlebars templates. These templates are used in emails sent by system for different operations like Register, RequestEmailChange and RequestPasswordChange.

  • minUsernameLength: minimum length for the user’s name.

  • maxUsernameLength: maximum length for the user’s name.

  • obfuscateAuthNErrorReason:`false`, if set to true the login error details are obfuscated and generalized error message is shown.

  • authorization:enable [true]: if set to true then access-control check is performed, if set to false then access-control check is overridden.

  • authorization:enforce [true]: if set to true then result of access-control-check is enforced, if value is set to false the result of access-control check is logged and ignored.

  • defaultRegisterUserRoles: default role associations granted to newly registered users.

Example: We can add a field called url nested inside the data field in the config.json file, and then use this field in registration_body.hbs to generate some html with the interpolated url. Multiple fields are supported as-well.

  • config.json:

{
  "service": {
    "data": {
      "url": "https://www.google.com/"
    }
  }
}

  • registration_body.hbs:

<a href="{{data.url}}">Google Main Page</a>

API

This microservice exposes the following gRPC endpoints:

User

A list of User resources.

io.restorecommerce.user.UserList

Field Type Label Description

items

io.restorecommerce.user.User[]

required

List of Users

total_count

number

optional

number of Users

subject

io.restorecommerce.auth.Subject

required

Subject details

A User resource.

io.restorecommerce.user.User

Field Type Label Description

id

string

optional

User ID, unique, key

meta

io.restorecommerce.meta.Meta

optional

Meta info

name

string

required

Username

first_name

string

optional

User’s first name

last_name

string

optional

User’s last name

email

string

required

Email address

new_email

string

optional

Property in which the email is stored upon an email change request until its confirmation

active

bool

optional

Value is true if the user was successfully activated

activation_code

string

optional

Activation code used in the activation process (cleared after successful activation)

password

string

required

Raw password, not stored

password_hash

bytes

optional

Hashed password, stored

timezone_id

string

optional

The User’s timezone setting (defaults to `Europe/Berlin')

locale_id

string

optional

The User’s locale ID

default_scope

string

optional

default scope of user

unauthenticated

bool

optional

Set automatically to true upon user registry until its account is activated for the first time

guest

bool

optional

If user is guest

role_associations

io.restorecommerce.auth.RoleAssociation []

optional

Role associations

user_type

io.restorecommerce.user.UserType

optional

User Type - individual, organization or guest user

image

io.restorecommerce.image.Image

optional

Image

invite

bool

optional

used for user invitation

invited_by_user_name

string

optional

inviting User’s name

invited_by_user_first_name

string

optional

inviting User’s first name

invited_by_user_last_name

string

optional

inviting User’s last name

tokens

io.restorecommerce.auth.Tokens []

optional

list of Tokens

last_access

google.protobuf.Timestamp

optional

timestamp of user’s last access

io.restorecommerce.auth.RoleAssociation

Field Type Label Description

role

string

optional

Role ID

attributes

io.restorecommerce.attribute.Attribute []

optional

Attributes associated with the User’s role

id

string

optional

role association identifier (referred in Tokens list)

io.restorecommerce.attribute.Attribute

Field Type Label Description

id

string

optional

attribute identifier

value

string

optional

attribute value

io.restorecommerce.user.UserType

Field Type Label Description

ORG_USER

enum

optional

organizational User

INDIVIDUAL_USER

enum

optional

private User

GUEST

enum

optional

guest User

TECHNICAL_USER

enum

optional

technical User

io.restorecommerce.image.Image

Field Type Label Description

id

string

optional

image identifier

caption

string

optional

image caption

filename

string

optional

image file name

content_type

string

optional

image content type

url

string

required

image URL

width

string

optional

image width

height

string

optional

image height

length

string

optional

image length

io.restorecommerce.auth.Subject

Field Type Label Description

id

string

optional

user id of the authenticated user

scope

string

optional

target scope of user

role_associations

io.restorecommerce.user.RoleAssociation[]

optional

A list of roles with their associated attributes

hierarchical_scopes

io.restorecommerce.user.HierarchicalScope[]

optional

A list of hierarchical scopes of the authenticated user

unauthenticated

bool

optional

for unauthenticated users

token

string

optional

token value

io.restorecommerce.user.HierarchicalScope

Field Type Label Description

id

string

optional

role scoping instance / root node value of Organization

role

io.restorecommerce.role.Role.id

optional

role identifier associated with role scoping instance

children

io.restorecommerce.user.HierarchicalScope[]

optional

hierarchical organizational tree

CRUD Operations

The microservice exposes the below CRUD operations for creating or modifying User resources.

io.restorecommerce.user.UserService

Method Name Request Type Response Type Description

Create

io.restorecommerce.user.UserList

io.restorecommerce.user.UserList

Create a list of User resources

Read

io.restorecommerce.resourcebase.ReadRequest

io.restorecommerce.user.UserList

Read a list of User resources

Update

io.restorecommerce.user.UserList

io.restorecommerce.user.UserList

Update a list of User resources

Delete

io.restorecommerce.resourcebase.DeleteRequest

Empty

Delete a list of User resources

Upsert

io.restorecommerce.user.UserList

io.restorecommerce.user.UserList

Create or Update a list of User resources

Create

Used to create a User (usually by privileged user). Requests are performed providing io.restorecommerce.user.UserList protobuf message as input and responses are an io.restorecommerce.user.UserList message. The User-to-Role associations assignment is optionally secured by access-control-srv with configuration. If authorization is enabled this service uses acs-client to invoke access-control-srv to verify the role and its associations are valid. When authorization is enabled the creating user should have a valid authentication subject io.restorecommerce.auth.Subject in request else the request is denied. The User is allowed to create other Users with valid User-to-Role associations io.restorecommerce.user.RoleAssociation.Attribute with in his io.restorecommerce.user.HierarchicalScope. The creating User can assign roles if io.restorecommerce.role.Role.assignable_by_roles is with in his hierarchical scope context io.restorecommerce.user.HierarchicalScope.role.

This API also checks if user name is complying with the following set of rules:

  1. If the user name contains an "@" symbol, then the username must also be a valid email.

  2. The user name must respect the minimum and maximum number of characters allowed.

  3. The user name must begin with a letter (a-z, A-Z, äöüÄÖÜß).

  4. The user name must contain only characters from the allowed characters list (a-z, A-Z, 0-9, äöüÄÖÜß, @_.-).

  5. The user name should not contain forbidden character repetitions (__, .., --).

Register

Used to register a User. Requests are performed providing io.restorecommerce.user.RegisterRequest protobuf message as input and responses are an io.restorecommerce.user.User message. The io.restorecommerce.user.RoleAssociation are associated using the preconfigured role association from the defaultRegisterUserRoles. If a valid configuration for retrieving email-related handlebars templates from a remote server is provided, an email request is performed upon a successful registration. Such configuration should correspond to the service/hbsTemplates element in the config files. The email contains the user’s activation code. Email requests are done by emitting a`sendEmail` notification event, which is consumed by notification-srv to send an email. Please note that this email operation also implies template rendering, which is performed by emitting a renderRequest event, which is consumed by the rendering-srv. Therefore, the email sending step requires both a running instance of the rendering-srv and the notification-srv (or similar services which implement the given interfaces) as well as a remote server containing a set of email templates. This is decoupled from the service’s core functionalities, and it is automatically disabled if no template configuration is provided.

Moreover, the Register operation itself is optional and one can enable or disable it through the service.register configuration value. If disabled, the only endpoint for user creation is Create.

io.restorecommerce.user.RegisterRequest

Field Type Label Description

guest

bool

optional

Guest user, default value is false

name

string

required

Username

first_name

string

optional

User’s first name

last_name

string

optional

User’s last name

email

string

required

User email ID

password

string

required

User password

timezone

string

optional

The User’s timezone setting (defaults to `Europe/Berlin')

locale_id

string

optional

The User’s locale setting identifier (defaults to `de-DE')

user_type

io.restorecommerce.user.UserType

optional

User Type

captcha_code

string

optional

captcha code

Activate

Used to activate a User. The service.userActivationRequired config value turns the user activation process on or off. Requests are performed providing io.restorecommerce.user.ActiveRequest protobuf message as input and responses are a google.protobuf.Empty message.

io.restorecommerce.user.ActiveRequest

Field Type Label Description

identifier

string

required

User name or User email

activation_code

string

required

activation code for User

subject

io.restorecommerce.auth.Subject

required

Subject details

ChangePassword

Used to change password for the User (this User should be activated to perform this operation). Requests are performed providing io.restorecommerce.user.ChangePasswordRequest protobuf message as input and responses are an io.restorecommerce.user.User message.

io.restorecommerce.user.ChangePasswordRequest

Field Type Label Description

password

string

required

old password

new_password

string

required

new password

subject

io.restorecommerce.auth.Subject

required

Subject details

RequestPasswordChange

Used to change password for the User in case they forget it. It generates and persists an activation code for the user and issues an email with a confirmation URL. Requests are performed providing io.restorecommerce.user.RequestPasswordChangeRequest protobuf message as input and responses are google.protobuf.Empty messages. Either user name or email should be specified upon the request.

io.restorecommerce.user.RequestPasswordChangeRequest

Field Type Label Description

identifier

string

required

User name or User email

subject

io.restorecommerce.auth.Subject

required

Subject details

ConfirmPasswordChange

Used to confirm the user’s password change request. The input is an io.restorecommerce.user.ConfirmPasswordChangeRequest message and the response is a google.protobuf.Empty message. If the received activation code matches the previously generated activation code, the stored password hash value is replaced by a hash derived from the new password, and the activation code is reset.

io.restorecommerce.user.ConfirmPasswordChangeRequest

Field Type Label Description

identifier

string

required

User name or User email

activation_code

string

required

Activation code

password

string

required

New password

subject

io.restorecommerce.auth.Subject

required

Subject details

RequestEmailChange

Used to change the user’s email. Requests are performed providing the io.restorecommerce.user.ChangeEmailRequest protobuf message as input and responses is a google.protobuf.Empty message. when receiving this request, the service assigns the new email value to the user’s new_email property and triggers an email with a confirmation URL containing a newly-generated activation code.

io.restorecommerce.user.ChangeEmailRequest

Field Type Label Description

identifier

string

required

User name or User email

new_email

string

required

New email

subject

io.restorecommerce.auth.Subject

required

Subject details

ConfirmEmailChange

Used to confirm the user’s email change request. The input is an io.restorecommerce.user.ConfirmEmailChangeRequest message and the response is a google.protobuf.Empty message. If the received activation code matches the previously generated activation code, the value assigned to the new_email property is then assigned to the email property and new_email is set to null.

io.restorecommerce.user.ConfirmEmailChangeRequest

Field Type Label Description

identifier

string

required

User name or User email

activation_code

string

required

Activation code

subject

io.restorecommerce.auth.Subject

required

Subject details

ConfirmUserInvitation

Used to confirm user invitation. Requests are performed providing io.restorecommerce.user.ConfirmUserInvitationRequest protobuf message as input and responses are a google.protobuf.Empty message. For Create operation if the invite flag io.restorecommerce.user.invite is set to true then an invitation mail would be sent if invitationURL and hbsTemplates configuration values are setup accordingly.

io.restorecommerce.user.ConfirmUserInvitationRequest

Field Type Label Description

identifier

string

required

User name or User email

password

string

required

User password

activation_code

string

required

User’s activation_code sent via email

subject

io.restorecommerce.auth.Subject

required

Subject details

Login

Used to verify the User name or email with a password and return User’s information in case the operation is successful. Requests are performed providing io.restorecommerce.user.LoginRequest protobuf message as input, and the response is io.restorecommerce.user.User message.

io.restorecommerce.user.LoginRequest

Field Type Label Description

identifier

string

required

User name or User email

password

string

optional

Raw password

token

string

optional

Token for users

Unregister

Used to unregister a User. Requests are performed providing io.restorecommerce.user.UnregisterRequest protobuf message as input and responses are a google.protobuf.Empty message.

io.restorecommerce.user.UnregisterRequest

Field Type Label Description

identifier

string

required

User name or User email

subject

io.restorecommerce.auth.Subject

required

Subject details

Find

A simplified version of read, which only filters users by a username, email and/or ID. Requests are performed providing io.restorecommerce.user.FindRequest protobuf message as input and responses contain a list io.restorecommerce.user.User messages.

io.restorecommerce.user.FindRequest

Field Type Label Description

id

string

optional

User ID

name

string

optional

User name

email

string

optional

User EmailID

subject

io.restorecommerce.auth.Subject

required

Subject details

FindByRole

A custom endpoint in order to filter a user by its role and any attributes associated with it. Requests are performed providing io.restorecommerce.user.FindByRoleRequest protobuf message as input and responses contain a list io.restorecommerce.user.User messages.

io.restorecommerce.user.FindByRoleRequest

Field Type Label Description

role

string

required

Role name

attributes

io.restorecommerce.user.RoleAssociation.Attribute[]

optional

Role attributes

subject

io.restorecommerce.auth.Subject

required

Subject details

FindByToken

This endpoint returns the user data based on the provided token value. Requests are performed providing io.restorecommerce.user.FindByTokenRequest protobuf message as input and response is io.restorecommerce.user.User data. For caching purpose this endpoint also stores the token information in Redis with key as token identifier and user data as value. The cached data is invalidated when User is logged_out or when token Destroy or RevokeByGrantId api is invoked.

io.restorecommerce.user.FindByTokenRequest

Field Type Label Description

token

string

required

Token value

SendActivationEmail

This endpoint sends activation email to the email id of the registered user. In case if the User is already activated suitable error response is sent, else activation email containing activation code is sent back. Requests are performed providing io.restorecommerce.user.SendActivationEmailRequest protobuf message as input and response is google.protobuf.Empty message.

io.restorecommerce.user.SendActivationEmailRequest

Field Type Label Description

identifier

string

required

User name or email

subject

io.restorecommerce.auth.Subject

required

Subject details

Role

A list of Role resources.

io.restorecommerce.role.RoleList

Field Type Label Description

items

io.restorecommerce.role.RoleList[]

required

List of Roles

total_count

number

optional

number of Roles

subject

io.restorecommerce.auth.Subject

required

subject details

io.restorecommerce.role.Role

Field Type Label Description

id

string

optional

Role identifier

name

string

required

specifies the Role of the User

description

string

optional

Role description

assignable_by_roles

string[]

optional

role identifier’s who can assign this role

meta

io.restorecommerce.meta.Meta

optional

Meta info

CRUD Operations

The microservice exposes the below CRUD operations for creating or modifying Role resources.

io.restorecommerce.role.RoleService

Method Name Request Type Response Type Description

Create

io.restorecommerce.user.RoleList

io.restorecommerce.user.RoleList

Create a list of Role resources

Read

io.restorecommerce.resourcebase.ReadRequest

io.restorecommerce.user.RoleList

Read a list of Role resources

Update

io.restorecommerce.user.RoleList

io.restorecommerce.user.RoleList

Update a list of Role resources

Delete

io.restorecommerce.resourcebase.DeleteRequest

Empty

Delete a list of Role resources

Upsert

io.restorecommerce.user.RoleList

io.restorecommerce.user.RoleList

Create or Update a list of Role resources

For the detailed protobuf message structure of io.restorecommerce.resourcebase.ReadRequest and io.restorecommerce.resourcebase.DeleteRequest refer resource-base-interface.

Token

A Token resource.

io.restorecommerce.auth.Tokens

Field Type Label Description

name

string

optional

Token name

expires_in

google.protobuf.Timestamp

optional

Token expiration timestamp

token

string

optional

token value

scopes

string []

optional

identifier for RoleAssociation io.restorecommerce.auth.RoleAssociation.id

type

string

optional

token type ex: access_token, refresh_token etc

last_login

google.protobuf.Timestamp

optional

timestamp of user last logged in

interactive

bool

optional

flag to indicate a login from GUI

CRUD Operations

The microservice exposes the below operations for upsert, find and delete Token resources.

io.restorecommerce.token.TokenService

Upsert

This endpoint upserts token data on user entity io.restorecommerce.user.User.tokens. Request is formed using io.restorecommerce.token.TokenData and response is google.protobuf.Any message containing the status of upsert operation. For upsert operation we use a tech user upsert_user_tokens configured in configuration.

io.restorecommerce.token.TokenData

Field Type Label Description

id

string

optional

Token identifier

payload

string

optional

Token payload (id_token)

expires_in

google.protobuf.Timestamp

optional

Token expiration timestamp

type

string

optional

Token type

subject

io.restorecommerce.auth.Subject

required

Subject details

Find

This endpoint is used to find the token information using token identifier. Requests are performed providing io.restorecommerce.token.Identifier protobuf message as input and response is google.protobuf.Any message containing token information.

io.restorecommerce.token.Identifier

Field Type Label Description

id

string

optional

Token identifier

type

string

optional

Token type

subject

io.restorecommerce.auth.Subject

optional

Subject details

Destroy

This endpoint is used to destroy or remove the token information from user entity io.restorecommerce.user.User.tokens. Requests are performed providing io.restorecommerce.token.Identifier protobuf message as input and response is google.protobuf.Any message containing token information.

Method Name Request Type Response Type Description

Upsert

io.restorecommerce.token.TokenData

google.protobuf.Any

upserts token and returns success or failure message

Find

io.restorecommerce.token.Identifier

google.protobuf.Any

find token data

Destroy

io.restorecommerce.token.Identifier

google.protobuf.Any

destroy token

RevokeByGrantId

io.restorecommerce.token.GrantId

google.protobuf.Any

destroy token by its grantId property reference

Consume

io.restorecommerce.token.Identifier

google.protobuf.Any

Mark a stored token as consumed (updates last_access)

Events

Emitted

List of events emitted by this microservice for below topics:

Topic Name Event Name Description

io.restorecommerce.users.resource

registered

emitted upon user registration

activated

emitted upon user activation

passwordChangeRequested

emitted when user requests for password change

passwordChanged

emitted when password was changed successfully

emailChangeRequested

emitted when user requests for email change

emailChangeConfirmed

emitted when user’s email was changed successfully

unregistered

emitted when a user is unregistered

userCreated

emitted when a user is created

userModified

emitted when a user is modified

userDeleted

emitted when a user is deleted

io.restorecommerce.roles.resource

roleCreated

emitted upon role creation

roleModified

emitted upon role modification

roleDeleted

emitted when role deletion

io.restorecommerce.notification

sendEmail

emitted when triggering notification email

io.restorecommerce.rendering

renderRequest

emitted when rendering is requested

io.restorecommerce.command

restoreResponse

system restore response

resetResponse

system reset response

healthCheckResponse

system health check response

versionResponse

system version response

flushCacheResponse

flush ACS Cache response

setApiKeyResponse

set API Key response

For renderRequest and renderResponse the message structures are defined in rendering-srv and for sendEmail they are defined in notification-srv,

Consumed

This microservice consumes messages for the following events by topic:

Topic Name Event Name Description

io.restorecommerce.command

restoreCommand

for triggering for system restore

resetCommand

for triggering system reset

healthCheckCommand

to get system health check

versionCommand

to get system version

flushCacheCommand

used to flush ACS Cache

configUpdateCommand

used to update configurations

io.restorecommerce.rendering

renderResponse

to get response from render request