Introductie

Deze pagina beschrijft hoe je Microsoft Active Directory (AD) als 'Group Provider' kunt inrichten. Hierdoor kan groepsinformatie rechtstreeks vanuit de AD via SURFconext naar bepaalde Service Providers worden doorgestuurd.

Een 'Group Provider' is een REST-service die op basis van basic authentication informatie verstrekt middels het VOOT-protocol.

Een simpele manier om een 'Group Provider' op te zetten is:

1. Installeer een server met IIS (Internet Information Service)
2. Maak een .NET project op basis van het WCF Service Application, met daarin een REST Service
3. Zorgt dat het .NET project antwoordt nav. 2 typen REST calls
4. Deploy het .NET project in IIS
5. Beveilig ISS oa. dmv. Basic Authentication 

De calls gestuurd naar uw 'Group Provider' komen van de SURFconext groeps-omgeving voot.surfconext.nl en zijn:

Stap 1: Installeer IIS

Bij het installeren van IIS voor de 'Group Provider' kan gebruik gemaakt worden van de standaard IIS installatie/rol.

Aandachtspunten zijn:

• De IIS server zal via LDAP (vanuit het .NET project) contact moeten kunnen leggen met de Active Directory omgeving (Zonder SSL via poort 389, met SSL - LDAPS, poort 636).
• De IIS server zal benaderd moeten kunnen worden vanaf de SURFconext groeps-omgeving (voot.surfconext.nl; 145.100.191.192/26 & 2001:610:188:426::/64).


Stap 2: Maken .NET project

Creëer een nieuw .NET project met daarin een RESTfull Service. Een voorbeeld is te vinden op: http://www.topwcftutorials.net/2013/09/simple-steps-for-restful-service.html.

Stap 3: Pas .NET project aan voor VOOT2/Group Provider

De call die door de groepenomgeving van SURFconext naar uw 'Group Provider' wordt gestuurd is: /groups/{groupid}/{userid}.

Hierbij is {groupid} de volledige identifier van de groep zoals bijvoorbeeld: urn:collab:group:example.org:nl:surfnet:diensten:groupname1

{userid} is de UID van de gebruiker, zoals: urn:collab:person:example.org:user1

Door het OperationContract in het .NET project aan te passen is het mogelijk de waarden van uit de call (in de URI/URL) te gebruiken binnen het project:

[OperationContract]
[WebInvoke(Method = "GET", ResponseFormat = WebMessageFormat.Xml,
BodyStyle = WebMessageBodyStyle.Bare,
UriTemplate = "user/{userid}/group/{groupid}")]

Door middel van LDAP is het nu mogelijk om te kijken om gebruiker met {userid} lid is van een groep met de naam {groupid}. Om verbinding te maken met de LDAP-server heb je de component LDAP library for C#.NET nodig. 

Er kan gebruik gemaakt worden van de volgende code om in Active Directory to zoeken of een gebruiker lid is van een bepaalde groep. Let op dat deze code niet compleet is en aanpassingen behoeft mbt. AD-domein en groups-locatie in de AD.

Introductie

Met de kennis van het VOOT-protocol in het achterhoofd heeft SURFnet een simpele webdienst geïmplementeerd om toegang te krijgen tot Microsoft Active Directory (AD) als Group Provider. SURFnet gebruikt hiervoor het LDAP-protocol. Voor de ontwikkeling van dit protocol is Microsoft Visual Studio 2010 gebruikt. Het project is gebaseerd op het 'WCF REST Services Project Template'.

Om verbinding te maken met de LDAP-server heb je de component LDAP library for C#.NET nodig. De AD-server wordt opgezet met de standaardconfiguratie, die de mappen 'Builtin' en 'Users' bevat.

Op dit moment ondersteunt deze tutorial alleen bepaalde delen van het VOOT-protocol.

Methoden

De onderstaande methoden worden op dit moment ondersteund:

• toon mijn eigen groepen - HTTP GET naar '/groups/@me'
• toon alle deelnemers van een van mijn eigen groepen - HTTP GET naar '/people/@me/[groep-id]'
• toon een bepaald persoon - HTTP GET naar '/people/[gebruiker-id]'

De code voor deze methoden is als volgt:

    public class VootService
    {
        private readonly IVootReader reader;

        public VootService()

public static List<string> GetUserGroupDetails(string userName)
        {
			DirectoryEntry entry = new DirectoryEntry("LDAP://CN=users,DC=fabrikam,DC=com");
            DirectorySearcher search = new DirectorySearcher(entry);
            List<string> groupsList = new List<string>();{
            search.Filterreader = String.Format("(cn={0})", userNamenew LdapVootReader(new ConfigurationHelper());
            search.PropertiesToLoad.Add("memberOf");}

            SearchResult result = search.FindOne();[WebGet(UriTemplate = "groups/@me")]
        public string   if (result != nullIsMemberOf()
            {
                int groupCount = result.Properties["memberOf"].Count;

return reader.IsMemberOf(currentUser);
        }

        for [WebGet(intUriTemplate counter = 0; counter < groupCount; counter++)= "people/{userId}")]
                {
                    string s = (string)result.Properties["memberOf"][counter];public string GetMember(string userId)
        {
            return groupsListreader.AddGetMember(suserId);
        }

        [WebGet(UriTemplate =   "people// _log.DebugFormat("found group for user {0} : {1}", userName, s);

@me/{groupId}")]
        public string       }
            }
            else
  GetGroupMembers(string groupId)
          {
            return    _log.Warn("no groups found for user " + userNamereader.GetGroupMembers(groupId);
            }
            return groupsList;
        }

Voorbeelden van de VOOT2-JSON uitvoer zien er zo uit:

• Geen groep gevonden = lege JSON:

[]

Alle resultaten worden geretourneerd in JSON-formaat.

Toon mijn eigen groepen

De 'VootReader'-klasse bevat de methode 'isMemberOf(userId)'. Deze retourneert alle groepen waar de gebruiker lid van is. De LDAP-bron wordt doorzocht vanuit 'CN=Users, DN=demo, ..., DN=nl' met het filter 'samAccountName='[gebruiker-id]'.

Het attribuut 'memberOf' retourneert een 'array' met alle groepen waar de gebruiker lid van is. Dat kan er bijvoorbeeld zo uitzien

...

:

{
  "id": "id1",
  "displayName": "display name 1",
  "membership": {
    "basic": "member"
  },
  "description": "description...1"
}

• Meerdere groepen gevonden:

[
  {
    "id": "id1",
    "displayName": "display name 1",
    "membership": {
      "basic": "member"
    },
    "description": "description...1"
  },
  {
    "id": "id2",
    "displayName": "display name 2",
    "membership": {
      "basic": "member"
    },
    "description": "description...2"
  }
]

Stap 4: Toevoegen .NET project aan IIS

Na het maken van het .NET project kan deze worden toegevoegd aan de IIS-webserver. Zie hiervoor de stappen zoals beschreven in: http://www.iis.net/learn/application-frameworks/scenario-build-an-aspnet-website-on-iis/configuring-step-1-install-iis-and-asp-net-modules#12.

Stap 5: Configuratie Basic Authentication + beperking toegang op basis van IP-adressen

De nieuwe 'Group Provider' dient te worden geconfigureerd in de SURFconext groepenomgeving. Om te zorgen dat alleen SURFconext met deze dienst kan communiceren (eventuele Service Providers communiceren altijd via het SURFconext-platform) wordt gebruik gemaakt van Basic Authentication in IIS en een restrictie van de servers die contact mogen leggen vanaf bepaalde IP-adressen.

Basic Authentication

Voer de volgende stappen uit om Basic Authentication aan te zetten op de web site van de 'Group Provider':

1. Open IIS manager en ga naar de web site.
2. Open de 'Features View' en dubbelklik op Authentication.
3. Op de Authentication pagina selecteer 'Basic Authentication'.
4. In het Actions paneel selecteer Enable om de Basic Authentication te gebruiken met de standaard instellingen.
5. Disable alle andere authenticatiemethoden.
6. Klik met rechts op Basic Authentication en selecteer Edit.
7. Geeft het standaard Active Directory domein aan in het veld Domein. Er hoeft geen realm geconfigureerd te worden.
8. Klik op OK.
9. Pas de permissies aan voor de website, zodat alleen een gespecificeerde gebruiker toegang heeft tot de website.

10. Geef de naam en het wachtwoord van deze gebruiker door aan SURFconext (via support@surfconext.nl)

IP-adres restrictie

Om te zorgen dat alleen de SURFconext groepenomgeving verbinding mag maken met de website voer de volgende stappen uit:

1. Open IIS manager en ga naar de Website.
2. Open de 'Features View' en dubbelklik op IP Address and Domain Restrictions.
3. Klik bij Actions op 'Add Allow Entry'.
4. Selecteer 'IP address range'.
5. IP adres: 145.100.191.192.
6. Mask: 255.255.255.192.
7. Klik OK.
8. Klik bij Actions op 'Add Allow Entry'.
9. Selecteer 'IP address range'.
10. IP adres: 2001:610:188:426::
11. Mask: 64.
12. Klik OK.

...

"CN=TestGroup,CN=Users,DC=demo,DC=..,DC=..,DC=surfnet,DC=nl",

"CN=DemoGroup,CN=Users,DC=demo,DC=..,DC=..,DC=surfnet,DC=nl",

"CN=Administrators,CN=Builtin,DC=demo,DC=..,DC=..,DC=surfnet,DC=nl"

}

Alle elementen uit de 'array' worden verwerkt door het verkrijgen van de enige 'LDAP-'entry' die gelijk is aan de eerste 'common name' (CN).

Toon alle leden van 1 van mijn groepen

De methode 'GetGroupMembers' retourneert alle leden van de opgegeven groep. De LDAP-zoektermen zijn gelijk aan de vorige methode, omdat in dit geval de groepen onderdeel zijn van de 'Users'-map. Maak gebruik van 'groupId' als deel van het filter.

Opnieuw wordt het resultaat geretourneerd als een 'array', maar ditmaal als waarde van het 'member'-attribuut.

Toon een bepaald persoon

De methode 'GetMember' retourneert de gegevens van de desbetreffende gebruiker. Het belangrijkste onderdeel van de methode is:

// Get the entry.
LdapEntry entry = GetEntry(id, configHelper.PeopleDn);

// Process the result.
if (entry != null)
{
    LdapAttribute attr = entry.getAttribute("displayName");
    if (attr != null)
    {
        result = new Person { DisplayName = attr.StringValue, Id = id };
    }
}

Authenticatie

Voor het authenticeren van het eindpunt van de gebruiker gebruiken we '3-legged OAuth versie 1.0a'. Om Single Sign On mogelijk te maken tussen de Service Provider, SURFconext en het externegroepen-eindpunt, moet je de OAuth Provider (deze is verantwoordelijk voor het aanmaken en uitdelen van toegangs-'tokens' na een succesvolle authenticatie) koppelen met SURFconext.

Hiervoor zijn verschillende.NET-componenten beschikbaar. SURFconext maakt gebruik van het component DotNetOpenAuth. Een voorbeeld hiervan is een 'OpenAuthServiceProvider'. Dit voorbeeld hebben we als basis gebruikt voor de OAuth/implementatie. Het bevat een ASP.NET handler door de 3-legged OAuth handshake. Vervolgens wordt er een VOOT-webservice aan toegevoegd. Met een aparte webapplicatie kun je de functionaliteit van de implementatie testen.

Todo

• Voeg extra VOOT-parameters toe: count, filterBy, filterOp, filterValue, sortOrder, startIndex.
• Voeg de code toe aan de GitHub directory

'IP and Domain Restrictions' wordt niet standaard mee 'geinstalleerd' in de Server Rol 'Webserver (IIS)'. Deze feature dient eerst aan de rol toegevoegd worden

...