com.smartgwt.client.util

## Class Authentication

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

-     public class Authentication
      extends java.lang.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 and Description
    `Authentication()`

  - ### Method Summary

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

    - #### Authentication

          public Authentication()

  - ### Method Detail

    - #### getAvailableRoles

          public static java.lang.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 java.lang.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 java.lang.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 java.lang.Boolean hasRole(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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