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 which has been implemented:
Class diagram
Service provides simple RESTful API. Below there is a description of each endpoint.
Creating new user:
POST /register
- register new userPOST /register/confirm
- confirming user accountGET /register/username/@{username}
- user name verificationGET /register/email/{email}
- email verificationUser account management:
POST /account/login
- login user into system (returns JWT access token)POST /account/refresh
- refresh JWT access tokenPOST /account/change-password
- change user passwordPOST /account/revoke/@{username}
- revoke all refresh tokens for userOpenID Connect support:
GET /identity/authenticate/{uri}
- authentication by external OpenId Connect providerGET /identity/callback/{uri}
- callback with code
from OpenId Connect providerPOST /identity/login
- login user into system via authentication token (flow is described below)Forgot password actions:
POST /forgot/token
- generate token for restoring passwordPOST /forgot/confirm
- new passwordUser data management:
GET /users/@{username}
- get user profilePUT /users/@{username}
- update user dataDELETE /users/@{username}
- deleting user accountRole management:
GET /roles
- list of rolesGET /roles/{id}
- specific rolePOST /roles
- new rolePUT /roles/{id}
- update role dataDELETE /roles/{id}
- delete roleConnect user to role:
POST /user-roles/connect
- connect role to userPOST /user-roles/disconnect
- disconnect user from roleAuhentication clients:
GET /auth-clients
- list of external authenticatorsGET /auth-clients/{id}
- specific auth clientPOST /auth-clients
- new auth clientPUT /auth-clients/{id}
- update auth client dataDELETE /auth-clients/{id}
- delete auth clientFirst 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.
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:
appsettings.json
(or in appsettings.local.json
if you don't want to commit file)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
.
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.
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 URLstenantId
- Id of tenant (directory) from Azure portal (applies only for Microsoft provider)clientId
- client Id generated by OpenId Connect providersclientSecret
- secret token generated by OpenId Connect providerscallbackUrl
- callback URL which will be open after successfull authentication (URL of presentation layer) to that URL authToken
will be addedOpenId Connect flow of authentication:
From Web application (client) perspective there are two important things:
/identity/authenticate/google
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.
You can deploy application as service in the Kubernates cluster or as a single 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
link |
Stars: 5 |
Last commit: 2 years ago |
Common operations for user management:
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics