Handling security

You handle security in GWS high-level REST via scopes.

Security is configured based on the recommendations of the OpenAPI specification via scopes implemented by OAuth, and Bearer token authentication.

In a secured system, you have a delegate service that is responsible for checking who has access to a service. If user access is allowed, the service must forward the scopes via the Genero Application Service (GAS) X-FourJs-Environemnt-Scopes environment variable. The scope definition sent by the GAS must match that in the WSScope attribute.

Note: The call to the REST function is executed if, and only if, the GAS is started.

To implement security the GAS delegate service must be running and must have extracted those scopes from an access token and forwarded them to the GWS REST service. For more information see the Genero Application Server User Guide.

If there is no access token, or there is no delegate service providing the verification, the function is not executed. Security is executed if, and only if, the request contains a scope definition, and its value matches what is in the WSScope attribute.

Note: Testing your services with WSScope:
  • When testing your service in standalone mode without a GAS, the WSScope is not checked. However, when behind a GAS, the appropriate scope is required and you will need to deploy and secure the service with the Genero Identity Provider (GIP).
  • Alternatively, if you need to integrate Genero REST services security into your own environment system, you can also write your own delegate service to validate any kind of token, extract the scope from it, and forward it to the REST service.

Handling security errors

Access token errors are automatically handled by the GWS engine. You do not need to do anything in your code. If the client request does not have the correct access token, the service will return HTTP 403.

Publishing scopes

When you generate the service description, the scope you declared in the WSScope attribute, the user or group member detail, is published in the "security" section for that function in the OpenAPI specification file. If you declare scopes with a modular variable with the WSInfo and WSScope attributes, the "security" tag at the end of the specification file contains the security details.