WSScope

Specify security in the REST service via scopes.

Syntax

WSScope = "{ scope } [,...]"
Where WSScope is a comma-separated list of scopes and where:
  1. scope defines access permission for the resource.

Usage

You use this attribute to specify security via scopes forwarded from the Genero Application Server to the GWS REST service.

The call to the REST function is executed if, and only if, the GAS is started and the scope definition matches that in the WSScope attribute.

WSScope is an optional 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.

You can set the WSScope attribute in the ATTRIBUTES() clause of the REST function or in a variable at the service level.

Example using WSScope at the service level

PUBLIC DEFINE serviceInfo 
  RECORD ATTRIBUTE(WSInfo,WSScope="users.fourjs")
    title STRING,
    version STRING,
    contact STRING
  END RECORD
The scope is set in the service information record of the module. The required attributes are WSInfo and WSScope. All REST functions in the Web service are executed if and only if the request contains a scope definition that matches the value in the WSScope attribute.

Example WSScope in REST function

PUBLIC FUNCTION Add(a INTEGER
    b INTEGER)
  ATTRIBUTES (WSGet,
              WSScope="dev.write, user.readonly")
  RETURNS (INTEGER)
    RETURN a + b
END FUNCTION

The call to the REST function is executed if:

  • the GAS is started
  • the scope contains "dev.write" or "user.readonly"

How to determine the scope names

When determining the names for the scopes, it is important to understand the role of scopes. You create a scope in the Identity Provider (IdP) system and assign it to a group or a user, so that the user or group member will get an access token containing the scope name, and be allowed to access an operation that specifies the same scope name using the WSScope attribute.

The names you choose can be a simple name (such as "readonly"), or it can use dot notation (such as "readonly.dev" and "readonly.user") to provide a logical hierarchy. The hierarchy approach is optional; it is purely provided to allow you to organize your scopes in a logical manner that makes sense to you. Your end user would still need to belong to groups that have either "readonly.dev" or "readonly.user" scope assigned to them, the ".dev" and ".user" extensions do not in themselves have any meaning to the IdP.

For example, you could create a service access list with the server name of "ReadOnly", with two scopes defined: "ReadOnly.dev" and "ReadOnly.user". You would then set the ReadOnly.dev scope to the resources to be accessible to developers, and the ReadOnly.user scope to the resrouces to be accessible to users only.

When determining scope names, it may also be helpful to think of the overall solution, which can be a complex system with many services all working together. You can evaluate the access needs of the various services and operations, and then identify the list of scopes that would allow you to provide (or restrict) access to your various groups of users.

In summary, there is no restriction on the names you choose for scopes. You can set them as you wish, depending on what you want to achieve.