Share via

AccessChecker Samples

  • Article

Important

For a complete walkthrough, see Walkthrough: Using the Business Data Catalog Security Trimmer to Trim Search Results.

An AccessChecker is a method that returns the rights a user has on one or more entity instances. A right can be a single bit or a collection of bits. The rights, once determined, can be used by Business Data client applications via the CheckAccess method. For example, consider a user building a custom Web Part on the Business Data Catalog that displays Create, Edit, and Delete Actions for an EntityInstance metadata object. By defining an AccessChecker method, the user could call Entity.CheckAccess and then conditionally enable one or more of the Actions, depending on what rights are returned.

Entities have zero or more AccessChecker methods.

Note

If the call to Entity.CheckAccess includes multiple entity instance IDs, but the back-end server API can handle only a single entity instance at one time, the Business Data Catalog automatically uses multithreading and instantiates as many threads as are needed to obtain the rights for all the requested entity instances. In the following Database Example and in Web Service Examples 2 and 3, multithreading is used by the Business Data Catalog because, in these cases, the back-end methods take only a single ID in the input parameter.

Database Example

Following is a simple example of an AccessChecker method instance for a database system. This example assumes that you have a table named RightsTable, which has the following three columns:

  • CustomerId   IDs of the customer entity instances

  • Username   Holds the user names.

  • Rights   Represents the rights that each user represented by the Username has on the Customer entity instance.

        <Method Name="UserRightsForCustomer">
          <Properties>
            <Property Name="RdbCommandText" Type="System.String">
              SELECT CAST(Rights as bigint)
              FROM Customers
              WHERE
                CustomerId = @CustomerId and UserName = @currentuser;
              </Property>
            <Property Name="RdbCommandType" Type="System.Data.CommandType, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">Text</Property>
          </Properties>
          <FilterDescriptors>
            <FilterDescriptor Type="UserContext" Name="currentuser" />
          </FilterDescriptors>
          <Parameters>
            <Parameter Direction="In" Name="@CustomerId">
              <TypeDescriptor TypeName="System.String" IdentifierName="CustomerId" Name="CustomerId" />
            </Parameter>
            <Parameter Direction="In" Name="@currentuser">
              <TypeDescriptor TypeName="System.String" AssociatedFilter="currentuser" Name="currentuser" />
            </Parameter>
            <Parameter Direction="Return" Name="RightsForUser">
              <TypeDescriptor TypeName="System.Data.SqlClient.SqlDataReader, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true" Name="AccessCheckDataReader">
                <TypeDescriptors>
                  <TypeDescriptor TypeName="System.Data.IDataRecord, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" Name="AccessCheckRecord">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName="System.Int64" Name="Rights" />
                    </TypeDescriptors>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
          </Parameters>
          <MethodInstances>
            <MethodInstance Type="AccessChecker" ReturnParameterName="RightsForUser" ReturnTypeDescriptorName="Rights" ReturnTypeDescriptorLevel="2" Name="UserRightsForCustomer" />
          </MethodInstances>
        </Method>

Web Service Examples

Following are a few examples of AccessChecker method instances for a Web service system. These examples assume that you have an entity called Contacts in your Web service system and that it has two identifiers as defined in the following code.

    <Identifiers>
       <Identifier Name=""id1"" TypeName=""System.String""/>
       <Identifier Name=""id2"" TypeName=""System.Int32""/>
    </Identifiers>

Notice that there are several different ways you can model your AccessChecker method, depending on the back-end API design of the method that returns the user's rights.

Web Service Example 1

This example assumes that the back-end API can take the IDs for several entity instances and return the rights the user has on all of those instances. Notice that a System.Int64[] array of values is returned, which the Business Data Catalog will return to the calling Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int64 CheckUserAccess1(System.Object[] in, System.String in2)

<Method Name="CheckUserAccess1">
  <FilterDescriptors>
    <FilterDescriptor Name="fd" Type="UserContext"/>
  </FilterDescriptors>
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in" TypeName="System.Object[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName=" + typeof(IdCase1).AssemblyQualifiedName + @" >
            <TypeDescriptors>
              <TypeDescriptor Name="Id1" TypeName="System.String" IdentifierName="id1"/>
              <TypeDescriptor Name="Id2" TypeName="System.Int32" IdentifierName="id2"/>
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="in2" Direction="In" >
      <TypeDescriptor Name="in" TypeName="System.String" AssociatedFilter="fd">
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int64[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Int64" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess1" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item" />
  </MethodInstances>
</Method>

Web Service Example 2

This example assumes that the back-end API takes the IDs for a single entity instance and returns the rights the user has on that instance. Notice that a System.Int64 value is returned, which the Business Data Catalog will return to the calling Entity.CheckAccess method. In this example, the Business Data Catalog uses multithreading and instantiates as many threads as are needed to obtain the rights for all the entity instances requested in the Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int64 CheckUserAccess2(System.Int32 in1, System.Int32 in2)

<Method Name="CheckUserAccess2">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in1" TypeName="System.String" IdentifierName="id1">
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="in2" Direction="In" >
      <TypeDescriptor Name="in2" TypeName="System.Int32" IdentifierName="id2">
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int64">
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess2" Type="AccessChecker" ReturnParameterName="out" />
  </MethodInstances>
</Method>

Web Service Example 3

This example assumes that the back-end API takes the IDs for a single entity instance and returns the rights the user has on that instance. Notice that a System.Int64[] array is returned by the back-end method. The Business Data Catalog will return it to the calling Entity.CheckAccess method. In this example, the Business Data Catalog uses multithreading and instantiates as many threads as are needed to obtain the rights for all the entity instances requested in the Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int64[] CheckUserAccess3(System.String in1, System.Int32 in2)

<Method Name="CheckUserAccess3">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in1" TypeName="System.String" IdentifierName="id1">
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="in2" Direction="In" >
      <TypeDescriptor Name="in2" TypeName="System.Int32" IdentifierName="id2">
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int64[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Int64" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess3" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item"/>
  </MethodInstances>
</Method>

Web Service Example 4

This example assumes that the back-end API can take the IDs for several entity instances and return the rights the user has on all of those instances. Notice that a System.Int64[] array of values is returned, which the Business Data Catalog will return to the calling Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int64[] CheckUserAccess4(YourCompany.CustomTypes.IdCase4a[] in1, YourCompany.CustomTypes.IdCase4b[] in2)

Following is how the custom types used in this example might look:

class IdCase4a

{

public System.String Id1;

}

class IdCase4b

{

public System.String Id2;

}

<Method Name="CheckUserAccess4">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in1" TypeName="YourCompany.CustomTypes.IdCase4a[], + typeof(IdCase4a).Assembly.FullName + @""" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName=" + typeof(IdCase4a).AssemblyQualifiedName + @" >
            <TypeDescriptors>
              <TypeDescriptor Name="Id1" TypeName="System.String" IdentifierName="id1"/>
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="in2" Direction="In" >
      <TypeDescriptor Name="in2" TypeName="YourCompany.CustomTypes.IdCase4b[], + typeof(IdCase4b).Assembly.FullName + @""" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName=" + typeof(IdCase4b).AssemblyQualifiedName + @" >
            <TypeDescriptors>
              <TypeDescriptor Name="Id2" TypeName="System.Int32" IdentifierName="id2"/>
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int64[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Int64" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess4" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item" />
  </MethodInstances>
</Method>

Web Service Example 5

This example assumes that the back-end API can take the IDs for several entity instances and return the rights the user has on all of those instances. Notice that a System.Int32[] array of values is returned, which the Business Data Catalog will convert to long[] before returning it to the Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int32 [] CheckUserAccess5(System.String[] in1, System.Int32[] in2)

Following is how the custom types used in this example might look:

class IdCase4a

{

public System.String Id1;

}

class IdCase4b

{

public System.String Id2;

}

<Method Name="CheckUserAccess5">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in1" TypeName="System.String[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="Id1" TypeName="System.String" IdentifierName="id1"/>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="in2" Direction="In" >
      <TypeDescriptor Name="in2" TypeName="System.Int32[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="Id2" TypeName="System.Int32" IdentifierName="id2"/>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int32 []" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Int32" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess5" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item" />
  </MethodInstances>
</Method>

Web Service Example 6

This example assumes that the back-end API can take the IDs for several entity instances and return the rights the user has on all of those instances. Notice that a System.Int32[] array of values is returned, which the Business Data Catalog will convert to long[] before returning it to the Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public YourCompany.CustomTypes.ReturnContainer CheckUserAccess6(YourCompany.CustomTypes.IdContainer in1)

Here is how the custom types used in this example might look:

class IdContainer

{

public YourCompany.CustomTypes.IdCase6[] ids;

}

class IdCase6

{

public YourCompany.CustomTypes.IdCase1``item;

}

class IdCase1

{

public System.String Id1;

public System.Int32 Id2;

}

class ReturnContainer

{

public System.Int32[] ints;

}

<Method Name="CheckUserAccess6">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in1" TypeName="YourCompany.CustomTypes.IdContainer, + typeof(IdCase4a).Assembly.FullName + @""" >
        <TypeDescriptors>
          <TypeDescriptor Name="ids" TypeName="YourCompany.CustomTypes.IdCase6[],  + typeof(IdCase1).Assembly.FullName + @""" IsCollection="true">
            <TypeDescriptors>
              <TypeDescriptor Name="item" TypeName=" + typeof(IdCase1).AssemblyQualifiedName + @" >
                <TypeDescriptors>
                  <TypeDescriptor Name="Id1" TypeName="System.String" IdentifierName="id1"/>
                  <TypeDescriptor Name="Id2" TypeName="System.Int32" IdentifierName="id2"/>
                </TypeDescriptors>
              </TypeDescriptor>
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName=" + typeof(ReturnContainer).AssemblyQualifiedName + @" >
        <TypeDescriptors>
          <TypeDescriptor Name="ints" TypeName="System.Int32[]" IsCollection="true">
            <TypeDescriptors>
              <TypeDescriptor Name="item" TypeName="System.Int32" />
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess6" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item" />
  </MethodInstances>
</Method>

Web Service Example 7

This example assumes that the back-end API can take the IDs for several entity instances and return the rights the user has on all of those instances. Notice that a System.Int64[] array of values is returned, which the Business Data Catalog will return to the calling Entity.CheckAccess method.

Following is how the back-end public method might look for this example:

public System.Int64[] CheckUserAccess7(System.Object[] in)

<Method Name="CheckUserAccess7">
  <Parameters>
    <Parameter Name="in" Direction="In" >
      <TypeDescriptor Name="in" TypeName="System.Object[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Object[]" >
            <TypeDescriptors>
              <TypeDescriptor Name="Id1" TypeName="System.String" IdentifierName="id1"/>
              <TypeDescriptor Name="Id2" TypeName="System.Int32" IdentifierName="id2"/>
            </TypeDescriptors>
          </TypeDescriptor>
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
    <Parameter Name="out" Direction="Return" >
      <TypeDescriptor Name="out" TypeName="System.Int64[]" IsCollection="true">
        <TypeDescriptors>
          <TypeDescriptor Name="item" TypeName="System.Int64" />
        </TypeDescriptors>
      </TypeDescriptor>
    </Parameter>
  </Parameters>
  <MethodInstances>
    <MethodInstance Name="CheckUserAccess7" Type="AccessChecker" ReturnParameterName="out" ReturnTypeDescriptorName="item" />
  </MethodInstances>
</Method>

See Also

Reference

MethodInstance

Concepts

Business Data Catalog Security Trimmer