# Introduction Welcome to LeZa! A cloud-based security gateway for application services and APIs. LeZa provides a modern security access platform for all cloud-based and legacy on-prem apps. It allows users to quickly implement [Auth2.0](https://datatracker.ietf.org/doc/html/rfc6749) and [OpenID Connect](https://openid.net/) with easy to use flexible functionality to centrally manage an advanced AuthN/AuthZ gateway across all your services. ## How does it work? The LeZa platform interface enables users to configure the access gateway and authentication for their applications and APIs with no code. The access gateway is handled by our [LeZa Proxy](https://hub.docker.com/r/simplusinnov/leza-proxy) an open-source software that can be installed on any local server or cloud provider infrastructure. ![LeZa architecture overview](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdSshgDvtEBCgCJYRjJ%2F-MdT6bZfyxRCYXVYhN-g%2FLEZA%20BASE%20ARCHITECTURE.jpg?alt=media\&token=eb1b9746-b5f3-410f-8eb0-69f5aca0fdfd) ## Key components ### The Platform *"LeZa Platform"* or *"LeZa Admin"* is cloud-hosted and accessible through the following link: . Access is available for private beta users. We would be happy to welcome you. In order to join send an email to . LeZa Admin provides you with the no-code functionality to register your applications and APIs, secure your endpoints, compile security policies, configure users, roles, permissions, etc... Additionally, the built-in analytics logs will also provide you with insights on traffic flowing through your application. ### The Proxy [*LeZa Proxy*](https://hub.docker.com/r/simplusinnov/leza-proxy) is open-source software that can be installed on any infrastructure, it is currently available in the form of a [Docker](https://docs.docker.com/get-docker/) repository. The proxy plays the role of a security gateway to your applications and services and is easily configured through **LeZa Platform.** Read more about the proxy and how to set it up [here](/getting_started/setup-your-proxy). ### Your application Your application is any front-end service or API that is being protected by LeZa, it generally sits on the same network as the Proxy and is not publicly accessible (from the open internet). Read more about how to set up your network to create a secure environment for your application [here](/getting_started/secure-your-network). ## Where to go next? ### A Quick Guide to Getting Started Have a look at our [Getting Started](/getting_started) page to start using LeZa and have your app service or API secured in less than 10 minutes. ### Basic Concepts A collection of [key concepts](/technology) to be familiar with when implementing LeZa ### API Reference Most of our features are also exposed as APIs so you can easily integrate LeZa through our APIs by checking [this link](/api). ### LeZa Feature Overview If you would like to get a detailed understanding of our features visit the [reference section](/references) (currently under construction :construction\_worker:). # Basic Concepts In this section, we will provide an introduction to the various technical concepts that LeZa provides. ### Authentication Authenticating a user or client trying to access any application or API service has a valid identity (proving they are, who they say they are [eg. SCA](https://en.wikipedia.org/wiki/Strong_customer_authentication)) is a critical part of any access control integration. LeZa allows you to control access to your application using both the OAuth 2.0 and OpenID Connect specifications and provides multiple options to handle the authentication experience built on top of the LeZa feature set. LeZa provides seamless no-code integrations with popular social sign-in identity providers ([SSO](https://en.wikipedia.org/wiki/Single_sign-on)). LeZa has built-in logic flows for strong and adaptive authentication as well as typical user registration and password (re)setting functionality. LeZa understands that the user sign-in experience is important and provides you with full UI customisation functionality. ### Authorization Authorization is a crucial part of verifying that a user/client has the necessary permissions to access resources and web services. With LeZa, you can achieve granular role-based access control on any application or API service using both OAuth 2.0 and OpenID Connect. LeZa at its core is an authorization engine for minting and validating OAuth 2.0 and OpenID Connect tokens. LeZa provides easy to use functionality to create permissions for your protected resources and scopes, associate those permissions with authorization policies, and enforce authorization decisions in your applications and services. ### Organizations LeZa enables you to organize your customers in organizations and sub-organizations. An organization is a hierarchical space where the admins of the organisation can independently perform access control actions such as assign applications, manage users, custom roles, permissions and access groups. ([see about more this here](/technology/organizing#organizations)) ![Organizations provide special features to easily manage hierarchy-based access control](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MfrV9oTNqH9crcZckaX%2F-MfrVHwXc_xe-KfzV49Z%2FScreenshot%202021-07-30%20at%2015.00.06.png?alt=media\&token=b97d475b-a001-4d70-b60b-c92a6e8a3a5a) ### Audit & Traceability LeZa tracks all the activity of your organization or the organisations using your application in order to understand the activity of your users and critical security changes that were made. LeZa provides access to granular detailed logs which allow you to understand your user's interaction with your application/services and the meta-data surrounding those transactions. ### Notifications One of LeZa's many convenient functionalities is notifications. This provides you with easy-to-use functionality to send notifications from your application or application services to one or several users. Your users will have the ability to independently configure what they do or do not want to receive. *This is a really interesting feature for those looking to generate backend service type notifications or broadcast user notifications across multiple customers. Contact our support who will be happy to tell you more.* ### # Authentication LeZa provides an out-the-box implementation for the right authentication to support your projects ## LeZa as an Identity Provider LeZa is in itself an identity provider based on the [OpenID Connect protocol](https://openid.net/connect/) implementation. It allows you to register users and keep their information safe. Easy access to this information is accessible through our open [API](https://dac.do.si-dev.net/docs#tag/Users). ## External Identity Providers LeZa seemlessly manages connections to other Identity Providers for your application and sits between your application and the Identity Provider that authenticates your users. LeZa provides SSO or Social Sign-in which allows you to connect to Identity Providers like [Google](https://developers.google.com/identity/protocols/oauth2/openid-connect), [Facebook](https://developers.facebook.com/docs/facebook-login/), [Azure](https://azure.microsoft.com/en-gb/free/active-directory/search/?\&ef_id=Cj0KCQjwxJqHBhC4ARIsAChq4asFWpQANdKTLykoNI1KjJzqBic33TiaCQILKHNssxOGzoXkhmQ0v4kaAp7VEALw_wcB:G:s\&OCID=AID2200255_SEM_Cj0KCQjwxJqHBhC4ARIsAChq4asFWpQANdKTLykoNI1KjJzqBic33TiaCQILKHNssxOGzoXkhmQ0v4kaAp7VEALw_wcB:G:s\&gclid=Cj0KCQjwxJqHBhC4ARIsAChq4asFWpQANdKTLykoNI1KjJzqBic33TiaCQILKHNssxOGzoXkhmQ0v4kaAp7VEALw_wcB) and many more with zero fuss. *An external identity provider is a service that creates and maintains identity information and then provides authentication services to your applications. Integrating with external identity providers can significantly reduce sign-in and registration friction, which allows your users to easily access applications without needing to create new passwords or remember usernames*. ## Authentication LeZa allows you to control access to your application using both the OAuth 2.0 and OpenID Connect specifications. [OpenID Connect](https://openid.net/connect/) (OIDC) is an authentication protocol that is an extension of [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749). While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization protocol. OIDC also makes heavy use of the [Json Web Token](https://jwt.io/) (JWT) set of standards. These standards define an identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way. ### MFA (Multi-Factor Authentication) LeZa enables [strong customer authentication](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32015L2366\&from=EN#d1e5540-35-1) allowing users to configure MFA. Organisation admins are able to set MFA as a requirement for all users in the organisation. The multi-factor authentication methods that are provided are: * Using an authentication app like Google Authenticator * Using one or more phone numbers * Using your email address ***What is Strong Customer Authentication?** Strong Customer Authentication (*[*SCA*](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32015L2366\&from=EN#d1e5540-35-1)*) is a new European regulatory requirement to reduce fraud and make online services more secure. SCA requires authentication to use at least two of the following three elements:* * ***Something the user knows** (eg. Password or Pin)* * ***Something the user has** (eg. Hardware key or Phone)* * ***Something the user is** (eg. Fingerprint or Facial Recognition)* ### Defining Custom Authentication Settings per Organization [Organization admins](/technology#organisations) have the flexibility to configure their own authentication policy requirements for the following items: * MFA to be required by users (forced) and which methods to allow * The token expiration time period for user registration and password reset * Password length and strength requirements * Permissible [SSO Identity Providers](/technology/authentication#external-identity-providers) * Maximum password lifetime # Audit & Traceability LeZa embeds detailed traceability logs that automatically allows you to audit usage and policy changes on your application or APIs. ## State Information You automatically gain insights into the state of your applications and APIs secured with LeZa. ### User sessions At any point in time administrators can check active sessions for users with very detailed information like the location of the session, the machine, operating system and more. ``` { "_id": "60e47b84c38ed482gg780f87", "browser": { "type": "browser", "name": "Chrome", "version": "91.0", "engine": "Blink", "engineVersion": "" }, "os": { "name": "GNU/Linux", "version": "", "platform": "x64" }, "device": { "type": "desktop", "brand": "", "model": "" }, "bot": null, "ip": "161.35.614.165", "geoLocationInfoOfIp": { "ip": "161.35.214.167", "country_code": "DE", "country_name": "Germany", "region_code": "HE", "region_name": "Hesse", "city": "Frankfurt am Main", "zip_code": "60313", "time_zone": "Europe/Berlin", "latitude": 50.1188, "longitude": 8.6843, "metro_code": 0 }, "machine_identifier": "-spwGnVaPEJyYHi6-V5RqfoTJ8ZA.wdPS7sH_GkKeTwU1rZp6rehY", "performer": { "id": "422129df-6611-45e9-adf1-83a", "name": "John Doe", "email": "doe@deer.com", "picture_url": "https://res.cloudinary.com/dfprwegge/image/upload/v1580297552/2ba96261-94e1-41e1-8c9d3bb.png", "organization_id": "fb1cf8e-1a90aa6f1d58", "organization_name": "Umbrella Academy", "role_name": "Super Natural", "redirect_uris": "https://app.yourcloud.com/auth/callback", "clientid": "6e851a76-cfc-410-b49-4f171b9", "organization_unit_id": null, "organization_unit_name": null, "organization_unit_labels": null, "organizations": [ { "id": "fb1cf80-4e25-4c-ab8e-1f1d58", "name": "Umbrella Academy", "type": "Rocket Dep", "labels": [] } ] }, "session_start": "2025-07-06T15:49:24.062Z", "__v": 0 } ``` ### Service Availability If you configured your applications and services with ping methods you will be able to see if your services are accessible and set up alarm notifications in case of failure. ## Logs Logging is a common useful requirement in all applications and with LeZa you won't have to redo an implementation for this. We are certain that you already have enough work on your hands by coding and logging your business logic, that's why we take care of this for you. ### Access Logs LeZa provides a very detailed view of all API accesses in your application or organization. This allows users to track all kinds of usage activities. (*see tabs below*) ### Audit Logs LeZa automatically logs all changes made inside the [administration platform](/#the-platform). This enables full end-2end traceability. You will automatically understand who and what type of changes were performed each step of the way. For example, you can see who changed the permissions for a certain role, and the whole history of changes for that role. (*see tabs below*) {% tabs %} {% tab title="Access Logs" %} **AUDIT ACCESS ADVISORY SESSION LOG** FROM: 2025-06-08 TO: 2025-07-08 | Time | Action Type | Endpoint | Endpoint Type | Reason | Details | | ------------ | ----------- | ---------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ | | 4 HOURS AGO | logout | /logout | GET | User has the permission to logout | MORE DETAILS | | 4 HOURS AGO | access | /api/v2/ti-api/geofence?organizationId=5e-32c7-41a5-8a5d-c | GET | User has the permission **Live Tracking Page Permission** to access this resource of this application **Insight App** | MORE DETAILS | | {% endtab %} | | | | | | {% tab title="Audit Logs" %} **AUDIT LOG** FROM: 2025-06-08 TO: 2025-07-08 | Time | Action | Details | | ------------- | -------------------------------------------- | ------------ | | 2 MONTHS AGO | John Doe update\_application LeZa Account | MORE DETAILS | | 2 MONTHS AGO | Jenny Admin add\_application LeZa Account | MORE DETAILS | | {% endtab %} | | | | {% endtabs %} | | | # Controlling Access Functionality With LeZa you can easily customise and configure hierarchical access control functionality to fit your application structure and API workflow needs. ## Services (Resources) Services are protected resources and capable of accepting and responding to protected resource requests. Ultimately, your endpoints become your protected resources, essentially turning your client application into the resource server. > "A resource server is a server hosting the protected resources and capable of accepting and responding to protected resource requests." - OAuth2 specification. LeZa enables you to configure granular authorization for protecting resources, where resource scopes can be defined and authorization decisions can be made based on different verbs (GET, POST, PUT, DELETE). {% tabs %} {% tab title="Settings" %} ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MeAlUQ9TdSSOAx2GCdG%2F-MeAtU_7h7RlE1BiuUST%2FScreenshot%202021-07-09%20at%2017.26.54.png?alt=media\&token=93905dc5-5946-4688-bed6-c0e0302136fe) {% endtab %} {% tab title="Endpoints" %} ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MeAlUQ9TdSSOAx2GCdG%2F-MeAtY5xFnjlkk_eXYcn%2FScreenshot%202021-07-09%20at%2017.29.03.png?alt=media\&token=b3f236ab-bebe-4859-ac3b-6f0fd1432080) {% endtab %} {% endtabs %} *A service can be a web page, a RESTful resource, a file in your file system. Services represent a group of resources or they can represent a single and specific resource.* ## Policies and Permissions LeZa allows you to create custom policies and permissions based on the granular authorizations protecting your resources and these policies can be organized into permissions (granting evaluated access to protected resources) for all the application services that are registered. Once you have defined your protected resources you can configure the below: ### Policies Policies define the conditions that must be satisfied to access or perform operations on your services (resource or scope), but they are not bound to what they are protecting. They are generic and can be reused to build permission combinations or even more complex policies Policies are ultimately, a convenient grouping of permissions that allows access to a group of protected services that can be easily issued and managed in a centralised manner. ### Permissions LeZa allows you to create custom permissions to define all the granted access points of your application. Permissions are bound to the service they protecting. With LeZa you specify what protected service access you will allow by assigning the policies that must be satisfied in order to grant or deny permission. {% hint style="info" %} **Visualize**: **Joe** can **View** his **Balance** * **Joe:** represents one or more users, groups or roles. * **View:** represents the actions that can be taken. * **Balance**: represents that service that is being protected "/balance" {% endhint %} ### Roles Roles are useful when you need more constrained or hierarchically structured access grants to protected resources (RBAC - Role-Based Access Control). Configuring roles allows you to assign users or a group of users to receive a specific set of permissions and policies that must be satisfied to access or perform operations on your services (resource or scope). ## User management Using the LeZa cloud platform you can easily invite and manage users, assign roles and permissions. This gives you the full flexibility you require to control how users and clients access your services. We allow each organization (see below: [Organizations](/technology/organizing#organizations)) the functionality to invite and manage users, assign roles and permissions independently. ### User groups This is a convenient feature whereby users can be grouped into user groups, which allows you to centrally issue those users a set of permission and/or policies in a group fashion instead of individually repeating tasks for each user. ## Organizations LeZa provides you with some valuable organisational centric functionality that separates your customers (user accounts) into organizations (Primary Account Space). Each organisation can be customized and self-managed by the Organization Admin (any users with admin rights in the organisation). Organizations contained their own context/settings which allow for custom configurations to be self-administered by their admin users. ([also see](/technology#organizations)) This out of the box feature gives you the full flexibility of [IAM](https://en.wikipedia.org/wiki/Identity_management) should your project require it. > **Example 1**: Let's say you've built a great web service that your customers subscribe to and you are looking to test your latest beta-service with select customers only. Those Organisations that you have invited to your new service can subscribe without having to resign up their users to this new service (self-managed subscriptions). > > **Example 2:** You have two customer accounts both using your Web Application but each customer has different IT policies. One requires that password refresh tokens are expired within 1hr (this client also requires it's user to use 2-factor authentication) and the other perferrs 24hrs (with no 2FA). No Problem! The each customer can manage this in the Organisation settings. ### Organization units Organizations can be further divided into organization units (sub-account spaces). This follows a logic tree format allowing you to organize your resources in a hierarchical logical structure. > "A great benefit of organisation units is they have their own assigned identifier which allows you to filter response results without having to cater for this in your code". ![Note: Access Groups allow for users in different organisation units to have joint permissions](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-Me5umDDxZyw7QBTYsSR%2F-MeAl49c4FZrK9BpAWZc%2FScreenshot%202021-07-09%20at%2016.55.28.png?alt=media\&token=07f69742-64fc-44f4-b27a-9a2834558223) ### Branding Custom themes, colours and logos can be set independently for every Organization. Giving your users a personalized experience whilst all using the same service :exploding\_head: # FAQ Frequently Asked Questions - Security Related Topics ### Risk Avoidance LeZa structures permissions, policies and roles in a best-practice manner to ensure that no breaches can be created from omissions or misconfigurations. Roles are organized as a hierarchy, policies are overlapping and constrained depending on the use case. If a broken access control configuration is created users will be notified before being able to commit the configuration. The logging functionality that is performed on each request assists or team in identifying erroneous or malicious behaviours in order to continuously improve system resilience and reduce the resolution times. ### WAF LeZa proxy contains a Web Application Firewall that protects your application from malicious attacks like SQL injection, Cross-site scripting, Session hijacking, broken access control, Cross-site request forgery - [Top 10 OWASP vulnerabilities](https://owasp.org/www-project-top-ten/). This does not mean that you should not take care and prepare your requests for SQL injection or use best practices to set up your URLs. Leza will block malicious requests in the majority of use cases. ### Encryption LeZa embeds encryption in all its communication and storage. We recommend you do the same when building your applications, however, this is something we can not control. We will always notify you and provide you with best-practice information on how to configure your applications. ### Password Hashing All passwords handled by LeZa are hashed using the[ bcrypt protocol](https://en.wikipedia.org/wiki/Bcrypt) for which the underlying hashing algorithm is blowfish. ### Compliance Standards LeZa is OWASP, PCI and GDPR compliant for its scope, this does not automatically mean that using LeZa makes your application compliant - there are other scopes to consider in terms of your application and application environment. Using LeZa will however make it much easier to achieve a level of compliance our team will always be available to support you and assist in advising you on the best way to configure your project in order to stay compliant. # Getting Started This guide will walk you through a few steps to quickly secure your application with LeZa This "Getting Started" guide is a short tutorial that will get you up and running with LeZa. At the end of this short tutorial, you will have secured your first application or service and will be able to invite users to access your resources securely :closed\_lock\_with\_key: We recommend you follow the steps in the order that they are presented to avoid getting lost in the different flexible concepts that LeZa provides. If you are not really interested in immediately starting to build with LeZa but want to have a better understanding of the product and how it can help you! We invite you to have a look at the [Basic Concepts section](/technology). Or, if you are interested in integrating with LeZa from a software point of view we recommend you have a look at our [API section](/api). # Create an account In this section you will be guided into creating an account on LeZa ## Early Access Early Access to LeZa is currently limited. The good news is that anyone can request to sign-up for early access by sending us a request to the following email address: #### Email content example: > Hi LeZa Team, > > My name is "........" and I would like to join the LeZa Beta. Once your request has been handled by our team, you will receive an invitation email to create a new password on our platform. Just fill in the information that is requested and you will have open access to LeZa :raised\_hands: . ## Where to go next? Your first step should be [setting up your organization](/getting_started/configure-your-organization) # Set up an Organization LeZa separates customers account spaces into organizations, these organizations provide the functionality to invite users and manage application settings within a secure environment. ## Organization settings {% hint style="info" %} To access organization settings, click on your profile to display the little drop-down menu. Then click on "Organization settings". {% endhint %} The organization settings page allows you to manage all the aspects of your organization, there are currently three sections * The profile section of your organization, which contains all the information related to it. * The theme section allows you to customize the application to meet your organization branding. * The audit section allows you to see all the actions that happened in your organization from a security/settings perspective. ## Create a new organization When you are invited to join LeZa, you will be a member of an already created organization. However, while you're getting started you might want to create a new organization to get the full experience. In order to do so, just follow these steps: **1) Click on the profile icon then "Switch organization"** ![On the top left menu click on switch organization](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdT6dAul8MZRv5xVIeR%2F-MdVbbK4eOtPXIfoKDtJ%2FSwitch%20organization.png?alt=media\&token=79e13108-ad3f-4e28-87fc-2f65c45c4ea2) **2) On the top right of your screen, just below the menu you will see a button with a plus sign(+). Click on it.** ![Click on create a new organization to create your own organization](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdT6dAul8MZRv5xVIeR%2F-MdVbbJumcw9TiS6oZv5%2FAdd%20organization.png?alt=media\&token=53038ea1-afa1-49af-b0de-9e476c8966d9) **3) Enter the requested information and click on "Ok"** ![Your are only required to fill in the name field and click "OK"](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdT6dAul8MZRv5xVIeR%2F-MdVbbK1quUhfBNYkhq2%2FOrganization%20creation%20form.png?alt=media\&token=dd5da249-75df-433a-92b8-bf03ae17ad4d) Your organization will now be created and you can configure it accordingly to your needs. ## Switch organization Once you have access to several organizations, you need to be able to navigate from one organization to the other. In order to do this follow these steps: **1) Click on the profile icon then "Switch organization"** ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdT6dAul8MZRv5xVIeR%2F-MdVbbK4eOtPXIfoKDtJ%2FSwitch%20organization.png?alt=media\&token=79e13108-ad3f-4e28-87fc-2f65c45c4ea2) **2) Click on the "Select organization" button on the right of the organization to which you want to switch** ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdT6dAul8MZRv5xVIeR%2F-MdVbbK3vEW__f4SHt-m%2FSelect%20your%20organization.png?alt=media\&token=0726d7a3-1598-48e2-8088-fab0c6fb0287) **3) Confirm that you want to switch** You will now be accessing the selected organization. # Create a first application Secure your first application with LeZa ## Introduction All applications secured with LeZa use the LeZa proxy as an access gateway. The proxy can be deployed on any cloud provider infrastructure or local server by the application/service owner (client). In order to configure the [LeZa proxy](/#the-proxy), you must first register your application and get a *Client ID* and a *Client Secret* ## Registering your application In order to get your application registered. You will generate a client/application Id and client/application secret for the authentication layer. You need to follow these steps: **1) Click on the application tab from the left sidebar.** **2) Click on plus icon (+) button to create a new application.** ![The application section](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdVdt19w7uM7GEROrOO%2F-MdVe-VhmgoisPHDequX%2FAdd%20application.png?alt=media\&token=89b915c4-8dec-488a-b44f-23a2d9f26852) **3) Complete the registration form** ![The application creation form](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MdVdt19w7uM7GEROrOO%2F-MdVe-Vj5hD7zkmFbPy5%2FApplication%20form.png?alt=media\&token=cfab49c3-230c-4837-a4ac-bcd71bdc64e4) 1. Add an application name - this is your application/service name. 2. Add a callback url - this is the URL where your application/service is hosted. 3. Click on the "Ok" button. {% hint style="info" %} If you are going to run **Leza Proxy** locally then your callback is [http://localhost/auth/callback](http://www.google.com/url?q=http%3A%2F%2Flocalhost%2Fauth%2Fcallback\&sa=D\&sntz=1\&usg=AFQjCNECHjnz8_leEImOSYMxWIm5EYxU3A) otherwise [http://](http://www.google.com/url?q=http%3A%2F%2Flocalhost%2Fauth%2Fcallback\&sa=D\&sntz=1\&usg=AFQjCNECHjnz8_leEImOSYMxWIm5EYxU3A)[\[domian or ip\]](http://www.google.com/url?q=http%3A%2F%2Flocalhost%2Fauth%2Fcallback\&sa=D\&sntz=1\&usg=AFQjCNECHjnz8_leEImOSYMxWIm5EYxU3A)[/auth/callback](http://www.google.com/url?q=http%3A%2F%2Flocalhost%2Fauth%2Fcallback\&sa=D\&sntz=1\&usg=AFQjCNECHjnz8_leEImOSYMxWIm5EYxU3A) {% endhint %} ## Register services Services are parts of your application or can be the whole application itself. In modern architectures we prefer to separate different units of logic in "micro-services" these micro-services are poorly coupled which makes development and maintenance easier. {% hint style="info" %} For example, an application can have one **front-end web application service** and a **back-end API.** In this case, we would register two services: 1. The front end web application 2. The back-end API {% endhint %} In order to register a service use the following steps: ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-Mexli6ZljMX4FUsIoEM%2F-Mexls6d1gNb7RAAk6SQ%2FOpera%20Snapshot_2021-07-19_095757_dac.do.si-dev.net.png?alt=media\&token=6d09f1b7-97dc-42f7-b685-d6c166c885c6) **1) Click on the services tab from the main menu.** **2) Click on the plus icon (+) button on the top right of your main screen to create the new service.** ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-Mexli6ZljMX4FUsIoEM%2F-MexmUgACg_wr8nqmoYI%2FOpera%20Snapshot_2021-07-19_100055_dac.do.si-dev.net.png?alt=media\&token=66f413b0-479b-4c3a-bbdc-3e8e03b4ecbc) **3) Add a name for your service, this name will help you to identify your service on LeZa** **4) Add a URL for your service** {% hint style="info" %} The URL of your service is the address of the service from a LeZa proxy point of view. So if LeZa proxy and your service are running on a private network (which we strongly recommend), then the URL should be the private IP of that service AND the port to reach the service via http or https. #### Example If you install the application on your private machine then the URL of your service should be the following: * http\://\[YOUR\_PRIVATE\_IP]:\[PORT] for Linux * http\://\[YOUR\_NETWORK\_IP]:\[PORT] for MAC {% endhint %} **5) Add a base path of your service, the base path is the pattern of your service path in the URL.** **6) Add a service logo, in order to recognize it easily.** Select if your service is private or public, a public service can be accessed without being logged in (like a front-end for example in certain cases). **7) Click on the "Ok" button** Your service should now be created and be ready to use. ## Create endpoints An end-point is a function accessible through your service. Each endpoint is determined by its path. Configuring endpoints will allow you to create custom rules to control access to those endpoints, we highly recommend you register all of your endpoints in order to get the most out of LeZa. In order to start creating endpoints, you must click on an already created service (Go to the previous section to [create a service](/getting_started/create-a-first-application#register-services)). Then go on the endpoints section and click on the little plus (+) button. ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MeyAAvvSWsBPoKbiAB4%2F-MeyAwJSLvfLxTWC9It5%2FOpera%20Snapshot_2021-07-19_101015_dac.do.si-dev.net.png?alt=media\&token=ed3fb798-c2ed-401b-a38b-f29fe14ff96d) **1) Go to the endpoints tab** **2) Click on add endpoint** Complete the following information: ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MeyAAvvSWsBPoKbiAB4%2F-MeyBVEGsDvEWKRXsl9o%2FCreate%20endpoint.png?alt=media\&token=0aa3a5be-d9b5-4bdd-bf22-b36d15384d16) 1\. Enter the name of your service endpoint, we recommend naming it according to its function for easy identification purposes 2\. Enter the name of your resource. *Recommendation: Depending on the information that the resource manages, you should name it accordingly (for example if the API returns oranges you should call it oranges)* 3\. Select the HTTP method type - (GET, POST, PUT, DELETE) 4\. Enter the service path to reach the function 5\. Click on "next" to finish the creation of the endpoint ## Attach services to your application After registering your services and creating their endpoints accordingly you will need to attach them with the corresponding application. To do this follow these steps: ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MeyAAvvSWsBPoKbiAB4%2F-MeyCY69j0wT9h_QJynD%2FAttach%20services.png?alt=media\&token=0074e48a-0b1b-48c5-809b-d818fffaeea2) 1. Click on the "application tab" from the left sidebar. 2. Go to the details view by clicking on the "edit" action icon. 3. Click on the "services" tab. 4. Click on the "attach" toggle button to attach a service to the application. Now your application is now set up and almost ready to go :raised\_hands: See [setting up access control](/getting_started/setup-access-control) next. # Setting up access control LeZa's granular access control gives you the power to manage fine grained permissions and access settings. ## You said access control ? Access control is controlling who and how users can access your application. In order to achieve this you first need to be familiar with some topics. ### Permissions A permission is the most granular access point of our application, it represents an action that a user can perform or the accessibility of a service, feature or resource. The creator of the application defines what the permission means and LeZa enables them to set it up. #### Setting up permissions In order to create permissions you first need to go to the app you want to give access to, in order to do so click on the app section in the main menu then on the app you want to configure. If you then go to the permission tab you will be able to add your new permissions. * Click on the plus button (+) on the top right * Give your permission a name like: 'See the email address of a user' * Give it a description * Confirm to add your permission Once you have added a permission you can manipulate it from your API or your front-end as you wish but you can also bind it to an endpoint, this will give access to that endpoint only if the user has the permission to do so. In order to bind the permission to an endpoint you must click on the attach to endpoint button on the left of your new permission. ### Policies Policies are a group of permissions configured for a certain scope. Policies will be used everywhere in your configuration because their are more convenient and significant than permissions alone. To have a better understanding of a policy let's use an example.. #### Example Imagine you are building a to do list application, which allows to create new tasks assign them to people and plan them in a calendar. You could create the following policies: * **Organize people's tasks**: this would give the permission to *add a new task* and *assign the task to a user* and to *See the list of tasks for all users* * **Organize the calendar**: this would give the permission to *assign a completion date* and to *See the list of tasks for all users* * **Complete tasks**: this would give the permission to *See you own tasks* and *Mark tasks as completed* #### Setting up policies In order to setup a new policy for your application you need to perform the following steps: * Go to the Policies section in your main menu * Click on the little plus (+) button on the top right to display the policy creation window * Enter your policy name ex: Organize tasks for people * Give a version ex: v1.0.0 * Give it a status, local or global (global policies are accessible to external organizations) * Click on ok and your policy is now created You must then attach your policy to permissions, in order to do sow follow these steps: * Click on the attach permission button on the right of your created policy * Select in the left corner the permissions that you want to attach * Click on the right arrow to add them to the policy's permissions * Save your changes and the policy is now configured ### Roles A role is the position of a user inside of your organization. A user can only have one role per organization, but you can configure as many roles as you want. The role will be associated to policies in order to determine its access to your application. The main difference between a role and a policy is that a role is seen from a user access rights point of view and policies are seen from a feature-set access rights point of view. #### Setting up roles In order to setup a first role in your organization you must perform the following steps: * Click on the role section in your main menu * Click on the plus button on the top right of your screen * Give your role a name and description * Select the parent role (check the notice bellow to understand how this works) {% hint style="info" %} Roles are organized hierarchically so that the children of a role only are allow to get access to a subset of its parent's permissions {% endhint %} * Click on the create button to create you role You can now bind policies to your role by * Clicking on the three dots on the right of you created role then "Bind policies" * Selecting the policies that need to be added on the left part of your screen * Click on the right arrow to add them as your role's policies * Click on the save button to confirm your changes ## Conclusion Now that you have configured all the security aspects of your application from an access point of view you can attach your role to a user of your organization by going to the users section and changing the role of your user. # Running the LeZa Proxy The proxy is your application security gateway providing the all-important secured access control. ## What is the LeZa proxy? [*LeZa Proxy*](https://hub.docker.com/r/simplusinnov/leza-proxy) is open-source software that can be installed on any infrastructure, it is currently available as a [Docker](https://docs.docker.com/get-docker/) image. The proxy plays the role of a security gateway to your applications and services and is easily configured through **LeZa Platform.** ***See the steps below to get your LeZa gateway up and running.*** ## How to set up the architecture of my app? The LeZa proxy is the gateway to your application and should be the only public access point (unless you know what you are doing). This means that the proxy should be inside the private network containing your application. Although there is a way to configure your application and the LeZa gateway on different networks this requires a bit more work. We highly recommend for the purposes of efficiency and security you keep all instances inside the same private network. ## Configuring your LeZa Proxy To install the proxy you will need the **Client ID** and **Client Secret** of your application, if you don't know where to get those please refer to the [create an application section](/getting_started/create-a-first-application). You will also need to have docker installed. If needed, you can go to [Docker Documentation](https://www.google.com/url?q=https%3A%2F%2Fdocs.docker.com%2F\&sa=D\&sntz=1\&usg=AFQjCNGKVGdPCjyAfuSrWCeHFaClP9227w) in order to see how to install and run the docker container. Next, pull the LeZa Proxy docker image with this command ``` docker pull simplusinnov/leza-proxy ``` Then, run the proxy with the below command ``` docker run -e OAUTH2_CLIENT_ID=[YOUR_LEZA_CLIENT_ID] -e OAUTH2_CLIENT_SECRET=[YOUR_LEZA_CLIENT_SECRET] --net=host -it -d simplusinnov/leza-proxy ``` {% hint style="warning" %} Input the client\_*ID and client\_secret provided by LeZa when* [*registering your application*](/getting_started/create-a-first-application#registering-your-application) *where you see* **\[YOUR\_*****LEZA\_*****CLIENT\_ID], \[YOUR\_*****LEZA\_*****CLIENT\_SECRET]** in the command. {% endhint %} {% hint style="warning" %} Note: If you use docker desktop, then **--net=host** will not work for you :cry: {% endhint %} If you are using a Mac then use the following command: ``` docker run -p 8001:80/tcp -e OAUTH2_CLIENT_ID=[YOUR_LEZA_CLIENT_ID] -e OAUTH2_CLIENT_SECRET=[YOUR_LEZA_CLIENT_SECRET] -it -d simplusinnov/leza-proxy ``` *Your proxy should now be running and if you configured your application on LeZa you will be redirected to a login page when trying to access your content!* :shield::raised\_hands: # Invite users Creating End Users in LeZa The purpose of access control is to provide your end users secure access to your application or resources. There are several ways to do this such as making your application or resources public and allowing users access through their own organization, however, we will describe this in-depth at a later stage. For now, we will focus on adding users to your organization. ## Invite a new user To add a new user to your organization perform the following steps: **1) Click on the 'Users' section in the main menu (or dashboard view).** ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MfhAc42HhG1sUkgkvyl%2F-MfhHZ8oWbIZ1N9kzSua%2FScreenshot%202021-07-28%20at%2015.20.55.png?alt=media\&token=8895fdd3-d053-4f08-bc12-192391f1d6d0) **2) Click on the plus (+) icon in the top right to add a user.** ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MfhAc42HhG1sUkgkvyl%2F-MfhIp4bbqork0kVfqfV%2FScreenshot%202021-07-28%20at%2015.26.49.png?alt=media\&token=bf4f0fec-cdff-4884-9d14-335507a37c68) **3) Enter the user name** **4) Enter the user email address** **5) Select the application for which you want the user to access after they have accepted the invitation.** **6) Click the 'ok' button** The user will then automatically receive an email to configure their password and be directed to your application. ![](https://3605998819-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MRtW8q_2YtUp8tqmG0E%2F-MfhAc42HhG1sUkgkvyl%2F-MfhL18c-luiqzEHPMPN%2FScreenshot%202021-07-28%20at%2015.32.58.png?alt=media\&token=51ee7d2a-4ee5-445c-98b2-e665644267e4) {% hint style="info" %} You can allow users to **sign-up** to access your application without you needing to invite them. To do this activate the **B2B Sign-up option** when [registering your application.](/getting_started/create-a-first-application#registering-your-application) *Pop our team a note if you would like some assistance with this (documentation coming soon).* {% endhint %} # Secure your network Recommendations in securing your network to avoid back-doors and other vulnerabilities. When securing your network it's important to have a good understanding of the infrastructure services you are using. In this section, we will describe very common infrastructure service providers and how to secure your application within those environments. ## Kubernetes If you have deployed your application on Kubernetes, make sure that there is no direct [ingress ](https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress)to your application or microservices, also make sure that the services linked to your application services are of `type:`` `*`NodePort`,* and set to`externalTrafficPolicy: 'local'` Unless you are confident with what you are doing, you should only have one *LoadBalancer* that is directed to your Ingress and which should redirect every request to the Leza Proxy ## Docker compose If you using Docker Compose to deploy your application or services, ensure you create a private network for your applications, microservices and databases then share that network with the LeZa Proxy **Example:** ```yaml // LeZa Proxy proxy: ... networks: - my_network - public // Your applications, services and databases app: ... networks: - my_network service: ... networks: - my_network database: ... networks: - my_network // Your networks networks: public: ... internal: false my_network: ... internal: true ``` ## AWS If you have deployed your application on AWS, make sure that the security groups linked to your application services and Load Balancers are configured to block any external access with the exception of your Load-balancer and the container that runs your LeZa Proxy. ## Google Cloud *We're working on it* :paintbrush: ## Azure *We're working on it* :paintbrush: ## Digital Ocean *We're working on it* :paintbrush: # API LeZa allows for seamless API integration To use the LeZa APIs follow [this link](https://dac.do.si-dev.net/docs) to our API documentation :robot: # References Links to useful information sources that might help you *We're working on it* :paintbrush: