👫 Mikroservices - Users

Microservice which provides common features for managing users (only RESTful API). Application is written in Swift and Vapor 4 and operates on PostgreSQL or SQLite databases. All functionalities are constantly verified by unit tests.

Main features

Main features which has been implemented:

• registering new user
• sign-in user (JWT access token & refresh token)
• forgot password
• change password
• update user data
• user roles

Class diagram

API

Service provides simple RESTful API. Below there is a description of each endpoint.

Creating new user:

• POST /register - register new user
• POST /register/confirm - confirming user account
• GET /register/username/@{username} - user name verification
• GET /register/email/{email} - email verification

User account management:

• POST /account/login - login user into system (returns JWT access token)
• POST /account/refresh - refresh JWT access token
• POST /account/change-password - change user password
• POST /account/revoke/@{username} - revoke all refresh tokens for user

OpenID Connect support:

• GET /identity/authenticate/{uri} - authentication by external OpenId Connect provider
• GET /identity/callback/{uri} - callback with code from OpenId Connect provider
• POST /identity/login - login user into system via authentication token (flow is described below)

Forgot password actions:

• POST /forgot/token - generate token for restoring password
• POST /forgot/confirm - new password

User data management:

• GET /users/@{username} - get user profile
• PUT /users/@{username} - update user data
• DELETE /users/@{username} - deleting user account

Role management:

• GET /roles - list of roles
• GET /roles/{id} - specific role
• POST /roles - new role
• PUT /roles/{id} - update role data
• DELETE /roles/{id} - delete role

Connect user to role:

• POST /user-roles/connect - connect role to user
• POST /user-roles/disconnect - disconnect user from role

Auhentication clients:

• GET /auth-clients - list of external authenticators
• GET /auth-clients/{id} - specific auth client
• POST /auth-clients - new auth client
• PUT /auth-clients/{id} - update auth client data
• DELETE /auth-clients/{id} - delete auth client

Getting started

First you need to have Swift installed on your computer. Next you should run following commands:

$ git clone https://github.com/Mikroservices/Users.git
$ cd Users
$ swift package update
$ swift build

Now you can run the application:

$ .build/debug/Run serve --port 8000

If application starts open following link in your browser: http://localhost:8000. You should see blank page with text: Service is up and running!. Now you can use API which is described above.

Database

If you want to use persistent database you have to set application setting in configuration file or in environment variable with connection string to the database.

Connection string for PostgreSQL:

Variable name:              users.connectionString
Value (connection string):  postgresql://user:password@host:5432/database?sslmode=require

Connection string for SQLite:

Variable name:              users.connectionString
Value (connection string):  users.db

You can set up this variable as:

1. setting in appsettings.json (or in appsettings.local.json if you don't want to commit file)
2. environment variable in your system
3. environment variable in XCode

Configuration

The application uses predefined settings. All settings are stored in the database in the Setting table. We can find there following settings:

• isRecaptchaEnabled - information about enable/disable Google Recaptcha, it's highly recommended to enable this feature. Recaptcha is validated during user registration process.
• recaptchaKey - secret key for Google Recaptcha.
• jwtPrivateKey - RSA512 key for generating JWT tokens (signing in). Private key should be entered only in that service. Other services should use only public key.
• emailServiceAddress - address to service responsible for sending emails (confirmation email, forgot your password features).
• corsOrigin - CORS origin address. Example value: http://origina.com/, http://originb.com/ (if empty all origins are accepted).
• eventsToStore - list of events which should be stored in events table. Possible values are (separated by comma):
  • accountLogin - logins to the system,
  • accountRefresh - refreshing access tokens,
  • accountChangePassword - changing password,
  • accountRevoke - revoking access tokens,
  • forgotToken - forgot password,
  • forgotConfirm - confirming changing password,
  • registerNewUser - registering new user,
  • registerConfirm - confirm new user registrations,
  • registerUserName - user name verifying,
  • registerEmail - email veryifying,
  • rolesCreate - role creating,
  • rolesList - list of roles,
  • rolesRead - role details,
  • rolesUpdate - role updating,
  • rolesDelete - role deleting,
  • userRolesConnect - connecting user to role,
  • userRolesDisconnect - disconnecting role from user,
  • usersRead - user details,
  • usersUpdate - user updating,
  • usersDelete - user deleting.

In production environment you MUST change especially jwtPrivateKey.

Email support

During registration process and forgot password process service will try send emails to the user. That's why correct address to email service must be defined. For that purposes you can use for example: SendGridEmails service.

OpenId Connect

Service has built in support for OpenId Connect authentication flow. You can define providers in the AuthClients table. You need to specify:

• type - type of supported provider. Possible values: apple, google and microsoft
• name - name of provider (can be used on presentation layer)
• uri - URI which will be added to the callback/redirect URLs
• tenantId - Id of tenant (directory) from Azure portal (applies only for Microsoft provider)
• clientId - client Id generated by OpenId Connect providers
• clientSecret - secret token generated by OpenId Connect providers
• callbackUrl - callback URL which will be open after successfull authentication (URL of presentation layer) to that URL authToken will be added

OpenId Connect flow of authentication:

From Web application (client) perspective there are two important things:

1. Web application have to redirect to authentication URL e.g. /identity/authenticate/google
2. After successfull authentication Web application should be opened with authenticateToken variable in query string. That variable can be exchanged for accessToken via /identity/login endpoint (authenticateToken is valid 60 seconds).

If user is signing in for a first time a new account will be created.

Deployment

You can deploy application as service in the Kubernates cluster or as a single service in Linux.

Users service in Linux

You must modify and copy file users.service to your Linux server (folder /lib/systemd/system). Then you can start service using below command:

$ systemctl start users.service

If you want start service at system boot you must run following command:

$ systemctl enable users.service