Prepare documentation for ACR and AAD integration

[sajayantony]

Azure Container Registry integration with Azure Active Directory

The Azure Container Registry allows users to manage a private Docker registry on the cloud. Our service enables customers to store and manage container images across all types of Azure deployments, keep container images near deployments to reduce latency and costs, maintain Windows and Linux container images in a single Docker registry, use familiar, open-source Docker command line interface (CLI) tools, and simplify registry access management with Azure Active Directory.

The integration of Azure Container Registry with Azure Active Directory is crucial in order to enable transparent authentication and authorization of users and headless services using AAD credentials. In this scenario, a user will only have to use their AAD credentials to log-in to their private registry, and the Azure Container Service will take care of the authorization validation of each operation using the provided credentials.

Under the hood Azure Container Service utilizes the oauth2 authorization protocol, as described by the Docker Registry v2 authentication via central service documentation as well as the Docker Registry v2 Bearer token specification. The JWT tokens generated by the Azure Container Registry are easy to observe in jwt.io.

Logging into a registry

The process to log in to the registry, from the user's perspective, is simple. The user will use the Microsoft Azure CLI 2.0:

az acr login -n contosoregistry

Internally, the CLI will follow these steps:

1. Calls to Azure Resource Manager to resolve the login server for the specified registry.
2. Obtains refresh credentials from the profile in use. For a headless call, this will give you the registered SPN, for a regular user this will give you a refresh token.
3. Makes an HTTPS GET call to the registry server's /v2 endpoint, without credentials. A bearer token authentication challenge is expected, specifying realm and service values. The realm contains the authentication server's URL.
4. Makes an HTTPS POST call to the authentication server's /oauth2/exchange endpoint, with a body indicating the grant type, the service, the tenant, and the credentials.
5. From the server's response, we extract an Azure Container Registry refresh token.
6. Pass the refresh token as the password to the Docker CLI, using a null GUID as the username and calling docker login. From here on, the docker CLI takes care of the authorization cycle using oauth2.

At the end Docker will store the refresh token and go through the oauth2 flow on each operation it does against the Azure Container Registry.

Listing a repository

The Microsoft Azure CLI 2.0 allows users to also list the repositories registries, and list tags for a repository in a registry. Here's how users can achieve listing the repositories in a registry:

az acr repository list -n contosoregistry

Internally, the CLI will follow these steps:

1. Calls to Azure Resource Manager to resolve the login server for the specified registry.
2. Obtains refresh credentials from the profile in use. For a headless call, this will give you the registered SPN, for a regular user this will give you a refresh token.
3. Makes an HTTPS GET call to the registry server's /v2 endpoint, without credentials. A bearer token authentication challenge is expected, specifying realm and service values. The realm contains the authentication server's URL.
4. Makes an HTTPS POST call to the authentication server's /oauth2/exchange endpoint, with a body indicating the grant type, the service, the tenant, and the credentials.
5. From the server's response we extract an Azure Container Registry refresh token.
6. Makes an HTTPS POST call to the authentication server's /oauth2/token endpoint, with a body indicating the grant type, the service, the scope, and the Azure Container Registry refresh token.
7. From the server's response we extract an Azure Container Registry access token.
8. Makes an HTTPS GET call to the registry server's /v2/_catalog endpoint using the access token as the bearer token.
9. Obtains the data from the service and displays it.

When listing the tags of a repository, every step above is the same except for the call to the endpoint that gives the tags which is /v2/contosoregistry/tags/list instead of /v2/_catalog.

Azure Container Registry Refresh Token and Access Token

Let's follow an example call to list a repository:

az acr repository list -n contosoregistry

This will produce a JWT refresh token with the following payload:

{
  "jti": "365e3b5b-844e-4a21-a38c-4d8aebdd6a06",
  "nbf": 1488413863,
  "exp": 1488417456,
  "iat": 1488413863,
  "iss": "Azure Container Registry",
  "aud": "contosoregistry-contoso.azurecr.io",
  "version": "1.0",
  "grant_type": "refresh_token",
  "tenant": "f686d426-8d16-42db-81b7-ab578e110ccd",
  "credential": "AQA...iAA"
}

Followed by an access token with the following payload:

{
  "jti": "ec425c1e-7eda-4f70-adb5-19f927e34a41",
  "nbf": 1488413866,
  "exp": 1488417464,
  "iat": 1488413866,
  "iss": "Azure Container Registry",
  "aud": "contosoregistry-contoso.azurecr.io",
  "access": [
    {
      "type": "registry",
      "name": "catalog",
      "actions": [
        "*"
      ]
    }
  ]
}

[DavidObando]

/cc @shhsu @yuwaMSFT2

Feedback welcome. This is still in progress.

Actually, we moved here --> #32

[DavidObando]

Actually, we moved here --> #32