WSScope (module)

Specify security via scopes that applies at the whole Web service level (the module).

Syntax

WSScope = "{ scope } [,...]"

Where WSScope is a comma-separated list of scopes and where:

scope defines access permission for the resource.

WSScope is an optional attribute.

Usage

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

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 service information record of the module at the service level or in the ATTRIBUTES() clause of the REST function. See WSScope (function) for an example setting access using scopes in the REST function.

Example using WSScope in the information record at the service level

When the scope is set in the service information record, 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.

PUBLIC DEFINE serviceInfo RECORD ATTRIBUTE(WSInfo, WSScope="users.myservice")
  title STRING,
  description STRING,
  termOfService STRING,
  contact RECORD
    name STRING,
    url STRING,
    email STRING
    END RECORD,
    version STRING
  END RECORD = (
    title: "my service", 
    version: "1.0", 
    contact: ( email:"helpdesk@mysite.com") )

Note: The main purpose of the service information record (defined with the WSInfo attribute) is to document the REST service. If you are not setting the scope at the modular level here, the record is still needed to provide service information.

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 resources 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.