Package com.smartgwt.client.util

# Class Authentication

java.lang.Object
com.smartgwt.client.util.Authentication

public class Authentication extends Object
The Authentication or Auth class represents a convenient, standard place to keep information about the currently logged in user and their assigned user roles.

The intended usage is that a server authentication system would require the user to log in, then provide data about the currently logged in user via `setCurrentUser()` and `setRoles()`. This data is then available in the `Rule Scope` so that components can use it to enable or disable or hide themselves, via properties such as `FormItem.readOnlyWhen`.

The format for user records is not explicitly defined or restricted by the Authentication subsystem but we recommend using the format described by `getUserSchema()`.
Having a standardized user record allows application designers to rely on a well-known set of field names at design time, and then at deployment time when a particular authentication system is chosen, the deployer can simply fill in the standardized user record from the data that the chosen authentication system returns. This also allows authentication systems to be swapped out in the future without the need to change application code.

The DataSource returned by `getUserSchema()` is used solely for visual tools to help with application authoring.
It is not intended to be used directly to store and retrieve user data, and while we recommend this format it is not a requirement that user records conform to it.

There are no security implications to calling `setRoles()` or other APIs on the `Authentication` class. The provided data affects only client-side components. All actual security enforcement must be done server-side - see the QuickStart Guide, especially the sections on Declarative Security, to understand how role-based authorization can be used on the server.

Rule Context

The default ruleContext obtained from `Canvas.getRuleContext()` includes a property for the current authentication information (based on `getUserSchema()`):

- auth

- currentUser

- firstName
- lastName
- ... other fields in schema

- roles
- isSuperUser

The default rule context would therefore include something like the following, expressed in JSON:

      {
       auth : {
          currentUser : {
             userId: "lisa",
             firstName: "Lisa",
             lastName: "Admin",
             roles: "admin",
             ..other properties..
          },
          roles : ['admin'],
          isSuperUser : false
       },
       ..other properties..
      }

Since the `currentUser` information is based on `getUserSchema()` any changes to the schema implemented as an override will be reflected in the rule context.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Authentication()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String[]`
  `getAvailableRoles()`
  Returns the full set of available user roles specified by `setAvailableRoles()`.
  `static Record`
  `getCurrentUser()`
  Returns the current user specified by `setCurrentUser()`.
  `static String`
  `getCurrentUserId()`
  Convenience method to return the `"userId"` attribute of the `current user` if there is one.
  `static String[]`
  `getRoles()`
  Returns the current set of user roles.
  `static DataSource`
  `getUserSchema()`
  Returns a DataSource describing the standard schema for user data.
  `static Boolean`
  `hasRole(String role)`
  Is the current user assigned to the specified role?
  `static void`
  `isSuperUser(Boolean isSuperUser)`
  Has the current user been marked as a super-user via `setSuperUser()`?
  `static void`
  `setAvailableRoles(String[] roles)`
  Specify the full set of available user roles.
  `static void`
  `setCurrentUser(Record user)`
  Set up the current user.
  `static void`
  `setRoles(String[] roles)`
  Set the user roles for the current user.
  `static void`
  `setSuperUser(Boolean isSuperUser)`
  Mark the current user as a super-user.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Authentication

    public Authentication()

- ## Method Details

  - ### getAvailableRoles

    public static String[] getAvailableRoles()
    Returns the full set of available user roles specified by `setAvailableRoles()`.
    Returns:
      full set of possible user roles.

  - ### getCurrentUser

    public static Record getCurrentUser()
    Returns the current user specified by `setCurrentUser()`.

    This method returns the user record currently available in the `Canvas.ruleScope` as "auth.currentUser".

    Returns:
      Record with attributes detailing the current user

  - ### getCurrentUserId

    public static String getCurrentUserId()
    Convenience method to return the `"userId"` attribute of the `current user` if there is one.
    Returns:
      userId attribute of the `current user record` if there is one.

  - ### getRoles

    public static String[] getRoles()
    Returns the current set of user roles. For `super users` this will be the intersection of any roles specified by `setRoles()` and the full set of `available roles` - otherwise it will be the set of roles specified by `setRoles()`.

    Current set of user roles are available in the `Canvas.ruleScope` as a top-level property "userRoles", so that it can be used in criteria such as `Canvas.visibleWhen` or `FormItem.readOnlyWhen`.

    Returns:
      set of roles which apply to the current user

  - ### getUserSchema

    public static DataSource getUserSchema()
    Returns a DataSource describing the standard schema for user data.

    The schema contains the following fields:

    Field Name | Type
    "userId" | "text"
    "email" | "text"
    "firstName" | "text"
    "lastName" | "text"
    "title" | "text"
    "phone" | "phoneNumber"
    "superUser" | "boolean"

    Returns:
      user schema dataSource

  - ### hasRole

    public static Boolean hasRole(String role)
    Is the current user assigned to the specified role?
    Parameters:
      `role` - role to check in current roles
    Returns:
      true if the user has the role in its `getRoles()` list; false otherwise
    See Also:
      - `getRoles()`

  - ### isSuperUser

    public static void isSuperUser(Boolean isSuperUser)
    Has the current user been marked as a super-user via `setSuperUser()`?
    Parameters:
      `isSuperUser` - New super user status

  - ### setAvailableRoles

    public static void setAvailableRoles(String[] roles)
    Specify the full set of available user roles.

    Note that if the current user has been marked as a `superUser`, `getRoles()` will return the full set of available roles.

    Parameters:
      `roles` - full set of possible user roles.

  - ### setCurrentUser

    public static void setCurrentUser(Record user)
    Set up the current user. This method makes the user record available in the `Canvas.ruleScope` as "auth.currentUser".
    Parameters:
      `user` - Record with attributes detailing the current user

  - ### setRoles

    public static void setRoles(String[] roles)
    Set the user roles for the current user. Roles may be retrieved via `getRoles()`.

    Calling setRoles() makes the specified set of user roles available in the `Canvas.ruleScope` as a top-level property "userRoles", so that it can be used in criteria such as `Canvas.visibleWhen` or `FormItem.readOnlyWhen`.

    Note that if this current user has been `marked as a super-user`, `getRoles()` will return the full set of available roles rather than the set of roles specified here.

    Parameters:
      `roles` - set of roles which apply to the current user

  - ### setSuperUser

    public static void setSuperUser(Boolean isSuperUser)
    Mark the current user as a super-user. This causes `getRoles()` to return the full set of `available roles` if specified
    Parameters:
      `isSuperUser` - New super user status