WSScope access (function)

Specify security in the REST service via scopes.

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 at the function level.

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 the service information record of the module. See WSScope (module) for an example setting access via scopes for the whole Web service (the module).

Example 1: Setting security with WSScope at function level

In this sample REST function there is an example of a function that requires authentication to access it. To execute this REST operation requires the request contains an access token with a scope that matches what is in WSScope.

The WSScope attribute is set in the ATTRIBUTES clause of the function. In this example the scope is set to "profile" or "profile.me".

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.

WSThrows is set to handle errors. In the TRY/CATCH block, the sqlca record is checked after the execution of the SQL query. The SQLERRMESSAGE is set to the message field of the userError variable, and a call to SetRestError() returns the message defined in WSThrows for the error.

IMPORT com

TYPE profileType RECORD
     id INTEGER,
     name VARCHAR(100),
     email VARCHAR(255)
     # ...
   END RECORD

PUBLIC FUNCTION FetchMyUserProfile( id INTEGER ATTRIBUTES(WSQuery) )
  ATTRIBUTES(
    WSGet,
    WSPath = "/users/profile",
    WSDescription = "Returns a user profile, requires authentication",
    WSThrows = "404:user not found",
    WSScope = "profile, profile.me")
  RETURNS profileType ATTRIBUTES(WSName = "data",
                                 WSMedia = "application/json,application/xml")
    DEFINE p profileType
    TRY
      SELECT * INTO p.* FROM users
             WHERE @id = id
      IF sqlca.sqlcode = NOTFOUND THEN
        CALL com.WebServiceEngine.SetRestError(404,NULL)
      END IF
    CATCH
       CALL com.WebServiceEngine.SetRestError(505,NULL)
    END TRY
    RETURN p
END FUNCTION

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.