Roles Roles Roles Roles Class

Definición

Administra la pertenencia del usuario a roles para el control de autorización en una aplicación ASP.NET.Manages user membership in roles for authorization checking in an ASP.NET application. Esta clase no puede heredarse.This class cannot be inherited.

public ref class Roles abstract sealed
public static class Roles
type Roles = class
Public Class Roles
Herencia
RolesRolesRolesRoles

Ejemplos

En el ejemplo siguiente se muestra el archivo Web. config para una aplicación configurada para utilizar los roles de pertenencia a SqlRoleProvider ASP.net y ASP.net y para usar el para almacenar información de pertenencia y roles en una base de datos de SQL Server.The following example shows the Web.config file for an application configured to use both ASP.NET membership and ASP.NET roles and to use the SqlRoleProvider to store membership and role information in a SQL Server database. Los usuarios se autentican con la autenticación de formularios y solo se permite el acceso a la aplicación a los usuarios del rol administradores.Users are authenticated with forms authentication and only users in the Administrators role are allowed access to the application.

<configuration>  
  <connectionStrings>  
    <add name="SqlServices" connectionString="Data Source=localhost;Initial Catalog=aspnetdb;Integrated Security=SSPI;" />  
  </connectionStrings>  
  
  <system.web>  
    <authentication mode="Forms" >  
      <forms loginUrl="login.aspx"  
      name=".ASPXFORMSAUTH" />  
    </authentication>  
  
    <authorization>  
      <deny users="?" />  
      <allow roles="Administrators" />  
      <deny users="*" />  
    </authorization>  
  
    <membership defaultProvider="AspNetSqlProvider" userIsOnlineTimeWindow="15">  
    </membership>  
  
    <roleManager defaultProvider="SqlProvider"   
      enabled="true"  
      cacheRolesInCookie="true"  
      cookieName=".ASPROLES"  
      cookieTimeout="30"  
      cookiePath="/"  
      cookieRequireSSL="true"  
      cookieSlidingExpiration="true"  
      cookieProtection="All" >  
  
      <providers>  
        <clear />  
        <add  
          name="SqlProvider"  
          type="System.Web.Security.SqlRoleProvider"  
          connectionStringName="SqlServices"  
          applicationName="SampleApplication" />  
        </providers>  
  
    </roleManager>  
  </system.web>  
</configuration>  

En el ejemplo de código siguiente se comprueba mediante programación si el usuario que ha iniciado sesión tiene el rol administradores antes de permitir que el usuario vea los roles de otros usuarios.The following code example programmatically checks whether the logged-on user is in the Administrators role before allowing the user to view other users' roles.

Comentarios

La administración de roles de ASP.NET le permite administrar la autorización de la aplicación en función de grupos de usuarios, denominados roles.ASP.NET role management enables you to manage authorization for your application based on groups of users, referred to as roles. Mediante la asignación de usuarios a roles, puede controlar el acceso a diferentes partes o características de la aplicación web en función del rol en lugar de, o además de, especificando la autorización basada en el nombre de usuario.By assigning users to roles, you can control access to different parts or features of your Web application based on role instead of, or in addition to, specifying authorization based on user name. Por ejemplo, una aplicación de empleado podría tener roles como administradores, empleados, directores, etc., donde se especifican privilegios diferentes para cada rol.For example, an employee application might have roles such as Managers, Employees, Directors, and so on, where different privileges are specified for each role.

Los usuarios pueden pertenecer a más de un rol.Users can belong to more than one role. Por ejemplo, si su sitio es un foro de discusión, algunos usuarios podrían estar en el rol de miembros y moderadores.For example, if your site is a discussion forum, some users might be in the role of both Members and Moderators. Puede definir cada rol para que tenga privilegios diferentes en el sitio, y un usuario que tenga ambos roles tendrá ambos conjuntos de privilegios.You might define each role to have different privileges on the site, and a user who is in both roles would then have both sets of privileges.

Para habilitar la administración de roles para la aplicación ASP.net, use el elemento roleManager system.web de la sección en el archivo Web. config de la aplicación, como se muestra en el ejemplo siguiente.To enable role management for your ASP.NET application, use the roleManager element of the system.web section in the Web.config file for your application, as shown in the following example.

<configuration>  
  <connectionStrings>  
    <add name="SqlServices" connectionString="Data Source=localhost;Initial Catalog=aspnetdb;Integrated Security=SSPI;" />  
  </connectionStrings>  
  
  <system.web>  
    <authentication mode="Forms" >  
      <forms loginUrl="login.aspx"  
      name=".ASPXFORMSAUTH" />  
    </authentication>  
  
  <roleManager defaultProvider="SqlProvider"   
    enabled="true"  
    cacheRolesInCookie="true"  
    cookieName=".ASPROLES"  
    cookieTimeout="30"  
    cookiePath="/"  
    cookieRequireSSL="false"  
    cookieSlidingExpiration="true"  
    cookieProtection="All" >  
    <providers>  
      <add  
        name="SqlProvider"  
        type="System.Web.Security.SqlRoleProvider"  
        connectionStringName="SqlServices"  
        applicationName="SampleApplication" />  
      </providers>  
    </roleManager>  
  </system.web>  
</configuration>  

Puede especificar reglas de autorización en el archivo de configuración de la aplicación web o mediante programación en el código.You can specify authorization rules in the configuration file for your Web application or programmatically in your code. Por ejemplo, la siguiente sección de autorización de un archivo Web. config requiere que los usuarios inicien sesión (mediante la denegación de usuarios anónimos) y, a continuación, solo permite que los usuarios del rol administradores tengan acceso.For example, the following authorization section from a Web.config file requires users to log on (by denying anonymous users), and then allows only users in the Administrators role to have access.

<authorization>  
  <deny users="?" />  
  <allow roles="Administrators" />  
  <deny users="*" />  
</authorization>  

Si usa la sección authorization del archivo Web. config de la aplicación para especificar la autorización basada en roles, los usuarios de la aplicación deben proporcionar una identidad de usuario autenticada.If you use the authorization section in your application's Web.config file to specify authorization based on roles, users of your application must supply an authenticated user identity. Puede autenticar a los usuarios mediante la autenticación de Windows o de formularios.You can authenticate users by using either Windows or Forms authentication. Los usuarios anónimos no se pueden asignar a un rol.Anonymous users cannot be assigned to a role. Los roles se pueden usar independientemente de las clases ASP.net Membership , o junto con ellas.Roles can be used independently of, or in conjunction with, the ASP.NET Membership classes.

Para comprobar la pertenencia a roles mediante programación, puede Roles usar la clase Page.User o la propiedad IsUserInRole con el método, o puede usar Page.User la propiedad con IPrincipal.IsInRole el método.To verify role membership programmatically, you can use the Roles class or the Page.User property with the IsUserInRole method, or you can use the Page.User property with the IPrincipal.IsInRole method. Para ver el código de ejemplo que comprueba la pertenencia a roles mediante programación, vea la sección ejemplo de este tema.For sample code that programmatically checks role membership, see the Example section in this topic.

La Roles clase también le permite crear y eliminar roles, así como agregar usuarios a los roles o quitarlos de ellos.The Roles class also enables you to create and delete roles and to add users to or remove users from roles.

Nota

Si ha configurado la aplicación para que use la WindowsTokenRoleProvider clase, no podrá modificar roles ni pertenencia a roles.If you have configured your application to use the WindowsTokenRoleProvider class, you cannot modify roles or role membership. La WindowsTokenRoleProvider clase solo comprueba la pertenencia a grupos de seguridad de Windows.The WindowsTokenRoleProvider class verifies membership in Windows security groups only. En este caso, debe usar la administración de cuentas de usuario de Windows en lugar de los roles de ASP.NET para crear y eliminar grupos y administrar la pertenencia a grupos.In this case, you must use Windows user account management rather than ASP.NET roles to create and delete groups and manage group membership.

Puede almacenar información de roles en varios orígenes de datos.You can store role information in several data sources.

  • Puede utilizar la clase WindowsTokenRoleProvider para recuperar información de roles en función de la pertenencia a grupos de Windows.You can use the WindowsTokenRoleProvider class to retrieve role information based on membership in Windows groups.

  • Puede almacenar la información de roles en una base de datos de SqlRoleProvider SQL Server mediante la clase.You can store role information in a SQL Server database by using the SqlRoleProvider class.

  • Si tiene información de rol existente o desea almacenar información de roles en y recuperar información de roles de un origen de datos que no sea Windows, un almacén de autorización o un SQL Server, puede implementar un proveedor de roles personalizado creando una clase que herede el RoleProvider clase abstracta.If you have existing role information, or want to store role information in and retrieve role information from a data source other than Windows, an Authorization Store, or SQL Server, you can implement a custom role provider by creating a class that inherits the RoleProvider abstract class. Para obtener más información, consulte implementación de un proveedor de roles.For more information, see Implementing a Role Provider.

Si el explorador de un usuario acepta cookies, puede almacenar la información de roles para ese usuario en una cookie en el equipo del usuario.If a user's browser accepts cookies, you can store role information for that user in a cookie on the user's computer. En cada solicitud de página, ASP.NET lee la información de rol para ese usuario de la cookie.On each page request, ASP.NET reads the role information for that user from the cookie. Esto puede mejorar el rendimiento de la aplicación reduciendo la cantidad de comunicación necesaria con el origen de datos para recuperar la información del rol.This can improve application performance by reducing the amount of communication required with the data source to retrieve role information. Si la información de rol de un usuario es demasiado larga para almacenarla en una cookie, ASP.NET almacena solo la información de los roles usados más recientemente en la cookie y, a continuación, busca información de roles adicional en el origen de datos según sea necesario.If the role information for a user is too long to store in a cookie, ASP.NET stores just the most recently used role information in the cookie and then looks up additional role information in the data source as required. Si el explorador del usuario no admite cookies o las cookies están deshabilitadas, la información de roles no se almacena en caché en una cookie.If the user's browser does not support cookies or cookies are disabled, role information is not cached in a cookie.

Puede mejorar la confiabilidad de los nombres de rol almacenados en caché en una cookie especificando una CookieProtectionValue propiedad al configurar los roles de ASP.net.You can improve the reliability of the role names cached in a cookie by specifying a CookieProtectionValue property when you configure ASP.NET roles. El valor CookieProtectionValue predeterminado Alles, que cifra los nombres de rol de la cookie y valida que el contenido de la cookie no se ha modificado.The default CookieProtectionValue is All, which encrypts role names in the cookie and validates that the cookie contents have not been altered.

Propiedades

ApplicationName ApplicationName ApplicationName ApplicationName

Obtiene o establece el nombre de la aplicación para la que se va a almacenar y recuperar información de roles.Gets or sets the name of the application to store and retrieve role information for.

CacheRolesInCookie CacheRolesInCookie CacheRolesInCookie CacheRolesInCookie

Obtiene un valor que indica si los roles del usuario actual se almacenan provisionalmente en una cookie.Gets a value indicating whether the current user's roles are cached in a cookie.

CookieName CookieName CookieName CookieName

Obtiene el nombre de la cookie donde están almacenados los nombres de rol.Gets the name of the cookie where role names are cached.

CookiePath CookiePath CookiePath CookiePath

Obtiene la ruta de acceso de la cookie de nombres de rol.Gets the path for the cached role names cookie.

CookieProtectionValue CookieProtectionValue CookieProtectionValue CookieProtectionValue

Obtiene un valor que indica cómo se protegen los nombres de rol almacenados provisionalmente en una cookie.Gets a value that indicates how role names cached in a cookie are protected.

CookieRequireSSL CookieRequireSSL CookieRequireSSL CookieRequireSSL

Obtiene un valor que indica si la cookie de nombres de rol requiere SSL para su devolución al servidor.Gets a value indicating whether the role names cookie requires SSL in order to be returned to the server.

CookieSlidingExpiration CookieSlidingExpiration CookieSlidingExpiration CookieSlidingExpiration

Indica si la fecha y hora de expiración de la cookie de nombres de rol se restablece periódicamente.Indicates whether the role names cookie expiration date and time will be reset periodically.

CookieTimeout CookieTimeout CookieTimeout CookieTimeout

Obtiene el número de minutos antes de que expire la cookie de roles.Gets the number of minutes before the roles cookie expires.

CreatePersistentCookie CreatePersistentCookie CreatePersistentCookie CreatePersistentCookie

Obtiene un valor que indica si la cookie de nombres de rol es para una sesión o persistente.Gets a value indicating whether the role-names cookie is session-based or persistent.

Domain Domain Domain Domain

Obtiene el valor del dominio de la cookie de nombres de rol.Gets the value of the domain of the role-names cookie.

Enabled Enabled Enabled Enabled

Obtiene o establece un valor que indica si está habilitada la administración de roles para la aplicación Web actual.Gets or sets a value indicating whether role management is enabled for the current Web application.

MaxCachedResults MaxCachedResults MaxCachedResults MaxCachedResults

Obtiene el número máximo de nombres de rol almacenados para un usuario.Gets the maximum number of role names to be cached for a user.

Provider Provider Provider Provider

Obtiene el proveedor de roles predeterminado para la aplicación.Gets the default role provider for the application.

Providers Providers Providers Providers

Obtiene una colección de los proveedores de roles de la aplicación ASP.NET.Gets a collection of the role providers for the ASP.NET application.

Métodos

AddUsersToRole(String[], String) AddUsersToRole(String[], String) AddUsersToRole(String[], String) AddUsersToRole(String[], String)

Agrega los usuarios especificados al rol especificado.Adds the specified users to the specified role.

AddUsersToRoles(String[], String[]) AddUsersToRoles(String[], String[]) AddUsersToRoles(String[], String[]) AddUsersToRoles(String[], String[])

Agrega los usuarios especificados a los roles especificados.Adds the specified users to the specified roles.

AddUserToRole(String, String) AddUserToRole(String, String) AddUserToRole(String, String) AddUserToRole(String, String)

Agrega el usuario especificado al rol especificado.Adds the specified user to the specified role.

AddUserToRoles(String, String[]) AddUserToRoles(String, String[]) AddUserToRoles(String, String[]) AddUserToRoles(String, String[])

Agrega el usuario especificado a los roles especificados.Adds the specified user to the specified roles.

CreateRole(String) CreateRole(String) CreateRole(String) CreateRole(String)

Agrega un rol nuevo al origen de datos.Adds a new role to the data source.

DeleteCookie() DeleteCookie() DeleteCookie() DeleteCookie()

Elimina la cookie donde se almacenan los nombres de rol.Deletes the cookie where role names are cached.

DeleteRole(String, Boolean) DeleteRole(String, Boolean) DeleteRole(String, Boolean) DeleteRole(String, Boolean)

Quita un rol del origen de datos.Removes a role from the data source.

DeleteRole(String) DeleteRole(String) DeleteRole(String) DeleteRole(String)

Quita un rol del origen de datos.Removes a role from the data source.

FindUsersInRole(String, String) FindUsersInRole(String, String) FindUsersInRole(String, String) FindUsersInRole(String, String)

Obtiene una lista de los nombres de usuario de un rol especificado que contienen un nombre de usuario buscado.Gets a list of users in a specified role where the user name contains the specified user name to match.

GetAllRoles() GetAllRoles() GetAllRoles() GetAllRoles()

Obtiene una lista de todas los roles de la aplicación.Gets a list of all the roles for the application.

GetRolesForUser() GetRolesForUser() GetRolesForUser() GetRolesForUser()

Obtiene una lista de los roles en los que está incluido el usuario de la sesión actual.Gets a list of the roles that the currently logged-on user is in.

GetRolesForUser(String) GetRolesForUser(String) GetRolesForUser(String) GetRolesForUser(String)

Obtiene una lista de los roles en que está incluido un usuario.Gets a list of the roles that a user is in.

GetUsersInRole(String) GetUsersInRole(String) GetUsersInRole(String) GetUsersInRole(String)

Obtiene una lista de usuarios incluidos en el rol especificado.Gets a list of users in the specified role.

IsUserInRole(String) IsUserInRole(String) IsUserInRole(String) IsUserInRole(String)

Obtiene un valor que indica si el usuario que inició la sesión actual está incluido en el rol especificado.Gets a value indicating whether the currently logged-on user is in the specified role. La API se ha diseñado únicamente para que se llame en el contexto de un subproceso de solicitud ASP.NET, y en este uso aprobado es seguro para subprocesos.The API is only intended to be called within the context of an ASP.NET request thread, and in that sanctioned use case it is thread-safe.

IsUserInRole(String, String) IsUserInRole(String, String) IsUserInRole(String, String) IsUserInRole(String, String)

Obtiene un valor que indica si el usuario especificado está incluido en el rol especificado.Gets a value indicating whether the specified user is in the specified role. La API se ha diseñado únicamente para que se llame en el contexto de un subproceso de solicitud ASP.NET, y en este uso aprobado es seguro para subprocesos.The API is only intended to be called within the context of an ASP.NET request thread, and in that sanctioned use case it is thread-safe.

RemoveUserFromRole(String, String) RemoveUserFromRole(String, String) RemoveUserFromRole(String, String) RemoveUserFromRole(String, String)

Quita el usuario especificado del rol especificado.Removes the specified user from the specified role.

RemoveUserFromRoles(String, String[]) RemoveUserFromRoles(String, String[]) RemoveUserFromRoles(String, String[]) RemoveUserFromRoles(String, String[])

Quita el usuario especificado de los roles especificados.Removes the specified user from the specified roles.

RemoveUsersFromRole(String[], String) RemoveUsersFromRole(String[], String) RemoveUsersFromRole(String[], String) RemoveUsersFromRole(String[], String)

Quita los usuarios especificados del rol especificado.Removes the specified users from the specified role.

RemoveUsersFromRoles(String[], String[]) RemoveUsersFromRoles(String[], String[]) RemoveUsersFromRoles(String[], String[]) RemoveUsersFromRoles(String[], String[])

Quita los nombres de usuario especificados de los roles especificados.Removes the specified user names from the specified roles.

RoleExists(String) RoleExists(String) RoleExists(String) RoleExists(String)

Obtiene un valor que indica si el nombre de rol especificado ya existe en el origen de datos del rol.Gets a value indicating whether the specified role name already exists in the role data source.

Se aplica a

Consulte también: