Quick Links

Overview

The Access Control Service factors access control logic for applications into manageable collections of rules. It consists of three parts: the Portal, the Client API, and the Security Token Service (STS).

Every .NET Services account includes a multi-tenant or virtual Access Control STS. The account owner can configure this STS via the Portal and the Client API. Both the Portal and the Client API provide a means to configure and manage Access Control rules.

The Access Control Service works with Web applications, Web services, and smart clients. The STS can be accessed via WCF in the .NET Framework 3.5, the code name "Geneva" Framework, or any WS-Trust 1.3 complaint development platform.

Architectural Model

The Access Control Service uses the same architectural model for Web applications, Web services, and smart clients. It consists of three participants:

1. The virtual Access Control Service STS
2. An application that trusts the virtual Access Control Service STS (Relying Party)
3. The application that uses the Relying Party (Requestor)

These participants interact with one another in the following manner:

1. The owner of the Relying Party provides the Access Control Service STS with a certificate. This certificate is used by the Access Control Service STS to encrypt tokens that the Relying Party will accept.
2. Before the Requestor can use the Relying Party, the owner of the Relying Party application defines Access Control rules in the STS. These rules logically grant the Requestor access to the Relying Party.
3. The Requestor sends a WS-Trust 1.3-compliant Request for Security Token (RST) to the Access Control STS.
4. The Access Control STS receives the RST, and uses the input claims in the RST to initiate processing of the Access Control rules defined in that STS.
5. After Access Control rule processing, the Access Control STS packages the output into a SAML security token, encrypts that token with the certificate provided in (1), signs the token, and sends the token back to the Requestor.
6. Upon receipt of the token, the Requestor sends the token to the Relying Party along with any other Relying Party-specific payload.
7. When the Relying Party receives the token, it verifies the claims in the token and decides whether the Requestor can access the application.

Portal

The Portal enables users to configure the Access Control Service STS. It has two modes of operation: Basic and Advanced. Basic Mode enables users to create and organize Access Control rules for their applications. Advanced Mode enables users to create and organize Access Control rules for their applications, as well as the Access Control rules for the ServiceBus and Workflow services. A Windows Live ID specified at account creation time is required to log into the Access Control Portal.

NOTE: For the Community Technology Preview shown at PDC, there are some naming differences in the Basic and Advanced modes of the portal. For example, Basic Mode uses the term "Application" while the Advanced Mode uses the term "Scope." Both are equivalent, and this will be resolved in future releases.

Access Control Rules

An Access Control rule describes how the STS will transform input claims to output claims. An Access Control rule can contain many input claims and exactly one output claim. Access Control rules can be chained together to provide Role Based Access Control (RBAC)-style behavior.

Access Control rules are organized by scopes. An Access Control rule exists in exactly one scope. A scope can contain many Access Control rules, and the scope has a URI name (http scheme only). Access Control rule processing occurs in exactly one scope.

Encryption Preferences

Access Control rule processing results in a set of output claims. Before these output claims are sent to the requestor, they are packaged into a SAML token, encrypted with a certificate (encrypting certificate), and signed with the global Access Control Service certificate. The owner of the Access Control STS determines the encrypting certificate that the Access Control Services uses to encrypt tokens. This encrypting certificate can be specified in the Access Control Portal (Basic or Advanced Mode) or the Client API.

Client API

The Client API is contained within the Microsoft.AccessControl.Management.dll assembly and installs with the .NET Services SDK. The types defined within the Client API enable users to programmatically configure their STS. 

NOTE: For the Community Technology Preview shown at PDC, there are some naming differences in the Basic and Advanced modes of the portal and the Client API. For example, Basic Mode uses the term "Application" while the Advanced Mode and the Client API use the term "Scope." This will be resolved in future releases.

STS

The STS receives Requests for Security Tokens (RSTs), uses the claims in those RSTs to drive Access Control Rule Processing, generates security tokens, and packages these security tokens into Requests for Security Token Responses (RSTRs). This interaction is described by WS-Trust 1.3, and by WS-Federation (for Web client cases). The Access Control Service STS accepts RSTs that contain claims issued by any Identity Provider that is compliant with these protocols. From a functional perspective, this means that the owner of an Access Control STS can define Access Control rules that specify individuals or groups that are defined by these different Identity Providers.

NOTE: For the Community Technology Preview shown at PDC, only Windows Live ID and "Geneva" Server have been tested as Identity Providers. We will be expanding test coverage in future versions.

Portal - Basic Mode

The Access Control portal has two modes of use: Basic and Advanced. The Basic mode is designed to simplify configuring and managing Access Control rules for applications that use the Access Control Service STS. It enables users to set up Applications (called Scopes in Advanced Mode), Encryption Preferences, and Access Control rules. It does not allow configuration of custom claim types, identity issuers, or token expiration defaults.

Applications and Certificates

When you log into the Access Control portal and choose Basic Mode, you can navigate to a page titled "Add Application." On this page, you can define a new URI for your application, and you can define a certificate that the Access Control Service STS will use to encrypt the security token. This certificate can be manually uploaded to the portal, or it can be retrieved from the URI (assuming the endpoint is public).

NOTE: For the Community Technology Preview shown at PDC, only the http scheme is allowed. The application can use SSL at run time. This limitation applies only to application naming for the Access Control STS.

The encrypting certificate is not mandatory, but is strongly recommended. If the encrypting certificate is not specified, then the security tokens will be sent to the Requestor and Relying Party in clear text. Unless other security measures are in place, this is not a recommended practice.

Rules

When configuring an Application in Basic Mode, you will see a page titled "Add Access Control Rules." This page consists of two major areas: Input Claims and Output Claims. The following figure shows an example of a rule.

Notice the issuers for the Input Claim and Output Claim. Since the Input Claim Type is Username, only the accesscontrol.windows.net Issuer is allowed. The Issuer for the Output Claim is always the Access Control STS name (accesscontrol.windows.net/<SolutionName>). The value of the Issuer for the Output Claim is never configurable.

Multiple Access Control rules can be defined for a single Application. In such a case, the rules are chained together to allow multiple output claims in a single token. For example, consider the rules shown in the following figure.

Given the three rules above, both the justinsm and dennispi user names will be issued the Calculator.Add and Calculator.Administrator output claims.

Portal - Advanced Mode

The Access Control portal has two modes of use: Basic and Advanced. Advanced mode provides more precise control over Access Control Service STS configuration than the Basic mode. Specifically, it allows configuration of Access Control rules, integration with Identity Providers, granting permissions to edit Access Control rules to other users, configuration of encryption preferences, managing custom claim types, and defining token expiration preferences.

NOTE: See the Release Notes for known issues with Advanced Mode.

Scopes

Advanced Mode Scopes are equivalent to Applications in Basic Mode. Applications defined in Basic Mode are visible in Advanced Mode as scopes. The only difference is the level of configuration control allowed. As implied by the name, Advanced Mode offers more configuration options.

Like Basic Mode, Scopes must have a valid URI name. The Access Control STS uses this name to locate the Access Control rules in response to a received RST. Specifically, the AppliesTo field of the RST is used to determine the Scope. In some cases, the AppliesTo field will not exactly match a Scope name. In this case, the Access Control Service STS searches for the appropriate Scope using a longest-prefix match algorithm.

Rules

Rule functionality in Advanced Mode is equivalent to Basic Mode functionality. For more information, see the Portal—Basic Mode section.

Identity Issuers

Advanced Mode allows users to configure trusted Identity Providers. To accept tokens from a WS-Trust 1.3-compliant Identity Provider, you will need the URI of the Identity Provider and the certificate used by that Identity Provider. This assumes that the Identity Provider has a publicly available endpoint.

When entering an Access Control rule that uses a claim issued by an Identity Provider, the issuer for the Input Claim is the friendly name you specify during Identity Issuer setup.

NOTE: Many Identity Providers require configuration before issuing a token for the Access Control STS. Different Identity Providers might also issue different claim types. Before processing a token issued by an Identity Provider, you should check the claim types issued by that Identity Provider.

NOTE: Encryption Preferences apply per scope, not the entire Access Control Service STS.

Permissions

When creating a scope in the Access Control Service STS, the owner can grant edit permissions on that scope to another .NET Services account holder. For example, if the account account1 creates a scope named http://localhost/CalculatorService, account1 can allow the account2 .NET Services account edit permission on the scope. At that point, account2 can edit, add, or delete rules in the http://localhost/CalculatorService scope.

The Service Bus and Workflow Service take this approach in managing scopes and rules. In a manner similar to other Access Control Service STSs, the Service Bus has its own Access Control Service STS. When a new .NET Services account is provisioned (for example, account1), the provisioning process creates a new scope (http://servicebus.windows.net/services/account1), creates two Access Control rules in that scope, and grants the new .NET Services account (account1) edit permissions on that scope.

NOTE: When in Advanced Mode, a user can edit the permissions on the Service Bus and Workflow Service scopes by selecting those scopes from the drop-down list.

Encryption

Encryption Preference functionality in Advanced Mode is equivalent to Basic Mode functionality. For more information, please see the Portal—Basic Mode section.

NOTE: Encryption Preferences apply per scope, not the entire Access Control Service STS.

Claim Types

Advanced Mode includes support for defining and managing custom claim types. Each Access Control Service STS is configured with a set of claim types. Claim types require a display name and a claim type URI. After a claim type is created, it can be used in Access Control rule values for either input or output claims.

NOTE: Claim types apply per scope, not the entire Access Control Service STS.

Expiration

Advanced Mode includes support for constraining the lifetime of issued tokens. The default token lifetime value defines the default token lifetime, and the maximum token lifetime value defines the maximum token lifetime (regardless of the value specified in the RST).

NOTE: Expiration preferences apply per scope, not the entire Access Control Service STS.

Client API

The Client API installs with the .NET Services SDK and provides programmatic configuration of the Access Control STS. The Microsoft.AccessControl.Management.dll assembly contains the types described here. The Access Control STS can also be configured using REST.

IdentityManagementClient

This class is used to programmatically perform identity management functions associated with a particular sign-in credential (user name/password or Information Card).

public class IdentityManagementClient
{
  public IdentityManagementClient();
  public IdentityManagementClient(ClientCredential credential);
  public IdentityManagementClient(string username, string password);
 
  public AccessRuleManager AccessRuleManager { get; }
  public AccountManager AccountManager { get; }
  public ClientCredential ClientCredential { get; }
  public IssuerManager IssuerManager { get; }
  public ResourceManager ResourceManager { get; }
  public ScopeManager ScopeManager { get; }
  public ServiceSettings ServiceSettings { get; }
 
  public void Close();
}

IssuerManager

This class is used to programmatically manage the system issuers.

public class IssuerManager
{
    public SystemIssuer MySystemIssuer { get; }
    public static SystemIssuer SystemIssuer { get; }
 
    public void AddIssuer(UserDefinedIssuer issuer);
    public void DeleteIssuer(string issuerName);
    public void DeleteIssuer(UserDefinedIssuer issuer);
    public List<Issuer> GetAllUserDefineIssuers();
    public UserDefinedIssuer GetUserDefinedIssuerByName(string issuerName);
    public void UpdateIssuerCertificate(Issuer issuer, X509Certificate2 certificate);
} 

Issuer

This abstract class can be used to represent an issuer.

public abstract class Issuer : ICloneable
{
    protected string type;
    public string Name { get; }
 
    public abstract object Clone();
    public override bool Equals(object obj);
    public override int GetHashCode();
}   
 

SystemIssuer

This class can be used to represent a system issuer.

public class SystemIssuer : Issuer
{
    public SystemIssuer(string name);
 
    public override object Clone();
}

UserDefinedIssuer

This abstract class can be used to represent a user-defined issuer.

public abstract class UserDefinedIssuer : Issuer
{
}

X509CertificateIssuer

This class can be used to represent a third-party issuer, which uses an X.509 certificate as its signing certificate.

public class X509CertificateIssuer : UserDefinedIssuer
{
        // Constructors
        public X509CertificateIssuer(string name);
        public X509CertificateIssuer(string name, X509Certificate2 certificate);
 
        // Properties
        public X509Certificate2 SigningCertificate;
}

AccessRule

This abstract class is used to represent a user-defined access rule.

public abstract class AccessRule
{
    protected ClaimSet inClaims;
 
    public Claim OutClaim { get; set; }
    public string OwnerName { get; set; }
    public int RequiredClaimNumber { get; set; }
    public string Scope { get; set; }
    public AccessRuleStatus Status { get; set; }
}

SimpleAccessRule

This class is used to represent an access rule with only one input claim and one output claim.

public class SimpleAccessRule : AccessRule
{
    public SimpleAccessRule(Claim inClaim, Claim outClaim);
 
    public Claim InClaim { get; set; }
} 

MultipleInputClaimsAccessRule

This class is used to represent an access rule with multiple input claims and one output claim.

public class MultipleInputClaimsAccessRule: AccessRule
{
    // Constructors
    public MultipleInputClaimsAccessRule( ClaimSet inClaims, nt requiredClaimNumber, Claim outClaim);
 
    // Properties
    public ClaimSet InClaims { get; set; }
}

AccessRuleStatus

This enumeration is used to define the status of an access rule.

public enum AccessRuleStatus
{
    Unknown,
    Enabled,
    Disabled
}

Claim

This class is used to represent a claim defined by the user.

public class Claim : ICloneable
{
    // Constructors
    public Claim(string type, string value, Issuer issuer);
    public Claim(string type, string value, string issuerName);
 
    // Properties
    public string Type { get; set; }
    public string Value { get; set; }
    public Issuer Issuer { get; set; }
}

DefaultClaimTypes

This class defines the default claim types configured for each Access Control STS.

public static class DefaultClaimTypes
{
    public const string Action = "http://docs.oasis-open.org/wsfed/authorization/200706/claims/action";
    public const string Email = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/email";
    public const string String = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/string";
    public const string Uri = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/uri";
    public const string UserIdentifier = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/useridentifier";
    public const string UserName = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/username";
    public const string Wlid = "http://schemas.microsoft.com/strata/2008/09/accesscontrol/claims/wlid";
}

ClaimSet

This class is used to represent a set of claims.

public class ClaimSet : ICloneable
{
    // Constructors
    public ClaimSet();
    public ClaimSet(List<Claim> claims);
 
    // Properties
    public int Count { get; }
    public Claim this[int index] { get; set; }
                
    // Methods
    public void AddClaim(Claim claim);
    public void AddClaim(string claimType, string claimValue, Issuer issuer);
    public void RemoveClaim(Claim claim);
    public void RemoveClaim(string claimType, string claimValue, Issuer issuer);
    public bool Contains(Claim claim);
    public object Clone();
}

Scope

This type represents a grouping of access control rules.

public class Scope
{
   public Scope(string owner, string uri);
 
    public string OwnerName { get; }
    public string Uri { get; }
}

ScopeType

This enumerated type is used to describe relative scope attributes.

public enum ScopeType
{
    Owned,
    Delegated,
    Accessible
}