ACS Management Service
Published: April 7, 2011
Updated: February 28, 2013
Applies To: Windows Azure
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.
Accessing the ACS 2.0 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.
ACS 2.0 Management Service data entities
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
By default, every Access Control namespace contains configuration data that is visible via the ACS Management Service, but not via the ACS Management Portal. This configuration data is typically used internally by the Access Control namespace and is not related to custom relying party applications. This data includes:
AccessControlManagement Relying Party Application—Represents the ACS Management Portal and the ACS Management Service, which are a relying party of the Access Control namespace in the same way custom relying party applications are.
AccessControlManagement Rule Group and Rules—Contains the access rules for the ACS Management Portal and the ACS Management Service. These are configurable in the Administration section of the ACS Management Portal.
Windows Live ID Identity Provider and Issuer—Represents the default Windows Live ID (Microsoft account) identity provider and issuer. This identity provider cannot be deleted, because it is used by the AccessControlManagement relying party for authentication to the ACS Management Portal.
LOCAL_AUTHORITY Issuer—Issuer used in the ACS rules engine for claims output by ACS.