NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

<security> Section Handler

Establishes all security settings used by the XSP security HttpModule.

<security>
   <authentication mode="[Windows/Cookie/Passport]">
      <cookie cookie="[name]" loginurl="[url]" decryptionkey="[key]">
         <credentials passwordformat="[Clear, SHA1, MD5]">
            <user name="[UserName]" password="[password]"/>
         </credentials>
      </cookie>
   </authentication>

   <authorization>
      <allow 
         users="[comma separated list of users]"
         roles="[comma separated list of roles]"/>
      <deny 
         users="[comma separated list of users]"
         roles="[comma separated list of roles]"/>
   </authorization>

   <identity>
      <codeaccess permissionset="[permissionset filename]">
      <impersonation enable="[true/false]"/>
   </identity>
</security>

The <authentication> Subtag

The <authentication> subtag supports one attribute – mode – that controls the default authentication mode for an application, and can be set to one of the following string values: "windows", "cookies", or "passport". It also supports one subelement - <cookie> - that defines cookie authentication settings.

The <cookie> Subtag

Contained within the <security> subtag is the <cookie> subtag, which supports three attributes.

Attribute Description
cookie Name of the HTTP Cookie to use for the authentication ticket. By default this is value is .ASPXAUTH.
loginurl The URL to which the request is redirected if it doesn’t contain a valid authentication ticket.
decryptionkey A key used to decrypt authentication tickets. If login and authentication are distributed across multiple machines, they all need to share the same key. The key is stored in cleartext.

The <cookie> subtag optionally allows users to define name/password credentials within the <credentials> subtag. Alternatively, developers can implement their own custom password scheme where validation occurs from external stores like databases, etc.

The <credentials> Subtag

Credentials are captured within a <credentials> subtag, which is contained within the <cookie> subtag. This subtag contains one attribute – passwordformat – that defines the encryption format used to store passwords (clear, MD5, or SHA1). The <credentials> sub-tag in turn supports multiple <user> sub-tags, each of which records the user login name and password.

Attribute Description
name User login name.
password User password

The <authorization> Subtag

This subtag is contained within the <security> subtag, and controls client access to URL resources. Sub-directories hierarchically inherit settings specified within an <authorization> section.

The <authorization> section is configured using two subtag directives, “allow” and “deny”, which are interpreted and processed in top-down sequential order. <allow> tags enable administrators to explicitly identify a class of users (either via usernames, roles, anonymous or all access) to grant access to. <deny> tags explicitly identify a class of users to which access is denied.

At runtime, the authorization module iterates through the <allow> and <deny> tags looking for the first access rule that fits a particular user. It decides to grant or reject access to a URL resource depending upon the whether the first access rule satisfied is either an <allow> or <deny> rule. By default it rejects access if no rule (either an allow or deny one) is found.

Directive Description
allow Allows access to a URL resource. Access is granted based on the following filtering constraints:

Users: A comma separated list of “user names” that should be granted access. The "?" character allows anonymous users and the "*" character is used to indicate that all users are accepted.

Roles: A comma separated list of “roles” that should be granted access

deny Denies access for a URL resource. Access is denied based on the following filtering constraints:

Users: A comma separated list of “user names” that should be denied access. The "?" character denies anonymous users and the "*" indicates that all users are denied.

Roles: A comma separated list of “roles” that should be denied access.

The <identity> Subtag

The <identity> subtag is contained within the <security> subtag, and defines the application-level identity of code running on the server. It supports two subtags:

Attribute Description
impersonation Controls whether client NT impersonation is used on each request. For legacy ASP/IIS purposes, this value by default is “true”
codeaccess Controls whether NGWS runtime code-access security is enabled, and if so what permissionset is used to guard the code running on the server.

Example:

<configsections>
   <add name="security" type="System.Web.Config.SecurityConfigHandler">
</configsections>

<security>
   <authentication mode="Cookie">
      <cookie cookie="401kApp" loginurl="/login.aspx"
                      decryptionkey="1!#$$">
         <credentials passwordformat="SHA1">
            <user name="Mary" password="GASDFSA9823423BSD"/>
            <user name="John" password="ZA#$34343443BSD44"/>
            <user name="Fred" password="IFSKDSJFSLKFJKDLS##"/>
         </credentials>
      </cookie>
   </authentication>

   <authorization>
      <allow roles="Admins", "Managers" />
      <allow users="Fred, "John" />
      <deny users="Jack", "Joe" />
   </authorization>

   <identity>
      <impersonation enable="false"/>
      <codeaccess permissionset="foo.xml"/>
   </identity>
</security>

Requirements

Contained Within: <configuration>

Web Platform: IIS 5.0

Configuration File: config.web

Configuration Section Handler:

System.Web.Config.SecurityConfigHandler

See Also

ASP+ Configuration Concepts; ASP+ Web Application Security