ACS Management Service
Published: April 7, 2011
Updated: February 21, 2014
Applies To: Windows Azure
Windows Azure Active Directory Access Control (also known as Access Control Service or ACS)
ACS Management Service is an ACS component that allows you to manage and configure the settings in an Access Control namespace programmatically. You can use the ACS Management Service as an alternative or complement to the ACS Management Portal, which provides a graphic user interface for ACS.
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 and Open Data (OData) protocol to manage and configure the ACS components in an Access Control namespace programmatically.
The following diagram illustrates the components of ACS and their relationships.
Programmatic management can be especially effective in scenarios like the following ones.
Adding new tenants to an SaaS service
If you have a software-as-a-service product, such as Office 365, you can write code that runs whenever a new customer signs up for your service. The code works with the ACS Management Service to configure the new tenant for the identity provider that they select. For a working sample of SaaS application source code that adds new tenants to ACS, see http://www.fabrikamshipping.com/.
Deploying solutions—When deploying new solutions, you can add a custom task to configure ACS as part of the deployment. The ACS Management Service can help you automate the deployment and minimize manual configuration tasks 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, if the user interface is rebranded, embedded into a larger management console, or exposed through non-web-based user interface, you can use the ACS Management Service to manage and configure your ACS settings.
Additional features Although most tasks can be performed in the ACS Management Portal, some are available only by using the ACS Management Service. For example, you can add custom OpenID identity providers only by using the ACS Management Service.
Accessing the ACS 2.0 Management Service
To access the ACS Management Service for a particular Access Control namespace, you must provide the Management Service endpoint URL to the OData client.
To find the Management Service endpoint URL for an Access Control namespace, use the following procedure.
Go to the Windows Azure Management Portal, sign in, and then click Active Directory (Troubleshooting tip: "Active Directory" item is missing or not available).
To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)
Click Management service.
The URL appears in the Management Service URL section of the page.
The format for an endpoint URL is https://<Namespace>.accesscontrol.windows.net/v2/mgmt/service where Namespace is the name of your Access Control namespace.
The ACS Management Service uses ACS for authentication. ACS accepts a management credential issued in OAuth WRAP protocol and, in response, issues a SWT token to the client. The SWT token is required for access to the ACS Management Service.
Use any of the following types of account credentials to authenticate to the ACS Management Service:
Passwords—Use OAuth WRAP protocol to send a password in a plaintext token request to ACS. The password field corresponds to the wrap_password parameter in an OAuth WRAP v0.9 token request and 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—Use a symmetric key to sign a SWT token and then use the OAuth WRAP protocol to send the token to ACS. For more information, see the "SWT token requests" in How to: Request a Token from ACS via the OAuth WRAP Protocol.
X.509 Certificates—Use an X.509 certificate 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 all of these credential types in the ACS Management Portal. For more information, see ACS Management Portal.
ACS 2.0 Management Service data entities
An entity data model organizes configuration data into records of entity types (or entities) and the associations between them. The data model for each Access Control namespace 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 the Access Control namespace.
This XML document uses conceptual schema definition language (CSDL) to describe the entity module. You can download this document and use it to generate typed classes in your code.
For more information about the ACS entity types and their properties, see ACS Management Service API Reference.
Default Entity Data
Every Access Control namespace contains default configuration data that is exposed to the ACS Management Service, but is not available in 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 relying parties of the Access Control namespace.
AccessControlManagement Rule Group and Rules—Contains the access rules for the ACS Management Portal and the ACS Management Service. You can configure the rules and rule groups in the ACS Management Portal.
Windows Live ID Identity Provider and Issuer—Represents Windows Live ID (Microsoft account), the default 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.
TasksCode Sample: Management Service
ConceptsACS 2.0 Components
ACS Management Service API Reference
How to: Request a Token from ACS via the OAuth WRAP Protocol
How to: Use ACS Management Service to Configure Facebook as an Internet Identity Provider
How to: Use ACS Management Service to Configure AD FS 2.0 as an Enterprise Identity Provider
How to: Use ACS Management Service to Configure an OpenID Identity Provider