ACS Management Service

Windows Azure Active Directory Access Control (also known as Access Control Service or ACS)

ACS Management Service is a key component of ACS that allows you to programmatically manage and configure settings in an Access Control namespace. This topic explains the following:

• How the ACS Management Service fits into the overall ACS architecture
  
  
• When it is appropriate to use the ACS Management Service to configure ACS settings
  
  
• How to use the ACS Management Service most effectively
  
  

You can use the ACS Management Service to manage and configure the ACS components in an Access Control namespace programmatically, using the Open Data (OData) protocol. For more information about ACS components, see ACS 2.0 Components.

The following are several scenarios where the ability to manage ACS programmatically can be especially effective:

• SaaS - onboarding new customers (tenants) —Consider the software as a service (SaaS) cloud service, such as Office 365. When signing up for this service, a user might be presented with several authentication options, such as Windows Live ID (Microsoft account), Google, Facebook, Yahoo!, or AD FS 2.0. After the user chooses the desired option, the code that runs in the background sends requests to the ACS Management Service and configures the new tenant for the selected identity provider. For a working example, of a SaaS application that uses the ACS Management Service when onboarding new tenants, including source code, see http://www.fabrikamshipping.com/.
  
  
• Deploying solutions—When deploying your new solution, you might want to add a custom task of configuring ACS as part of the deployment. The ACS Management Service can help you automate the deployment and save on manual configuration after the application is deployed.
  
  
• Custom user interface—You can use the ACS Management Portal (a web-based user interface that is hosted on its own domain) to manage and configure ACS components. However, consider a situation where the user interface is changed for branding purposes, or embedded into a larger management console, or exposed through non-web-based user interface. In these cases, you can use the ACS Management Service to manage and configure your ACS settings.
  
  
• Functionality not available through the ACS Management Portal—In ACS, there are certain administrative tasks that are not completed in the ACS Management Portal, and that you must perform by using the ACS Management Service. For example, in ACS, you can add custom OpenID identity providers only programmatically, via the ACS Management Service.
  
  

To access the ACS Management Service for a specific Access Control namespace, an OData client must know the Management Service endpoint URL. You can view the Management Service endpoint URL on the Management Service page of the ACS Management Portal. In ACS, this endpoint URL is https://YourServiceNamespace.accesscontrol.windows.net/v2/mgmt/service where YourServiceNamespace is the name of your Windows Azure namespace.

You can access the ACS Management Service using Management Service accounts, which are hosted locally on the Access Control namespace. This is most commonly a username and password, but it can also be a certificate or symmetric key used to sign a token that is then used to gain access to the ACS Management Service. The ACS Management Service uses ACS for authentication, where ACS consumes a management credential issued to it using the OAuth WRAP protocol, and then issues a SWT token to the client that is required to access the ACS Management Service.

The following are three types of the ACS Management Service account credentials:

• Passwords—When authenticating with the ACS Management Service, a password is used in a plaintext token request to ACS using the OAuth WRAP protocol. The password field corresponds to the wrap_password parameter in an OAuth WRAP v0.9 token request, where the username field corresponds to the wrap_name parameter. For more information, see “Password token requests” in How to: Request a Token from ACS via the OAuth WRAP Protocol.
  
  
• Symmetric Keys—When authenticating with the ACS Management Service, symmetric keys are used to sign a SWT token sent to ACS using the OAuth WRAP protocol. For more information, see the “SWT token requests” in How to: Request a Token from ACS via the OAuth WRAP Protocol.
  
  
• X.509 Certificates—When authenticating with the ACS Management Service, an X.509 certificate can be used to validate the signature of a SAML bearer token sent to ACS for authentication. For more information, see “SAML token requests” in How to: Request a Token from ACS via the OAuth WRAP Protocol
  
  

You can add and configure management service accounts with the above credentials using the ACS Management Portal. For more information, see ACS Management Portal.

An entity data model organizes the ACS configuration data in the form of records of entity types (or entities) and the associations between them. The data model is described in the OData Service Metadata Document available at: https://<namespace>.accesscontrol.windows.net/v2/mgmt/service/$metadata, where <namespace> is the name of your Access Control namespace.

This XML document uses a conceptual schema definition language (CDSL) to describe the available data. You can download this document and use it to generate typed classes in your code.

For a complete list of all of the ACS entity types and descriptions and their respective properties and descriptions, see ACS Management Service API Reference

Default Entity Data

• Code Sample: Management Service
  
  

Concepts