<p>Die Authentifizierung am Windows Azure Active Directory haben wir sowohl bereits <a href="http://code-inside.de/blog/2013/12/01/windows-azure-active-directory-asp-net-tooling-ein-blick-hinter-die-kulissen/">mit dem Tooling</a> als <a href="http://code-inside.de/blog/2013/11/10/windows-azure-active-directoryauthentifizierung-nur-code-erste-schritte-mit-der-graph-api/">auch via Code</a> gesehen. Heute geht es darum, wie man Daten lesen und sogar auch schreiben kann.</p>
Windows Azure Active Directory?
<p>Wer keine Ahnung von der Begrifflichkeit hat, dem empfehle ich ebenfalls die beiden vorangegangen Blogposts oder schaut einfach auf <a href="http://www.windowsazure.com/en-us/documentation/services/active-directory/">dieser Azure Info Seite</a>. </p>
Welche Ressourcen befinden sich da?
<p>Im Azure AD befinden sich folgende Entitäten:</p>
<p>- Users<br />
- Groups<br />
- Contacts<br />
- Roles</p>
Zugriff auf das Directory oder auf den “Directory Graph”
<p>Trotz des “Active Directory” im Namen und den bekannten Entitäten hat dieser Azure Dienst wenig Gemeinsamkeiten zu einem herkömmlichen Active Directory. Der vermutlich grösste Unterschied: Es gibt kein LDAP Zugriff – es ist eine <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974478.aspx">REST API</a>. Die Daten liegen im so genannten <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974476.aspx">Windows Azure Active Directory Graph</a>. Anwendungen die jetzt gegen ein Active Directory funktionieren müssen umgeschrieben werden für Windows Azure AD. </p>
REST … oder auch OData
<p>Als Endpunkt gibt es eine REST bzw. eine <a href="http://www.odata.org/">OData API</a>. Ob OData der eleganteste Weg ist steht auf einem anderen Papier – allerdings arbeitet das Team daran weitere <a href="http://blogs.msdn.com/b/aadgraphteam/archive/2013/09/18/enhancing-graph-api-queries-with-additional-odata-supported-queries.aspx">OData Features mit zu unterstützen.</a></p>
<p>Grundsätzlich gibt es zwei Arten von Queries: </p>
<p><a href="http://msdn.microsoft.com/en-us/library/windowsazure/jj126255.aspx">“Common Queries”</a>: Eine recht einfache API mit der man alle Daten aus dem AD rausholen kann.</p>
<p><a href="http://msdn.microsoft.com/en-us/library/windowsazure/jj836245.aspx">“Differential Queries”</a>: Diese API wird interessant wenn man grosse Datenmengen zwischen der eigenen Anwendung und dem Azure AD synchronisieren möchte. Über diese API kann man nur die Änderungen an einer Ressource zwischen zwei Requests herausbekommen.</p>
Aktuell: Kein nettes NuGet Package
<p>Jetzt weg von der Theorie, hin zur Praxis. Aktuell gibt es leider kein NuGet Package oder ähnliches was die Arbeit mit der Graph API komplett vereinfacht. Zwar gibt es ein <a href="http://www.nuget.org/packages/Auth10.WindowsAzureActiveDirectory/">altes NuGet Package</a>, allerdings stammt dies auch nur aus Sample Code und zudem ist die API entsprechend schon recht alt und untersützt nicht alle Funktion die es heute gibt (Gruppen-Management z.B.)</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1968.png"></a> </p>
Alternative: Hand Made Requests
<p>Da es eine REST API ist, benötigt man natürlich nur einen HttpClient und man kann dagegen entwickeln. Die <a href="http://msdn.microsoft.com/en-us/library/windowsazure/dn151678.aspx">MSDN</a> gibt auch genügend Beispiele wie der Request aussehen kann:</p>
GET https://graph.windows.net/contoso.onmicrosoft.com/users/Alex@contoso.onmicrosoft.com?api-version=2013-04-05 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
<p>Da sich die API allerdings recht schnell weiter entwickelt und ich mir die “OData”-like Queries nicht von Hand zusammenschrauben möchte, gibt es noch einen Weg. Dieser scheint wohl mehr oder minder auch der “empfohlene” Weg zu sein.</p>
Zum Code: Wir nutzen Sample Code – uhh oh…
<p>Das Azure Graph Team publiziert auf <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974459.aspx">dieser MSDN</a> Seite verschiedene Beispiele, darunter auch eine “Graph API Helper Library”. Im Einsatz kommt diese Library auch im <a href="http://code.msdn.microsoft.com/Write-Sample-App-for-79e55502">.NET Sample</a>.</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1969.png"></a>Das Sample ist eine MVC Anwendung, welche ein CRUD auf User und Groups abbildet. Der GraphHelper enthält die generierte “DataService” aus dem <a href="https://graph.windows.net/contoso.com/$metadata?api-version=2013-04-05">OData-Endpunkt</a> und einige Utilities drum herum – so kann man recht einfach sich gegen die Graph API authentifizieren und Requests abschicken.</p>
<p>Das Sample kommt mit voreingestellten Settings – allerdings ist die App nur “lesend” auf das AD berechtigt.</p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p>Mal ein paar Screenshots von der Applikation:</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1970.png"></a> </p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1971.png"></a> </p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1972.png"></a> </p>
Generierter Code… uh…
<p></p>
<p>Der “generierte” Code stammt aus dem <a href="https://graph.windows.net/contoso.com/$metadata?api-version=2013-04-05">OData Endpunkt</a> und ist alles andere als “schön”. Dazu gibt es noch eine “Partial” Klasse, da die generierte Klasse die eigentlichen Entitäten nicht erkennt. </p>
<p>Der eigentliche Code ist nicht sehr komplex, aber vom Syntax nicht ganz so sexy.</p>
<p>So holt man z.B. alle Gruppen ab:</p>
//
// GET: /Group/
// Get: /Group?$skiptoken=xxx
// Get: /Group?$filter=DisplayName eq 'xxxx'
public ActionResult Index(string displayName, string skipToken)
{
QueryOperationResponse response;
var groups = DirectoryService.groups;
// If a filter query for displayName is submitted, we throw away previous results we were paging.
if (displayName != null)
{
ViewBag.CurrentFilter = displayName;
// Linq query for filter for DisplayName property.
groups = (DataServiceQuery)(groups.Where(group => group.displayName.Equals(displayName)));
response = groups.Execute() as QueryOperationResponse;
}
else
{
// Handle the case for first request vs paged request.
if (skipToken == null)
{
response = groups.Execute() as QueryOperationResponse;
}
else
{
response = DirectoryService.Execute(new Uri(skipToken)) as QueryOperationResponse;
}
}
List groupList = response.ToList();
// Handle the SkipToken if present in the response.
if (response.GetContinuation() != null)
{
ViewBag.ContinuationToken = response.GetContinuation().NextLinkUri;
}
return View(groupList);
}
Empfehlung: Sample anschauen und nicht direkt auf die generierten Klassen verweisen
<p>Das Sample enthält die “Common Queries” plus CRUD-Operations und bietet einen einfachen Einstieg. Ich würde aber davon abraten direkt die Entitäten daraus zu nutzen, da die generierten Klassen auch “Unschönheiten” wie z.B. kleine Property-Namen mitbringen.</p>
<p>Weitere Informationen findet man in der <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974476.aspx">MSDN auf der Graph API Seite</a>.</p>
Windows Azure Active Directory?
<p>Wer keine Ahnung von der Begrifflichkeit hat, dem empfehle ich ebenfalls die beiden vorangegangen Blogposts oder schaut einfach auf <a href="http://www.windowsazure.com/en-us/documentation/services/active-directory/">dieser Azure Info Seite</a>. </p>
Welche Ressourcen befinden sich da?
<p>Im Azure AD befinden sich folgende Entitäten:</p>
<p>- Users<br />
- Groups<br />
- Contacts<br />
- Roles</p>
Zugriff auf das Directory oder auf den “Directory Graph”
<p>Trotz des “Active Directory” im Namen und den bekannten Entitäten hat dieser Azure Dienst wenig Gemeinsamkeiten zu einem herkömmlichen Active Directory. Der vermutlich grösste Unterschied: Es gibt kein LDAP Zugriff – es ist eine <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974478.aspx">REST API</a>. Die Daten liegen im so genannten <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974476.aspx">Windows Azure Active Directory Graph</a>. Anwendungen die jetzt gegen ein Active Directory funktionieren müssen umgeschrieben werden für Windows Azure AD. </p>
REST … oder auch OData
<p>Als Endpunkt gibt es eine REST bzw. eine <a href="http://www.odata.org/">OData API</a>. Ob OData der eleganteste Weg ist steht auf einem anderen Papier – allerdings arbeitet das Team daran weitere <a href="http://blogs.msdn.com/b/aadgraphteam/archive/2013/09/18/enhancing-graph-api-queries-with-additional-odata-supported-queries.aspx">OData Features mit zu unterstützen.</a></p>
<p>Grundsätzlich gibt es zwei Arten von Queries: </p>
<p><a href="http://msdn.microsoft.com/en-us/library/windowsazure/jj126255.aspx">“Common Queries”</a>: Eine recht einfache API mit der man alle Daten aus dem AD rausholen kann.</p>
<p><a href="http://msdn.microsoft.com/en-us/library/windowsazure/jj836245.aspx">“Differential Queries”</a>: Diese API wird interessant wenn man grosse Datenmengen zwischen der eigenen Anwendung und dem Azure AD synchronisieren möchte. Über diese API kann man nur die Änderungen an einer Ressource zwischen zwei Requests herausbekommen.</p>
Aktuell: Kein nettes NuGet Package
<p>Jetzt weg von der Theorie, hin zur Praxis. Aktuell gibt es leider kein NuGet Package oder ähnliches was die Arbeit mit der Graph API komplett vereinfacht. Zwar gibt es ein <a href="http://www.nuget.org/packages/Auth10.WindowsAzureActiveDirectory/">altes NuGet Package</a>, allerdings stammt dies auch nur aus Sample Code und zudem ist die API entsprechend schon recht alt und untersützt nicht alle Funktion die es heute gibt (Gruppen-Management z.B.)</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1968.png"></a> </p>
Alternative: Hand Made Requests
<p>Da es eine REST API ist, benötigt man natürlich nur einen HttpClient und man kann dagegen entwickeln. Die <a href="http://msdn.microsoft.com/en-us/library/windowsazure/dn151678.aspx">MSDN</a> gibt auch genügend Beispiele wie der Request aussehen kann:</p>
GET https://graph.windows.net/contoso.onmicrosoft.com/users/Alex@contoso.onmicrosoft.com?api-version=2013-04-05 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
<p>Da sich die API allerdings recht schnell weiter entwickelt und ich mir die “OData”-like Queries nicht von Hand zusammenschrauben möchte, gibt es noch einen Weg. Dieser scheint wohl mehr oder minder auch der “empfohlene” Weg zu sein.</p>
Zum Code: Wir nutzen Sample Code – uhh oh…
<p>Das Azure Graph Team publiziert auf <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974459.aspx">dieser MSDN</a> Seite verschiedene Beispiele, darunter auch eine “Graph API Helper Library”. Im Einsatz kommt diese Library auch im <a href="http://code.msdn.microsoft.com/Write-Sample-App-for-79e55502">.NET Sample</a>.</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1969.png"></a>Das Sample ist eine MVC Anwendung, welche ein CRUD auf User und Groups abbildet. Der GraphHelper enthält die generierte “DataService” aus dem <a href="https://graph.windows.net/contoso.com/$metadata?api-version=2013-04-05">OData-Endpunkt</a> und einige Utilities drum herum – so kann man recht einfach sich gegen die Graph API authentifizieren und Requests abschicken.</p>
<p>Das Sample kommt mit voreingestellten Settings – allerdings ist die App nur “lesend” auf das AD berechtigt.</p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p> </p>
<p>Mal ein paar Screenshots von der Applikation:</p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1970.png"></a> </p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1971.png"></a> </p>
<p><a href="http://code-inside.de/blog/wp-content/uploads/image1972.png"></a> </p>
Generierter Code… uh…
<p></p>
<p>Der “generierte” Code stammt aus dem <a href="https://graph.windows.net/contoso.com/$metadata?api-version=2013-04-05">OData Endpunkt</a> und ist alles andere als “schön”. Dazu gibt es noch eine “Partial” Klasse, da die generierte Klasse die eigentlichen Entitäten nicht erkennt. </p>
<p>Der eigentliche Code ist nicht sehr komplex, aber vom Syntax nicht ganz so sexy.</p>
<p>So holt man z.B. alle Gruppen ab:</p>
//
// GET: /Group/
// Get: /Group?$skiptoken=xxx
// Get: /Group?$filter=DisplayName eq 'xxxx'
public ActionResult Index(string displayName, string skipToken)
{
QueryOperationResponse response;
var groups = DirectoryService.groups;
// If a filter query for displayName is submitted, we throw away previous results we were paging.
if (displayName != null)
{
ViewBag.CurrentFilter = displayName;
// Linq query for filter for DisplayName property.
groups = (DataServiceQuery)(groups.Where(group => group.displayName.Equals(displayName)));
response = groups.Execute() as QueryOperationResponse;
}
else
{
// Handle the case for first request vs paged request.
if (skipToken == null)
{
response = groups.Execute() as QueryOperationResponse;
}
else
{
response = DirectoryService.Execute(new Uri(skipToken)) as QueryOperationResponse;
}
}
List groupList = response.ToList();
// Handle the SkipToken if present in the response.
if (response.GetContinuation() != null)
{
ViewBag.ContinuationToken = response.GetContinuation().NextLinkUri;
}
return View(groupList);
}
Empfehlung: Sample anschauen und nicht direkt auf die generierten Klassen verweisen
<p>Das Sample enthält die “Common Queries” plus CRUD-Operations und bietet einen einfachen Einstieg. Ich würde aber davon abraten direkt die Entitäten daraus zu nutzen, da die generierten Klassen auch “Unschönheiten” wie z.B. kleine Property-Namen mitbringen.</p>
<p>Weitere Informationen findet man in der <a href="http://msdn.microsoft.com/en-us/library/windowsazure/hh974476.aspx">MSDN auf der Graph API Seite</a>.</p>